Register-PSSessionConfiguration

Crée et enregistre une configuration de session.

Syntax

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]
Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]
Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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 Register-PSSessionConfiguration de commande crée et inscrit une nouvelle configuration de session sur l’ordinateur local. Il s’agit d’une applet de commande avancée que vous pouvez utiliser pour créer des sessions personnalisées pour les utilisateurs distants.

Chaque session PowerShell (PSSession) utilise une configuration de session, également appelée point de terminaison. Lorsque les utilisateurs créent une session qui se connecte à l’ordinateur, ils peuvent sélectionner une configuration de session ou utiliser la configuration de session par défaut inscrite lorsque vous activez la communication à distance PowerShell. Les utilisateurs peuvent également définir la variable de préférence $PSSessionConfigurationName, qui spécifie une configuration par défaut pour les sessions distantes créées dans la session active.

La configuration de session définit l'environnement pour la session à distance. Cette configuration peut déterminer les commandes et les éléments de langage qui sont disponibles dans la session. Elle peut aussi inclure des paramètres qui protègent l'ordinateur, tels que ceux qui limitent la quantité de données que la session peut recevoir à distance dans un objet ou une commande unique. Le descripteur de sécurité de la configuration de session détermine quels utilisateurs ont l’autorisation d’utiliser la configuration de session.

Vous pouvez définir les éléments de configuration en utilisant un assembly qui implémente une nouvelle classe de configuration, ainsi qu'un script qui s'exécute dans la session. À compter de PowerShell 3.0, vous pouvez également utiliser un fichier de configuration de session pour définir la configuration de session.

Pour plus d’informations sur les configurations de session, consultez about_Session_Configurations. Pour plus d’informations sur les fichiers de configuration de session, consultez about_Session_Configuration_Files.

Exemples

Exemple 1 : Inscrire une configuration de session NewShell

Dans cet exemple, nous inscrivons la configuration de session NewShell . Les paramètres AssemblyName et ApplicationBase spécifient l’emplacement du fichier MyShell.dll , qui spécifie les applets de commande et les fournisseurs dans la configuration de session. Le paramètre ConfigurationTypeName spécifie la classe de configuration à utiliser à partir de l’assembly.

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

Pour utiliser cette configuration, tapez New-PSSession -ConfigurationName newshell.

Exemple 2 : Inscrire une configuration de session MaintenanceShell

Cet exemple enregistre la configuration de session MaintenanceShell sur l’ordinateur local. Le paramètre StartupScript spécifie le Maintenance.ps1 script.

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

Lorsqu’un utilisateur utilise une New-PSSession commande et sélectionne la configuration MaintenanceShell , le Maintenance.ps1 script s’exécute dans la nouvelle session. Le script peut configurer la session. Cela inclut l’importation de modules et la définition de la stratégie d’exécution pour la session. Si le script génère des erreurs, y compris des erreurs sans fin, la New-PSSession commande échoue.

Exemple 3 : Inscrire une configuration de session

Cet exemple enregistre la configuration de session Administration Shell.

La $sessionParams variable est une table de hachage contenant toutes les valeurs de paramètre. Cette table de hachage est transmise à l’applet de commande à l’aide de la mise en forme PowerShell. La Register-PSSessionConfiguration commande utilise le paramètre SecurityDescritorSDDL pour spécifier le SDDL dans la valeur de la $sddl variable et le paramètre MaximumReceivedObjectSize Mo pour augmenter la limite de taille de l’objet. Il utilise également le paramètre StartupScript pour spécifier un script qui configure la session.

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FASA;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

Cet exemple montre comment inscrire la configuration MaintenanceShell . Register-PSSessionConfiguration retourne un objet WSManConfigContainerElement stocké dans la $s variable. Format-List affiche toutes les propriétés de l’objet retourné. La propriété PSPath indique que l’objet est stocké dans un répertoire du lecteur WSMan : . Get-ChildItem (alias dir) affiche les éléments dans le chemin d’accès WSMan:\LocalHost\PlugIn . Celles-ci incluent la nouvelle configuration MaintenanceShell et les deux configurations par défaut fournies avec PowerShell.

$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

Dans cet exemple, nous créons et inscrivons la configuration de session WithProfile . Le paramètre StartupScript dirige PowerShell pour exécuter le script spécifié pour toute session qui utilise la configuration de session.

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

Le script contient une seule commande qui utilise l’approvisionnement par points pour exécuter le profil CurrentUserAllHosts de l’utilisateur dans l’étendue actuelle de la session.

Pour plus d'informations sur les profils, consultez about_Profiles. Pour plus d’informations sur l’approvisionnement par points, consultez about_Scopes.

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 :

  • Désactivé. désactive la configuration de session. Elle ne peut pas être utilisée pour l'accès local ou distant à 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.
  • Distant. permet aux utilisateurs locaux et distants d'utiliser la configuration de session pour créer des sessions et exécuter des commandes sur l'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 autorise l’accès à distance à toutes les configurations de session, l’applet Enable-PSSessionConfiguration de commande active les configurations de session et l’applet Disable-PSRemoting de commande empêche l’accès à distance à toutes les configurations de session.

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

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

-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 requis lorsque vous spécifiez le paramètre ConfigurationTypeName .

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

-ConfigurationTypeName

Spécifie le nom qualifié complet du type Microsoft .NET Framework qui est 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.

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, spécifiez le paramètre NoServiceRestart .

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

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

Type:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

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

Type:Nullable<T>[Double]
Position:Named
Default value:10
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

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

Par défaut, seul Microsoft.PowerShell.Core est importé dans les 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 dans le fichier de configuration de session peuvent masquer les commandes exportées par les modules ou empêcher les utilisateurs de les utiliser.

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 un nom pour la configuration de session. Ce paramètre est obligatoire.

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 une Register-PSSessionConfiguration commande, 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 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 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.

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

-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 de 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. Échec des tentatives de création d'un processus 64 bits sur un ordinateur 32 bits.

Type:String
Aliases:PA
Accepted values:x86, amd64
Position:Named
Default value:None
Required:False
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) 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 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 la chaîne 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.

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’utilisation de 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

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 Register-PSSessionConfiguration commande, puis redémarré 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.

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

-StartupScript

Spécifie le chemin complet d’un script PowerShell. Le script spécifié est exécuté 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 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 :

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

-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 valides pour ce paramètre sont :

  • Par défaut
  • 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 l’option de transport.

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

WSManConfigContainerElement

Notes

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

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

Cette applet de commande génère du code XML qui représente une configuration de plug-in Web Services for Management (WS-Management) et envoie le code XML à WS-Management, qui inscrit le plug-in sur l’ordinateur local (New-Item wsman:\localhost\plugin).

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.