Set-PSSessionConfiguration

Article
01/13/2010

Modifie les propriétés d'une configuration de session inscrite.

Syntaxe

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

Description

L'applet de commande Set-PSSessionConfiguration modifie les propriétés des configurations de session inscrites sur l'ordinateur local. Il s'agit d'une applet de commande avancée, conçue pour être employée par les administrateurs système pour la gestion des configurations de session personnalisées des utilisateurs.

Utilisez le paramètre Name pour identifier la configuration à modifier. Employez les autres paramètres pour spécifier de nouvelles valeurs pour les propriétés de la configuration de session. Pour supprimer une valeur de propriété de la configuration (et utiliser la valeur par défaut), entrez une chaîne vide ("") ou la valeur $null pour le paramètre correspondant.

Pour consulter les propriétés d'une configuration de session, utilisez l'applet de commande Get-PSSessionConfiguration ou le fournisseur de Gestion des services Web. Pour plus d'informations sur le fournisseur de Gestion des services Web, tapez « get-help wsman ».

Paramètres

-ApplicationBase <string>

Modifie le chemin d'accès au fichier d'assembly (*.ddl) qui est indiqué dans la valeur du paramètre AssemblyName.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-AssemblyName <string>

Spécifie un autre fichier d'assembly pour la configuration. Entrez le chemin d'accès (facultatif) et le nom d'un fichier d'assembly (.dll) qui définit le type de configuration.

Si vous entrez uniquement le nom, vous pouvez spécifier le chemin d'accès dans la valeur du paramètre ApplicationBase.

Obligatoire ?	true
Position ?	2
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-ConfigurationTypeName <string>

Spécifie un autre type de configuration. Le type que vous indiquez doit implémenter la classe System.Management.Automation.Remoting.PSSessionConfiguration.

Si vous entrez « $null » ou une chaîne vide, la classe DefaultRemotePowerShellConfiguration est utilisée pour la configuration de session.

Obligatoire ?	true
Position ?	3
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-Force

Supprime toutes les invites utilisateur et redémarre le service WinRM sans demander de confirmation. Pour que la modification de la configuration prenne effet, le service doit être redémarré.

Pour empêcher un redémarrage et supprimer l'invite proposant cette opération, utilisez le paramètre NoServiceRestart.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-MaximumReceivedDataSizePerCommandMB <double>

Modifie la limite fixée pour le volume de données pouvant être envoyé à cet ordinateur dans une commande distante unique. Entrez la taille des données en mégaoctets (Mo). La valeur par défaut est 50 Mo.

Si une limite est définie pour la taille des données dans le type de configuration qui est spécifié dans le paramètre ConfigurationTypeName, elle est utilisée et la valeur de ce paramètre est ignorée.

Obligatoire ?	false
Position ?	named
Valeur par défaut	50
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-MaximumReceivedObjectSizeMB <double>

Modifie la limite fixée pour le volume de données pouvant être envoyé à cet ordinateur dans un objet unique. Entrez la taille des données en mégaoctets (Mo). La valeur par défaut est 10 Mo.

Si une limite est définie pour la taille des objets dans le type de configuration qui est spécifié dans le paramètre ConfigurationTypeName, elle est utilisée et la valeur de ce paramètre est ignorée.

Obligatoire ?	false
Position ?	named
Valeur par défaut	10
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-Name <string>

Spécifie le nom de la configuration de session à modifier.

Vous ne pouvez pas utiliser ce paramètre pour modifier le nom de la configuration de session.

Obligatoire ?	true
Position ?	1
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-NoServiceRestart

Ne redémarre pas le service WinRM et supprime l'invite proposant de le redémarrer.

Par défaut, lorsque vous entrez une commande Set-PSSessionConfiguration, vous êtes invité à redémarrer le service WinRM pour appliquer la nouvelle configuration de session. La nouvelle configuration de session n'est pas effective tant que le service WinRM n'a pas été redémarré.

Pour redémarrer le service WinRM sans demande de confirmation, utilisez le paramètre Force. Pour démarrer le service WinRM manuellement, utilisez l'applet de commande Restart-Service.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-SecurityDescriptorSDDL <string>

Spécifie une autre chaîne au format SDDL (Security Descriptor Definition Language) pour la configuration.

Cette chaîne détermine les autorisations qui sont obligatoires pour l'utilisation de la nouvelle configuration de session. Pour employer une configuration de session dans une session, les utilisateurs doivent au moins disposer de l'autorisation « Exécution(Invoke) » pour cette configuration.

Pour utiliser le descripteur de sécurité par défaut pour la configuration, entrez une chaîne vide ("") ou la valeur $null. La valeur par défaut correspond au SDDL racine dans le lecteur WSMan:.

Si le descripteur de sécurité est complexe, utilisez le paramètre ShowSecurityDescriptorUI au lieu de ce paramètre. Vous ne pouvez pas employer les deux paramètres dans la même commande.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-ShowSecurityDescriptorUI

Affiche une feuille de propriétés vous permettant de créer un nouveau SDDL pour la configuration de session. La feuille de propriétés apparaît lorsque vous entrez la commande Set-PSSessionConfiguration, puis redémarrez le service WinRM.

Lorsque vous définissez les autorisations pour la configuration, n'oubliez pas que les utilisateurs doivent au moins disposer de l'autorisation « Exécution(Invoke) » pour employer la configuration de session dans une session.

Vous ne pouvez pas utiliser le paramètre SecurityDescriptorSDDL et ce paramètre dans la même commande.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-StartupScript <string>

Ajoute ou modifie le script de démarrage de la configuration. Entrez le chemin d'accès complet à un script Windows PowerShell. Le script spécifié est exécuté dans la nouvelle session qui utilise la configuration de session.

Pour supprimer un script de démarrage d'une configuration de session, entrez une chaîne vide ("") ou la valeur $null.

Vous pouvez utiliser un script de démarrage pour configurer plus en détail la session de l'utilisateur. Si le script génère une erreur (même une erreur sans fin d'exécution), la session n'est pas créée et la commande New-PSSession de l'utilisateur échoue.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-ThreadApartmentState <ApartmentState>

Modifie le paramètre d'état de cloisonnement des threads de la session. Les valeurs valides sont STA, MTA et Unknown. La valeur par défaut est Unknown.

Obligatoire ?	false
Position ?	named
Valeur par défaut	ApartmentState.Unknown
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-ThreadOptions <PSThreadOptions>

Modifie le paramètre des options de thread dans la configuration. Ce paramètre détermine la façon dont les threads sont créés et utilisés lorsqu'une commande est exécutée dans la session. Les valeurs valides sont Default, ReuseThread, UseCurrentThread et UseNewThread. La valeur par défaut est UseCurrentThread.

Obligatoire ?	false
Position ?	named
Valeur par défaut	PSThreadOptions.UserCurrentThread
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-Confirmer

Vous invite à confirmer l'exécution de la commande.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

-WhatIf

Décrit le résultat que vous obtiendriez en exécutant la commande, sans réellement l'exécuter.

Obligatoire ?	false
Position ?	named
Valeur par défaut
Accepter l'entrée de pipeline ?	false
Accepter les caractères génériques ?	false

<CommonParameters>

Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.

Entrées et sorties

Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.

Entrées

Aucun

Vous ne pouvez pas diriger d'entrée vers cette applet de commande.

Sorties

Microsoft.WSMan.Management.WSManConfigLeafElement

Remarques

Pour exécuter cette applet de commande sur Windows Vista, Windows Server 2008 et les versions ultérieures de Windows, vous devez ouvrir Windows PowerShell avec l'option Exécuter en tant qu'administrateur.

L'applet de commande Set-PSSessionConfiguration ne modifie pas le nom de configuration et le fournisseur de Gestion des services Web ne prend pas en charge l'applet de commande Rename-Item. Pour modifier le nom d'une configuration, utilisez l'applet de commande Unregister-PSSessionConfiguration afin de supprimer la configuration, puis l'applet de commande Register-PSSessionConfiguration afin de créer et d'inscrire une nouvelle configuration de session.

Vous pouvez employer l'applet de commande Set-PSSessionConfiguration pour modifier les configurations de session Microsoft.PowerShell et Microsoft.PowerShell32 par défaut. Elles ne sont pas protégées. Pour revenir à la version d'origine d'une configuration de session par défaut, utilisez l'applet de commande Unregister-PSSessionConfiguration pour supprimer la configuration de session par défaut, puis l'applet de commande Enable-PSRemoting pour la restaurer.

Exemple 1

C:\PS>set-pssessionconfiguration -name MaintenanceShell -threadApartmentState STA

Description
-----------
Cette commande redéfinit l'état de cloisonnement des threads dans la configuration MaintenanceShell sur STA. La modification est prise en compte lorsque vous redémarrez le service WinRM.

Exemple 2

C:\PS>register-pssessionconfiguration -name AdminShell -assemblyName c:\shells\AdminShell.dll -configurationType AdminClass

C:\PS> set-pssessionconfiguration -name AdminShell -startupScript AdminConfig.ps1

C:\PS> set-pssessionconfiguration -name AdminShell -startupScript $null

Description
-----------
Cet exemple indique comment créer, puis modifier une configuration de session.

La première commande utilise l'applet de commande Register-PSSessionConfiguration pour créer la configuration AdminShell. 

La deuxième commande utilise l'applet de commande Set-PSSessionConfiguration pour ajouter le script AdminConfig.ps1 à la configuration. La modification est prise en compte lorsque vous redémarrez WinRM.

La troisième commande supprime le script AdminConfig.ps1 de la configuration. Elle utilise l'applet de commande Set-PSSessionConfiguration avec la valeur $null pour le paramètre StartupScript.

Exemple 3

C:\PS>Set-PSSessionConfiguration -name foo -MaximumReceivedObjectSizeMB 20

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

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Description
-----------
Cet exemple montre un exemple de sortie de l'applet de commande Set-PSSessionConfiguration. 

La commande Set-PSSessionConfiguration utilisée dans cet exemple porte la valeur de la propriété MaximumReceivedObjectSizeMB à 20. 

La commande Set-PSSessionConfiguration retourne un objet Microsoft.WSMan.Management.WSManConfigLeafElement qui affiche le nom du paramètre et la nouvelle valeur.

Elle vous invite également à redémarrer le service WinRM. La modification apportée par Set-PSSessionConfiguration n'est pas effective tant que le service WinRM n'a pas été redémarré.

Exemple 4

C:\PS>set-pssessionconfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1


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

ParamName            ParamValue
---------            ----------
startupscript        c:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y


C:\PS> get-pssessionConfiguration maintenanceshell | format-list -property *

xmlns            : https://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : c:\ps-test\Maintenance.ps1
ResourceUri      : https://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :


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

ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript c:\ps-test\Maintenance.ps1

Description
-----------
Cette commande présente différentes façons de consulter les résultats d'une commande Set-PSSessionConfiguration.

La première commande utilise l'applet de commande Set-PSSessionConfiguration pour redéfinir le script de démarrage dans la configuration MaintenanceShell sur Maintenance.ps1. La sortie de cette commande montre la modification et vous invite à redémarrer le service WinRM. La réponse est « y » (yes).

La deuxième commande fait appel à l'applet de commande Get-PSSessionConfiguration pour obtenir la configuration de session MaintenanceShell. Elle utilise un opérateur de pipeline (|) pour envoyer les résultats à l'applet de commande Format-List, qui affiche toutes les propriétés de l'objet de configuration de session dans une liste.

La troisième commande utilise le fournisseur de Gestion des services Web pour consulter les paramètres d'initialisation de la configuration MaintenanceShell. Elle fait appel à l'applet de commande Get-ChildItem (alias = dir) pour obtenir les éléments enfants du nœud InitializationParameters pour le plug-in MaintenanceShell.

Pour plus d'informations sur le fournisseur de Gestion des services Web, tapez « get-help wsman ».

Voir aussi

Concepts

about_Session_Configurations
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
Register-PSSessionConfiguration
Unregister-PSSessionConfiguration
WSMan Provider

Partager via