Register-PSSessionConfiguration

Register-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirmer] [-WhatIf] [<CommonParameters>]

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

Description
-----------
Cette commande inscrit la configuration de session NewShell. Elle utilise les paramètres ApplicationName et ApplicationBase pour spécifier l'emplacement du fichier MyShell.dll, qui indique les applets de commande et les fournisseurs présents dans la configuration de session. Elle fait également appel au paramètre ConfigurationTypeName pour spécifier une nouvelle classe qui configure plus en détail la session.

Pour employer cette configuration, les utilisateurs doivent taper « new-pssession -configurationname newshell ».

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

Description
-----------
Cette commande inscrit la configuration MaintenanceShell sur l'ordinateur local. Elle utilise le paramètre StartupScript pour spécifier le script Maintenance.ps1.

Lorsqu'un utilisateur emploie une commande New-PSSession et sélectionne la configuration MaintenanceShell, le script Maintenance.ps1 est exécuté dans la nouvelle session. Le script peut configurer la session, et notamment importer des modules, ajouter des composants logiciels enfichables Windows PowerShell et définir la stratégie d'exécution de la session. Si le script génère des erreurs, telles que des erreurs sans fin d'exécution, la commande New-PSSession échoue.

C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"

C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\AdminShell.ps1

Description
-----------
Cet exemple permet d'inscrire la configuration de session AdminShell. 

La première commande enregistre un SDDL personnalisé dans la variable $sddl. 

La deuxième commande inscrit le nouvel interpréteur de commandes. Elle utilise le paramètre SecurityDescritorSDDL pour spécifier le SDDL dans la valeur de la variable $sddl et le paramètre MaximumReceivedObjectSizeMB pour augmenter la limite de taille définie pour les objets. Elle fait également appel au paramètre StartupScript pour spécifier un script qui configure la session.

Au lieu du paramètre SecurityDescriptorSDDL, vous pouvez utiliser le paramètre ShowSecurityDescriptorUI, qui affiche une feuille de propriétés permettant de définir des autorisations pour la configuration de session. Lorsque vous cliquez sur « OK » dans la feuille de propriétés, l'outil génère un SDDL pour la configuration de session.

C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

C:\PS> $s

   WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}


C:\PS> $s.getType().fullname
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement


C:\PS> $s | format-list -property *

PSPath            : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath      : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName       : MaintenanceShell
PSDrive           : WSMan
PSProvider        : Microsoft.WSMan.Management\WSMan
PSIsContainer     : True
Keys              : {Name=MaintenanceShell}
Name              : MaintenanceShell
TypeNameOfElement : Container


C:\PS> dir wsman:\localhost\plugin

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}
microsoft.powershell      Container            {Name=microsoft.powershell}
microsoft.powershell32    Container            {Name=microsoft.powershell32}

Description
-----------
Cet exemple montre qu'une commande Register-PSSessionConfiguration retourne un objet WSManConfigContainerElement. Il indique également comment rechercher des éléments conteneurs dans le lecteur WSMan:.

La première commande utilise l'applet de commande Register-PSSessionConfiguration pour inscrire la configuration MaintenanceShell. Elle enregistre l'objet retourné par l'applet de commande dans la variable $j.

La deuxième commande affiche le contenu de la variable $s. 

La troisième commande utilise la méthode GetType et sa propriété FullName pour afficher le nom de type de l'objet retourné par Register-PSSessionConfiguration.

La quatrième commande utilise l'applet de commande Format-List pour afficher toutes les propriétés de l'objet retourné par Register-PSSessionConfiguration dans une liste. La propriété PSPath indique que l'objet est stocké dans un répertoire du lecteur WSMan:.

La cinquième commande utilise l'applet de commande Get-ChildItem pour afficher les éléments présents dans le chemin d'accès WSMan:\LocalHost\PlugIn. Ces éléments incluent la nouvelle configuration MaintenanceShell et les deux configurations par défaut fournies avec Windows PowerShell.

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

Description
-----------
Cette commande crée et inscrit la configuration de session WithProfile sur l'ordinateur local. Elle utilise le paramètre StartupScript pour demander à Windows PowerShell d'exécuter le script spécifié dans toute session qui emploie la configuration de session.

Le contenu du script spécifié, Add-Profile.ps1, est également affiché. Le script contient une commande unique qui utilise l'appel de source de type « dot sourcing » pour exécuter le profil CurrentUserAllHosts de l'utilisateur dans la portée actuelle de la session.

Pour plus d'informations sur les profils, consultez about_Profiles. Pour plus d'informations sur l'appel de source de type « dot sourcing », consultez about_Scopes.