Set-PSSessionConfiguration

  • Référence
Module:
Microsoft.PowerShell.Core

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

Syntax

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

Cette applet de commande est disponible uniquement sur la plateforme Windows.

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

Utilisez le paramètre Name pour identifier la configuration de session à modifier. Utilisez les autres paramètres pour spécifier les nouvelles valeurs des 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 du $Null 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é offre une méthode simple et intuitive pour définir ou 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 New-PSSessionConfigurationFile commande.

Les configurations de session définissent l’environnement des sessions distantes (PSSessions) qui se connectent à l’ordinateur local. Chaque session PSSession utilise une configuration de session. La configuration de session détermine les fonctionnalités de la session 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 Get-PSSessionConfiguration de commande ou le fournisseur WSMan. Pour plus d’informations sur le fournisseur WSMan, tapez Get-Help WSMan.

Exemples

Exemple 1 : 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 Administration Shell. La deuxième commande ajoute le AdminConfig.ps1 script à la configuration. La modification est effective lorsque vous redémarrez WinRM. La troisième commande supprime le AdminConfig.ps1 script 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 2 : Afficher les résultats

Cet exemple augmente la valeur de la propriété MaximumReceivedObjectSize Mo à 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 3 : Afficher les résultats de différentes façons

Dans cet exemple, Set-PSSessionConfiguration modifie le script de démarrage dans la configuration de session MaintenanceShell sur Maintenance.ps1. 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 . Get-ChildItem 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.

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

Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : http://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      : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :

Get-ChildItem 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 si elle peut être utilisée pour les sessions locales ou distantes sur l'ordinateur. Les valeurs valides pour ce paramètre sont :

  • Disabled. désactive la configuration de session. Elle ne peut pas être utilisée pour l'accès local ou distant à 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.
  • Remote. Supprime Deny_All et Network_Deny_All entrées des descripteurs de sécurité de la configuration de session. Les utilisateurs des 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 Enable-PSRemoting de commande active toutes les configurations de session sur l’ordinateur et autorise l’accès à distance à eux, et l’applet Disable-PSRemoting de commande 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
Accepted values:Disabled, Local, Remote
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 d’assembly .dll 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
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 obligatoire quand vous spécifiez un nom d'assembly.

Type:String
Position:2
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Vous demande une confirmation avant d’exécuter l’applet de commande.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Supprime toutes les invites de l’utilisateur et redémarre le service WinRM sans inviter. Le redémarrage du service permet d'appliquer la modification de configuration.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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). Par défaut, il s’agit de 50.

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:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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. Par défaut, il s’agit de 10.

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:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

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

Par défaut, seul le module Microsoft.PowerShell.Core est importé dans des sessions, mais sauf si les applets de commande sont exclues, vous pouvez utiliser les applets de commande et Add-PSSnapin les Import-Module applets de commande 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 dans le fichier de configuration de session peuvent masquer les commandes exportées par les 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 par le paramètre ModulesToImport de l’applet Register-PSSessionConfiguration de commande.

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

Type:Object[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Spécifie le nom de la configuration de session que vous souhaitez modifier.

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

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters: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 demander d’invite, utilisez le paramètre Force . Pour redémarrer manuellement le service WinRM , utilisez l’applet de Restart-Service commande.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

Spécifie le chemin d’accès d’un fichier de configuration de session (.pssctel qu’un fichier créé par l’applet de New-PSSessionConfigurationFile commande). 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 New-PSSessionConfigurationFile commande.

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

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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
Aliases:PowerShellVersion
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SecurityDescriptorSddl

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

Cette chaîne détermine les autorisations qui sont nécessaires pour utiliser la nouvelle configuration de session. Pour utiliser une configuration de session dans une session, les utilisateurs doivent disposer au moins Execute(Invoke) d’autorisations 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 WSMan: lecteur.

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
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 New-PSWorkflowExecutionOption de commande.

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

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

Type:PSSessionTypeOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ShowSecurityDescriptorUI

Lorsque ce paramètre est utilisé, l’applet de commande ouvre 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 Set-PSSessionConfiguration commande, puis redémarré le service WinRM .

Lorsque vous définissez des autorisations sur la configuration, n’oubliez pas que les utilisateurs doivent avoir au moins Execute(Invoke) l’autorisation d’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
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StartupScript

Spécifie le script de démarrage de la configuration. Entrez le chemin complet d’un script 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 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 New-PSSession commande échoue.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadApartmentState

Spécifie l’état d’appartement du module de threading à utiliser. Les valeurs acceptables sont les suivantes :

  • Unknown
  • MTA
  • STA
Type:ApartmentState
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Spécifie le paramètre d’options de thread dans la configuration. Ce paramètre définit comment les threads sont créés et utilisés quand une commande est exécutée dans la session. Les valeurs valides pour ce paramètre sont :

  • Default
  • ReuseThread
  • UseCurrentThread
  • UseNewThread

La valeur par défaut est UseCurrentThread.

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

Type:PSThreadOptions
Accepted values:Default, UseNewThread, ReuseThread, UseCurrentThread
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 New-PSTransportOption de commande.

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

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

Type:PSTransportOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseSharedProcess

Utilisez un seul processus pour héberger toutes les sessions qui sont démarrées par le même utilisateur et qui recourent à 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
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Montre ce qui se passe en cas d’exécution de l’applet de commande. L’applet de commande n’est pas exécutée.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

WSManConfigLeafElement

Notes

Cette applet de commande est disponible uniquement sur les plateformes Windows.

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

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

Vous pouvez utiliser l’applet Set-PSSessionConfiguration de commande pour modifier les configurations par défaut Microsoft.PowerShell et Microsoft.PowerShell32 de session. Elles ne sont pas protégées. Pour revenir à la version d’origine d’une configuration de session par défaut, utilisez l’applet Unregister-PSSessionConfiguration de commande pour supprimer la configuration de session par défaut, puis utilisez l’applet de commande pour la Enable-PSRemoting 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 sessions qui utilisent un fichier de configuration de session ont des propriétés supplémentaires.

Vous pouvez utiliser des commandes dans le WSMan: lecteur pour modifier les propriétés des configurations de session. Toutefois, vous ne pouvez pas utiliser le WSMan: lecteur 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 WSMan: lecteur dans PowerShell 3.0 ou version ultérieure.