Register-PSSessionConfiguration

Syntaxe

NameParameterSet (Par défaut)

Register-PSSessionConfiguration
    [-Name] <String>
    [-ProcessorArchitecture <String>]
    [-SessionType <PSSessionType>]
    [-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>]

AssemblyNameParameterSet

Register-PSSessionConfiguration
    [-Name] <String>
    [-AssemblyName] <String>
    [-ConfigurationTypeName] <String>
    [-ProcessorArchitecture <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>]

SessionConfigurationFile

Register-PSSessionConfiguration
    [-Name] <String>
    -Path <String>
    [-ProcessorArchitecture <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-TransportOption <PSTransportOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

Exemples

Exemple 1 : Inscrire une configuration de session NewShell

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='c:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

Exemple 2 : Inscrire une configuration de session MaintenanceShell

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

Exemple 3 : Inscrire une configuration de session

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"
$sessionParams = @{
    Name="AdminShell"
    SecurityDescriptorSDDL=$sddl
    MaximumReceivedObjectSizeMB=20
    StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams

Exemple 4 : Retourner un élément conteneur de configuration

$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin

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

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

Exemple 5 : Inscrire une configuration de session avec un script de démarrage

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.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 :

• Désactivé. Désactive la configuration de session. Il ne peut pas être utilisé pour l’accès distant ou local à l’ordinateur.
• Local. Permet aux utilisateurs de l’ordinateur local d’utiliser la configuration de session pour créer une session de bouclage locale sur le même ordinateur, mais refuse l’accès aux utilisateurs distants.
• Éloigné. Permet aux utilisateurs locaux et distants d’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 autorise l’accès à distance à toutes les configurations de session, l’applet de commande Enable-PSSessionConfiguration active les configurations de session et l’applet de commande Disable-PSRemoting empêche l’accès à distance à toutes les configurations de session.

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

Propriétés du paramètre

Jeux de paramètres

-ApplicationBase

Spécifie le chemin d’accès du fichier d’assembly (*.dll) spécifié dans la valeur du paramètre AssemblyName. Utilisez ce paramètre lorsque la valeur du paramètre AssemblyName n’inclut pas de chemin d’accès. L'emplacement par défaut est le répertoire actif.

Propriétés du paramètre

Jeux de paramètres

-AssemblyName

Spécifie le nom d’un fichier d’assembly (*.dll) dans lequel le type de configuration est défini. Vous pouvez spécifier le chemin de l'.dll dans ce paramètre ou dans la valeur du paramètre ApplicationBase.

Ce paramètre est obligatoire lorsque vous spécifiez le paramètre ConfigurationTypeName.

Propriétés du paramètre

Jeux de paramètres

-ConfigurationTypeName

Spécifie le nom complet du type Microsoft .NET Framework utilisé pour cette configuration. Le type que vous spécifiez doit implémenter la classe System.Management.Automation.Remoting.PSSessionConfiguration.

Pour spécifier le fichier d’assembly (*.dll) qui implémente le type de configuration, spécifiez les paramètres AssemblyName et ApplicationBase.

La création d’un type vous permet de contrôler davantage d’aspects de la configuration de session, tels que l’exposition ou le masquage de certains paramètres d’applets de commande, ou la définition de limites de taille des données et de taille d’objet que les utilisateurs ne peuvent pas remplacer.

Si vous omettez ce paramètre, la classe DefaultRemotePowerShellConfiguration est utilisée pour la configuration de session.

Propriétés du paramètre

Jeux de paramètres

-Confirm

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

Propriétés du paramètre

Jeux de paramètres

-Force

Supprime toutes les invites de l’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, spécifiez le paramètre NoServiceRestart.

Propriétés du paramètre

Jeux de paramètres

-MaximumReceivedDataSizePerCommandMB

Spécifie une limite pour 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 et la valeur de ce paramètre est ignorée.

Propriétés du paramètre

Jeux de paramètres

-MaximumReceivedObjectSizeMB

Spécifie une limite pour 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 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 et la valeur de ce paramètre est ignorée.

Propriétés du paramètre

Jeux de paramètres

-ModulesToImport

Spécifie les modules qui sont automatiquement importés dans des sessions qui utilisent la configuration de session.

Par défaut, seule Microsoft.PowerShell.Core est importée dans des sessions. Sauf si les applets de commande sont exclues, vous pouvez utiliser Import-Module pour ajouter des modules à la session.

Les modules spécifiés dans cette valeur de paramètre sont importés en plus des modules spécifiés par le paramètre SessionType et ceux répertoriés dans la clé ModulesToImport 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.

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

Propriétés du paramètre

Jeux de paramètres

-Name

Spécifie un nom pour la configuration de session. Ce paramètre est obligatoire.

Propriétés du paramètre

Jeux de paramètres

-NoServiceRestart

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

Par défaut, lorsque vous exécutez une commande Register-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, spécifiez le paramètre force . Pour redémarrer manuellement le service WinRM , utilisez l’applet de commande .

Propriétés du paramètre

Jeux de paramètres

-Path

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

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

Propriétés du paramètre

Jeux de paramètres

-ProcessorArchitecture

Détermine si une version 32 bits ou 64 bits du processus PowerShell est démarrée dans les sessions qui utilisent cette configuration de session. Les valeurs acceptables pour ce paramètre sont : x86 (32 bits) et AMD64 (64 bits). La valeur par défaut est déterminée par l’architecture du processeur de l’ordinateur qui héberge la configuration de session.

Vous pouvez utiliser ce paramètre pour créer une session 32 bits sur un ordinateur 64 bits. Les tentatives de création d’un processus 64 bits sur un ordinateur 32 bits échouent.

Propriétés du paramètre

Jeux de paramètres

-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.

Propriétés du paramètre

Jeux de paramètres

-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.

Propriétés du paramètre

Jeux de paramètres

-SecurityDescriptorSddl

Spécifie une chaîne SDDL (Security Descriptor Definition Language) 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.

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

Si vous omettez ce paramètre, le SDDL racine du service WinRM est utilisé pour cette configuration. Pour afficher ou modifier le SDDL racine, utilisez le fournisseur WSMan. Par exemple, Get-Item wsman:\localhost\service\rootSDDL. Pour plus d’informations sur le fournisseur WSMan, tapez Get-Help wsman.

Propriétés du paramètre

Jeux de paramètres

-SessionType

Spécifie le type de session créé à l’aide de la configuration de session. Les valeurs acceptables pour ce paramètre sont les suivantes :

• Vide. Aucun module n’est ajouté à la session par défaut. Utilisez les paramètres de cette applet de commande pour ajouter des modules, des fonctions, des scripts et d’autres fonctionnalités à la session.
• Par défaut. Ajoute Microsoft.PowerShell.Core à la session. Ce module inclut l’applet de commande Import-Module que les utilisateurs peuvent utiliser pour importer d’autres modules, sauf si vous interditz explicitement l’applet de commande.
• RestrictedRemoteServer. Inclut uniquement les applets de commande suivantes : Exit-PSSession, Get-Command, Get-FormatData, Get-Help, Measure-Object, Out-Defaultet Select-Object. Utilisez un script ou un assembly, ou les clés du fichier de configuration de session, pour ajouter des modules, des fonctions, des scripts et d’autres fonctionnalités à la session.

La valeur par défaut est Default.

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

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

Propriétés du paramètre

Jeux de paramètres

-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.

Propriétés du paramètre

Jeux de paramètres

-ShowSecurityDescriptorUI

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

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

Propriétés du paramètre

Jeux de paramètres

-StartupScript

Spécifie le chemin complet d’un script PowerShell. Le script spécifié s’exécute dans la nouvelle session qui utilise la configuration de session.

Vous pouvez utiliser le script pour configurer la session. 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.

Propriétés du paramètre

Jeux de paramètres

-ThreadApartmentState

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

Propriétés du paramètre

Jeux de paramètres

-ThreadOptions

Spécifie la façon dont les threads sont créés et utilisés lorsqu’une commande s’exécute dans la session. Les valeurs acceptables pour ce paramètre sont les suivantes :

• Par défaut
• ReuseThread
• UseCurrentThread
• UseNewThread

La valeur par défaut est UseCurrentThread.

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

Propriétés du paramètre

Jeux de paramètres

-TransportOption

Spécifie l’option de transport.

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

Propriétés du paramètre

Jeux de paramètres

-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.

Propriétés du paramètre

Jeux de paramètres

-WhatIf

Affiche ce qui se passerait si l’applet de commande s’exécute. L’applet de commande ne s’exécute pas.

Propriétés du paramètre

Jeux de paramètres

CommonParameters

Entrées

None

Sorties

WSManConfigContainerElement

Notes

Liens associés

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration (Activer la configuration de session PS)
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• New-PSSessionOption
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• Fournisseur WSMan
• à_propos_des_Configurations_de_Session
• à_propos_des_fichiers_de_configuration_de_session