Partager via


Set-PSSessionConfiguration

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

Syntaxe

Set-PSSessionConfiguration
   [-Name] <String>
   [-ApplicationBase <String>]
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-PSSessionConfiguration
   [-Name] <String>
   [-AssemblyName] <String>
   [-ApplicationBase <String>]
   [-ConfigurationTypeName] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-PSSessionConfiguration
   [-Name] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-TransportOption <PSTransportOption>]
   -Path <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

L’applet de commande Set-PSSessionConfiguration modifie les propriétés des configurations de session sur l’ordinateur local.

Utilisez le paramètre Name pour identifier la configuration de session que vous souhaitez modifier. Utilisez 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 une valeur de $Null pour le paramètre correspondant.

À compter de PowerShell 3.0, vous pouvez utiliser un fichier de configuration de session pour définir une configuration de session. Cette fonctionnalité fournit une méthode simple et détectable pour définir et modifier les propriétés des sessions qui utilisent la configuration de session. Pour spécifier un fichier de configuration de session, utilisez le paramètre Path de Set-PSSessionConfiguration. Pour plus d’informations sur les fichiers de configuration de session, consultez about_Session_Configuration_Files. Pour plus d’informations sur la création et la modification d’un fichier de configuration de session, consultez l’applet de commande New-PSSessionConfigurationFile.

Les configurations de session définissent l’environnement des sessions distantes (PSSessions) qui se connectent à l’ordinateur local. Chaque PSSession utilise une configuration de session. La configuration de session détermine les fonctionnalités de l'PSSession, telles que les modules disponibles dans la session, les applets de commande autorisées à s’exécuter, le mode de langage, les quotas et les délais d’expiration. Le descripteur de sécurité de la configuration de session détermine qui peut utiliser la configuration de session pour se connecter à l’ordinateur local. Pour plus d’informations sur les configurations de session, consultez about_Session_Configurations.

Pour afficher les propriétés d’une configuration de session, utilisez l’applet de commande Get-PSSessionConfiguration ou le fournisseur WSMan. Pour plus d’informations sur le fournisseur WSMan, tapez Get-Help WSMan.

Exemples

Exemple 1 : Modifier l’état de l’appartement du thread

PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA

Cette commande remplace l’état de l’appartement du thread dans la configuration MaintenanceShell par STA. La modification est effective lorsque vous redémarrez le service WinRM .

Exemple 2 : Créer et modifier une configuration de session

Cet exemple montre comment ajouter et supprimer un script de démarrage d’une configuration.

La première commande crée la configuration AdminShell. La deuxième commande ajoute le script AdminConfig.ps1 à la configuration. La modification est effective lorsque vous redémarrez WinRM. La troisième commande supprime le script AdminConfig.ps1 de la configuration.

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

Exemple 3 : Afficher les résultats

Cet exemple augmente la valeur de la propriété MaximumReceivedObjectSizeMB à 20. Cette commande vous invite également à redémarrer le service WinRM. La modification n’est pas effective tant que le service WinRM n’est pas redémarré.

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\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

Exemple 4 : Afficher les résultats de différentes façons

Dans cet exemple, modifie le script de démarrage dans la configuration de session MaintenanceShell en . La sortie affiche la modification et vous invite à redémarrer le service WinRM. La réponse est « y » (oui).

Get-PSSessionConfiguration obtient la configuration de session MaintenanceShell. L’opérateur de pipeline (|) envoie les résultats de la commande à Format-List, qui affiche toutes les propriétés de l’objet de configuration dans une liste. Ensuite, à l’aide du fournisseur WSMan, nous affichons les paramètres d’initialisation de la configuration MaintenanceShell . (alias ) obtient les éléments enfants dans le nœud InitializationParameters pour le plug-in MaintenanceShell . Pour plus d’informations sur le fournisseur WSMan, tapez Get-Help wsman.

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

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       :

PS> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

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

Paramètres

-AccessMode

Active et désactive la configuration de session et détermine s’il peut être utilisé pour les sessions distantes ou locales sur l’ordinateur. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • Handicapé. Désactive la configuration de session. Il ne peut pas être utilisé pour l’accès distant ou local à l’ordinateur. Cette valeur définit la propriété Enabled de la configuration de session (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) sur False.
  • Local. Ajoute une entrée Network_Deny_All au descripteur de sécurité de la configuration de session. Les utilisateurs de l’ordinateur local peuvent utiliser la configuration de session pour créer une session de bouclage locale sur le même ordinateur, mais les utilisateurs distants sont refusés.
  • Lointain. Supprime Deny_All et Network_Deny_All entrées des descripteurs de sécurité de la configuration de session. Les utilisateurs d’ordinateurs locaux et distants peuvent utiliser la configuration de session pour créer des sessions et exécuter des commandes sur cet ordinateur.

La valeur par défaut est remote.

D’autres applets de commande peuvent remplacer la valeur de ce paramètre ultérieurement. Par exemple, l’applet de commande Enable-PSRemoting active toutes les configurations de session sur l’ordinateur et autorise l’accès à distance à eux, et l’applet de commande Disable-PSRemoting autorise uniquement l’accès local à toutes les configurations de session sur l’ordinateur.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:PSSessionConfigurationAccessMode
Valeurs acceptées:Disabled, Local, Remote
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ApplicationBase

Spécifie le chemin d’accès du fichier d’assembly (*.dll) spécifié dans la valeur du paramètre AssemblyName.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-AssemblyName

Spécifie le nom de l’assembly. Cette applet de commande crée une configuration de session basée sur une classe définie dans un assembly.

Entrez le nom de fichier ou le chemin complet d’un fichier .dll assembly qui définit une configuration de session. Si vous entrez uniquement le nom de fichier, vous pouvez entrer le chemin d’accès dans la valeur du paramètre ApplicationBase.

Type:String
Position:1
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ConfigurationTypeName

Spécifie le type de la configuration de session définie dans l’assembly dans le paramètre AssemblyName. Le type que vous spécifiez doit implémenter la classe System.Management.Automation.Remoting.PSSessionConfiguration.

Ce paramètre est requis lorsque vous spécifiez un nom d’assembly.

Type:String
Position:2
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Confirm

Vous invite à confirmer avant d’exécuter l’applet de commande.

Type:SwitchParameter
Alias:cf
Position:Named
Valeur par défaut:False
Obligatoire:False
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 invite. Le redémarrage du service rend la modification de configuration effective.

Pour empêcher un redémarrage et supprimer l’invite de redémarrage, utilisez le paramètre NoServiceRestart.

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-MaximumReceivedDataSizePerCommandMB

Spécifie la limite de la quantité de données qui peuvent être envoyées à cet ordinateur dans n’importe quelle commande distante unique. Entrez la taille des données en mégaoctets (Mo). La valeur par défaut est de 50 Mo.

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

Type:Double
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-MaximumReceivedObjectSizeMB

Spécifie les limites relatives à la quantité de données qui peuvent être envoyées à cet ordinateur dans n’importe quel objet unique. Entrez la taille des données en mégaoctets. La valeur par défaut est de 10 Mo.

Si une limite de taille d’objet est définie dans le type de configuration spécifié dans le paramètre ConfigurationTypeName, la limite dans le type de configuration est utilisée. La valeur de ce paramètre est ignorée.

Type:Double
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ModulesToImport

Spécifie les modules et les composants logiciels enfichables qui sont automatiquement importés dans des sessions qui utilisent la configuration de session. Entrez les noms du module et du composant logiciel enfichable.

Par défaut, seul le composant logiciel enfichable Microsoft.PowerShell.Core est importé dans les sessions, mais sauf si les applets de commande sont exclues, vous pouvez utiliser les applets de commande Import-Module et Add-PSSnapin pour ajouter des modules et des composants logiciels enfichables à la session.

Les modules spécifiés dans cette valeur de paramètre sont importés en plus des modules spécifiés dans le fichier de configuration de session (New-PSSessionConfigurationFile). Toutefois, les paramètres du fichier de configuration de session peuvent masquer les commandes exportées par des modules ou empêcher les utilisateurs de les utiliser.

Les modules spécifiés dans cette valeur de paramètre remplacent la liste des modules spécifiés à l’aide du paramètre ModulesToImport de l’applet de commande Register-PSSessionConfiguration.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:Object[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Name

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.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-NoServiceRestart

Ne redémarre pas le service WinRM et supprime l’invite de redémarrage du service.

Par défaut, lorsque vous exécutez Set-PSSessionConfiguration, vous êtes invité à redémarrer le service WinRM pour rendre la nouvelle configuration de session effective. Tant que le service WinRM n’est pas redémarré, la nouvelle configuration de session n’est pas effective.

Pour redémarrer le service WinRM sans invite, utilisez le paramètre Force. Pour redémarrer manuellement le service WinRM , utilisez l’applet de commande .

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Path

Spécifie le chemin d’accès d’un fichier de configuration de session (.pssc), tel qu’un créé par l’applet de commande New-PSSessionConfigurationFile. Si vous omettez le chemin d’accès, la valeur par défaut est le répertoire actif.

Pour plus d’informations sur la modification d’un fichier de configuration de session, consultez la rubrique d’aide de l’applet de commande New-PSSessionConfigurationFile.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-PSVersion

Spécifie la version de PowerShell dans les sessions qui utilisent cette configuration de session.

La valeur de ce paramètre est prioritaire sur la valeur de la clé PowerShellVersion dans le fichier de configuration de session.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:Version
Alias:PowerShellVersion
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-RunAsCredential

Spécifie les informations d’identification des commandes dans la session. Par défaut, les commandes s’exécutent avec les autorisations de l’utilisateur actuel.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:PSCredential
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-SecurityDescriptorSddl

Spécifie une chaîne SDDL (Security Descriptor Definition Language) différente pour la configuration.

Cette chaîne détermine les autorisations requises pour utiliser la nouvelle configuration de session. Pour utiliser une configuration de session dans une session, les utilisateurs doivent disposer au moins de l’autorisation Execute(Invoke) pour la configuration.

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

Si le descripteur de sécurité est complexe, envisagez d’utiliser le paramètre ShowSecurityDescriptorUI au lieu de celui-ci. Vous ne pouvez pas utiliser les deux paramètres dans la même commande.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-SessionTypeOption

Spécifie les options spécifiques au type de la configuration de session. Entrez un objet options de type de session, tel que l’objet PSWorkflowExecutionOption retourné par l’applet de commande New-PSWorkflowExecutionOption.

Les options des sessions qui utilisent la configuration de session sont déterminées par les valeurs des options de session et les options de configuration de session. Sauf indication contraire, les options définies dans la session, telles que l’utilisation de l’applet de commande New-PSSessionOption, sont prioritaires sur les options définies dans la configuration de session. Toutefois, les valeurs d’option de session ne peuvent pas dépasser le nombre maximal de valeurs définies dans la configuration de session.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:PSSessionTypeOption
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ShowSecurityDescriptorUI

Indique que cette applet de commande est une feuille de propriétés qui vous aide à créer un SDDL pour la configuration de session. La feuille de propriétés s’affiche après avoir exécuté la commande , puis redémarré le service WinRM .

Lorsque vous définissez des autorisations sur la configuration, n’oubliez pas que les utilisateurs doivent disposer au moins de l’autorisation Execute(Invoke) pour utiliser 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.

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-StartupScript

Spécifie le script de démarrage de la configuration. Entrez le chemin complet d’un script PowerShell. Le script spécifié s’exécute 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 une valeur de $Null.

Vous pouvez utiliser un script de démarrage pour configurer davantage la session utilisateur. Si le script génère une erreur, même une erreur sans fin, la session n’est pas créée et la commande New-PSSession échoue.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ThreadApartmentState

Spécifie le paramètre d’état d’appartement pour les threads de la session. Les valeurs acceptables pour ce paramètre sont : STA, MTA et Unknown. La valeur par défaut est Unknown.

Type:ApartmentState
Valeurs acceptées:STA, MTA, Unknown
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ThreadOptions

Spécifie le paramètre d’options de thread dans la configuration. Ce paramètre définit la façon dont les threads sont créés et utilisés lorsqu’une commande est exécutée dans la session. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • Faire défaut
  • ReuseThread
  • UseCurrentThread
  • UseNewThread

La valeur par défaut est UseCurrentThread.

Pour plus d’informations, consultez énumération PSThreadOptions.

Type:PSThreadOptions
Valeurs acceptées:Default, UseNewThread, ReuseThread, UseCurrentThread
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-TransportOption

Spécifie les options de transport de la configuration de session. Entrez un objet d’options de transport, tel que l’objet WSManConfigurationOption retourné par l’applet de commande New-PSTransportOption.

Les options des sessions qui utilisent la configuration de session sont déterminées par les valeurs des options de session et les options de configuration de session. Sauf indication contraire, les options définies dans la session, telles que l’utilisation de l’applet de commande New-PSSessionOption, sont prioritaires sur les options définies dans la configuration de session. Toutefois, les valeurs d’option de session ne peuvent pas dépasser le nombre maximal de valeurs définies dans la configuration de session.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:PSTransportOption
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-UseSharedProcess

Utilisez un seul processus pour héberger toutes les sessions démarrées par le même utilisateur et utiliser la même configuration de session. Par défaut, chaque session est hébergée dans son propre processus.

Ce paramètre a été introduit dans PowerShell 3.0.

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-WhatIf

Affiche ce qui se passerait si l’applet de commande s’exécute. L’applet de commande n’est pas exécutée.

Type:SwitchParameter
Alias:wi
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

None

Vous ne pouvez pas diriger l’entrée vers cette applet de commande.

Sorties

WSManConfigLeafElement

Notes

Pour exécuter cette applet de commande, démarrez PowerShell à l’aide de l’option Exécuter en tant qu’administrateur.

L’applet de commande ne modifie pas le nom de configuration et le fournisseur WSMan ne prend pas en charge l’applet de commande . Pour modifier le nom d’une configuration de session, utilisez l’applet de commande Unregister-PSSessionConfiguration pour supprimer la configuration, puis utilisez l’applet de commande Register-PSSessionConfiguration pour créer et inscrire une nouvelle configuration de session.

Vous pouvez utiliser l’applet de commande Set-PSSessionConfiguration pour modifier les configurations de session Microsoft.PowerShell et Microsoft.PowerShell32 par défaut. Ils ne sont pas protégés. 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 utilisez l’applet de commande Enable-PSRemoting pour la restaurer.

Les propriétés d’un objet de configuration de session varient selon les options définies pour la configuration de session et les valeurs de ces options. En outre, les configurations de session qui utilisent un fichier de configuration de session ont des propriétés supplémentaires.

Vous pouvez utiliser des commandes dans le lecteur WSMan : pour modifier les propriétés des configurations de session. Toutefois, vous ne pouvez pas utiliser le lecteur WSMan : dans PowerShell 2.0 pour modifier les propriétés de configuration de session introduites dans PowerShell 3.0, telles que OutputBufferingMode. Les commandes Windows PowerShell 2.0 ne génèrent pas d’erreur, mais elles sont inefficaces. Pour modifier les propriétés introduites dans PowerShell 3.0, utilisez le lecteur WSMan : dans PowerShell 3.0.