New-PSSessionOption

Crée un objet qui contient des options avancées pour une session PSSession.

Syntax

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

Description

L’applet New-PSSessionOption de commande crée un objet qui contient des options avancées pour une session gérée par l’utilisateur (PSSession). Vous pouvez utiliser l’objet comme valeur du paramètre SessionOption des applets de commande qui créent une session PSSession, par New-PSSessionexemple , Enter-PSSessionet Invoke-Command.

Sans paramètres, New-PSSessionOption génère un objet qui contient les valeurs par défaut pour toutes les options. Étant donné que chaque propriété peut être modifiée, vous pouvez utiliser l’objet résultant en tant que modèle et créer des objets d’option standard pour votre entreprise.

Vous pouvez également enregistrer un objet SessionOption dans la $PSSessionOption variable de préférence. Les valeurs de cette variable établissent de nouvelles valeurs par défaut pour les options de session. Elles sont effectives lorsqu’aucune option de session n’est définie pour la session et qu’elles sont prioritaires sur les options définies dans la configuration de session, mais vous pouvez les remplacer en spécifiant des options de session ou un objet SessionOption dans une applet de commande qui crée une session. Pour plus d’informations sur la $PSSessionOption variable de préférence, consultez about_Preference_Variables.

Lorsque vous utilisez un objet SessionOption dans une applet de commande qui crée une session, les valeurs d’option de session sont prioritaires sur les valeurs par défaut pour les sessions définies dans la $PSSessionOption variable de préférence et dans la configuration de session. Elles ne sont cependant pas prioritaires sur les valeurs maximales, les quotas ou les limites définis dans la configuration de session. Pour plus d'informations sur les configurations de session, consultez about_Session_Configurations.

Exemples

Exemple 1 : Créer une option de session par défaut

Cette commande crée un objet SessionOption avec les valeurs par défaut.

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Exemple 2 : Configurer une session à l’aide d’un objet d’option de session

Cet exemple montre comment utiliser un objet SessionOption pour configurer une session.

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

La première commande crée un objet SessionOption et l’enregistre dans la valeur de la $pso variable. La deuxième commande utilise l’applet New-PSSession de commande pour créer une session sur l’ordinateur distant Server01. La commande utilise l’objet SessionOption dans la valeur de la $pso variable comme valeur du paramètre SessionOption de la commande.

Exemple 3 : Démarrer une session interactive

Cette commande utilise l’applet Enter-PSSession de commande pour démarrer une session interactive avec l’ordinateur Server01.

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

La valeur du paramètre SessionOption est une New-PSSessionOption commande qui a les paramètres NoEncryption et NoCompression .

La New-PSSessionOption commande est placée entre parenthèses pour s’assurer qu’elle s’exécute avant la Enter-PSSession commande.

Exemple 4 : Modifier un objet d’option de session

Cet exemple montre que vous pouvez modifier l’objet SessionOption . Toutes les propriétés ont des valeurs en lecture/écriture.

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Utilisez cette méthode pour créer un objet de session standard pour votre entreprise, puis créez-en des versions personnalisées pour des utilisations particulières.

Exemple 5 : Créer une variable de préférence

Cette commande crée une $PSSessionOption variable de préférence.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

Lorsque la $PSSessionOption variable de préférence est définie dans la session, elle établit les valeurs par défaut pour les options des sessions créées avec les applets de commande, Enter-PSSessionet Invoke-Command les New-PSSessionapplets de commande.

Pour rendre la variable disponible dans toutes les sessions, ajoutez-la $PSSessionOption à votre session PowerShell et à votre profil PowerShell.

Pour plus d’informations sur la $PSSessionOption variable de préférence, consultez about_Preference_Variables. Pour plus d'informations sur les profils, consultez about_Profiles.

Exemple 6 : Répondre aux exigences d’une configuration de session à distance

Cet exemple montre comment utiliser un objet SessionOption pour répondre aux exigences d’une configuration de session à distance.

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

La première commande utilise l’applet New-PSSessionOption de commande pour créer un objet SessionOption qui a la propriété SkipCNCheck . La commande enregistre l’objet de session résultant dans la $skipCN variable.

La deuxième commande utilise l’applet New-PSSession de commande pour créer une session sur un ordinateur distant. La $skipCN variable case activée est utilisée dans la valeur du paramètre SessionOption.

Étant donné que l’ordinateur est identifié par son adresse IP, la valeur du paramètre ComputerName ne correspond à aucun des noms communs du certificat utilisé pour SSL (Secure Sockets Layer). Par conséquent, l’option SkipCNCheck est requise.

Exemple 7 : Rendre les arguments disponibles pour une session à distance

Cet exemple montre comment utiliser le paramètre ApplicationArguments de l’applet New-PSSessionOption de commande pour rendre des données supplémentaires disponibles pour la session à distance.

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

La première commande crée une table de hachage avec deux clés, Team et Use. La commande enregistre la table de hachage dans la $team variable. Pour plus d’informations sur les tables de hachage, voir À propos des tables de hachage.

Ensuite, l’applet New-PSSessionOption de commande, à l’aide du paramètre ApplicationArguments , crée un objet SessionOption enregistré dans la $team variable. Lorsque vous New-PSSessionOption créez l’objet d’option de session, il convertit automatiquement la table de hachage dans la valeur du paramètre ApplicationArguments en primitiveDictionary afin que les données puissent être transmises de manière fiable à la session distante.

L’applet New-PSSession de commande démarre une session sur l’ordinateur Server01. Il utilise le paramètre SessionOption pour inclure les options dans la $teamOption variable.

L’applet Invoke-Command de commande montre que les données de la $team variable sont disponibles pour les commandes de la session distante. Les données apparaissent dans la propriété ApplicationArguments de la $PSSenderInfo variable automatique.

La finale Invoke-Command montre comment les données peuvent être utilisées.

Paramètres

-ApplicationArguments

Spécifie un PrimitiveDictionary envoyé à la session distante. Les commandes et les scripts de la session à distance, y compris les scripts de démarrage dans la configuration de session, peuvent trouver ce dictionnaire dans la propriété ApplicationArguments de la $PSSenderInfo variable automatique. Vous pouvez utiliser ce paramètre pour envoyer des données à la session à distance.

Pour plus d’informations, consultez about_Hash_Tables, about_Session_Configurations et about_Automatic_Variables.

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

-CancelTimeout

Détermine la durée pendant laquelle PowerShell attend une opération d’annulation (CTRL+C) avant de la terminer. Entrez une valeur en millisecondes.

La valeur par défaut est 60000 (une minute). La valeur (zéro) signifie qu’il n’y a pas de 0 délai d’attente ; la commande continue indéfiniment.

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Culture

Spécifie la culture à utiliser pour la session. Entrez un nom de culture au <languagecode2>-<country/regioncode2> format (par exemple ja-JP), une variable qui contient un objet CultureInfo ou une commande qui obtient un objet CultureInfo .

La valeur par défaut est $Null, et la culture définie dans le système d’exploitation est utilisée dans la session.

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

-IdleTimeout

Détermine la durée pendant laquelle la session reste ouverte si l’ordinateur distant ne reçoit aucune communication de l’ordinateur local. Cela inclut le signal de pulsation. Quand le délai expire, la session se ferme.

La valeur de délai d’inactivité est importante si vous envisagez de vous déconnecter et de vous reconnecter à une session. Vous pouvez vous reconnecter seulement si la session n'est pas expirée.

Entrez une valeur en millisecondes. La valeur minimale est 60000 (1 minute). La valeur maximale est la valeur de la propriété MaxIdleTimeoutms de la configuration de session. La valeur par défaut , -1ne définit pas de délai d’inactivité.

La session utilise le délai d’inactivité défini dans les options de session, le cas échéant. Si aucun n’est défini (-1), la session utilise la valeur de la propriété IdleTimeoutMs de la configuration de session ou de la valeur de délai d’attente de l’interpréteur de commandes WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout), la plus courte.

Si le délai d’inactivité défini dans les options de session dépasse la valeur de la propriété MaxIdleTimeoutMs de la configuration de session, la commande permettant de créer une session échoue.

La valeur IdleTimeoutMs de la configuration de session Microsoft.PowerShell par défaut est 7200000 de millisecondes (2 heures). Sa valeur MaxIdleTimeoutMs est 2147483647 de millisecondes (>24 jours). La valeur par défaut du délai d’inactivité de l’interpréteur de commandes WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) est 7200000 de millisecondes (2 heures).

La valeur de délai d’inactivité d’une session peut également être modifiée lors de la déconnexion d’une session ou de la reconnexion à une session. Pour plus d’informations, consultez Disconnect-PSSession et Connect-PSSession.

Dans Windows PowerShell 2.0, la valeur par défaut du paramètre IdleTimeout est 240000 (4 minutes).

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludePortInSPN

Inclut le numéro de port dans le nom du principal de service (SPN) utilisé pour l’authentification Kerberos, par exemple HTTP://<ComputerName>:5985. Cette option permet à un client qui utilise un nom de principal du service qui n'est pas le nom par défaut de s'authentifier auprès d'un ordinateur distant qui utilise l'authentification Kerberos.

L'option est conçue pour les entreprises où plusieurs services prenant en charge l'authentification Kerberos s'exécutent sous différents comptes d'utilisateurs. Par exemple, une application IIS qui autorise l’authentification Kerberos peut exiger que le SPN par défaut soit inscrit auprès d’un compte d’utilisateur différent du compte d’ordinateur. Dans ce cas, la communication à distance PowerShell ne peut pas utiliser Kerberos pour s’authentifier, car elle nécessite un SPN inscrit sur le compte d’ordinateur. Pour résoudre ce problème, les administrateurs peuvent créer différents SPN, tels que l’utilisation Setspn.exe, qui sont inscrits auprès de différents comptes d’utilisateur et peuvent les distinguer en incluant le numéro de port dans le SPN.

Pour plus d’informations, consultez Vue d’ensemble de Setspn.

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

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

-MaxConnectionRetryCount

Spécifie le nombre de fois où PowerShell tente d’établir une connexion à un ordinateur cible si la tentative actuelle échoue en raison de problèmes réseau. La valeur par défaut est 5.

Ce paramètre a été ajouté pour PowerShell version 5.0.

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

-MaximumReceivedDataSizePerCommand

Spécifie le nombre maximal d'octets que l'ordinateur local peut recevoir de l'ordinateur distant dans une même commande. Entrez une valeur en octets. Par défaut, il n'existe pas de limite de taille des données.

Cette option est conçue pour protéger les ressources sur l'ordinateur client.

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

-MaximumReceivedObjectSize

Spécifie la taille maximale d'un objet que l'ordinateur local peut recevoir de l'ordinateur distant. Cette option est conçue pour protéger les ressources sur l'ordinateur client. Entrez une valeur en octets.

Dans Windows PowerShell 2.0, si vous omettez ce paramètre, la taille des objets n'est pas limitée. À compter de Windows PowerShell 3.0, si vous omettez ce paramètre, la valeur par défaut est 209715200 octets (ou 200MB).

Type:Int32
Position:Named
Default value:209715200
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

Détermine le nombre de fois où PowerShell redirige une connexion vers un AUTRE URI (Uniform Resource Identifier) avant l’échec de la connexion. La valeur par défaut est 5. La valeur ( 0 zéro) empêche toute redirection.

Cette option est utilisée dans la session uniquement lorsque le paramètre AllowRedirection est utilisé dans la commande qui crée la session.

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoCompression

Désactive la compression de paquets dans la session. La compression utilise davantage de cycles processeur, mais rend la transmission plus rapide.

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

-NoEncryption

Désactive le chiffrement des données.

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

-NoMachineProfile

Empêche le chargement du profil d'utilisateur Windows de l'utilisateur. Par conséquent, la session peut-être être créée plus rapidement, mais les paramètres de Registre spécifiques à l'utilisateur, les éléments comme des variables d'environnement et les certificats ne sont pas disponibles dans la session.

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

-OpenTimeout

Détermine le temps pendant lequel l'ordinateur client attend que la connexion de la session soit établie. Quand le délai expire, la commande d'établissement de la connexion échoue. Entrez une valeur en millisecondes.

La valeur par défaut est 180000 (3 minutes). La valeur (zéro) signifie qu’il n’y a pas de 0 délai d’attente ; la commande continue indéfiniment.

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

Détermine la durée maximale pendant laquelle WinRM attend les tests de connexion positifs à partir d’une connexion active avant de lancer un délai d’attente de connexion. Pour plus d’informations sur WinRM, consultez la documentation de gestion à distance Windows.

OperationTimeout n’impose pas de limite de temps sur les commandes ou les processus en cours d’exécution dans une session distante et n’affecte pas d’autres protocoles de communication à distance comme SSH.

La valeur par défaut est 180000 (3 minutes). La valeur (zéro) signifie qu’il n’y a pas de 0 délai d’attente.

Type:Int32
Aliases:OperationTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

Détermine comment la sortie de la commande est gérée dans des sessions déconnectées quand la mémoire tampon de sortie est pleine.

Si le mode de mise en mémoire tampon de sortie n’est pas défini dans la session ou dans la configuration de session, la valeur par défaut est Block. Les utilisateurs peuvent également changer le mode de mise en mémoire tampon de sortie lors de la déconnexion de la session.

Si vous omettez ce paramètre, la valeur de OutputBufferingMode de l’objet SessionOption est .None Une valeur ou remplace l’option de BlockDrop transport du mode de mise en mémoire tampon de sortie définie dans la configuration de session. Les valeurs valides pour ce paramètre sont :

  • Block. Quand la mémoire tampon de sortie est pleine, l'exécution est suspendue jusqu'à ce que la mémoire tampon soit effacée.
  • Drop. Quand la mémoire tampon de sortie est pleine, l'exécution se poursuit. Quand une nouvelle sortie est enregistrée, la sortie la plus ancienne est supprimée.
  • None. Aucun mode de mise en mémoire tampon de sortie n'est spécifié.

Pour plus d’informations sur l’option de transport en mode de mise en mémoire tampon de sortie, consultez New-PSTransportOption.

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

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

Détermine le mécanisme utilisé pour résoudre le nom d’hôte. Les valeurs valides pour ce paramètre sont :

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

La valeur par défaut est None.

Pour plus d’informations sur les valeurs de ce paramètre, consultez Énumération ProxyAccessType.

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAuthentication

Spécifie la méthode d'authentification qui est utilisée pour la résolution du proxy. Les valeurs valides pour ce paramètre sont :

  • Basic
  • Digest
  • Negotiate

La valeur par défaut est Negotiate.

Pour plus d’informations sur les valeurs de ce paramètre, consultez AuthenticationMechanism, énumération.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

Spécifie les informations d'identification à utiliser pour l'authentification du proxy. Entrez une variable qui contient un objet PSCredential ou une commande qui obtient un objet PSCredential , tel qu’une Get-Credential commande. Si cette option n'est pas définie, aucune information d'identification n'est spécifiée.

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

-SkipCACheck

Spécifie que lorsqu’il se connecte via HTTPS, le client ne valide pas que le certificat de serveur est signé par une autorité de certification approuvée.

Utilisez cette option seulement quand l'ordinateur distant est approuvé via un autre mécanisme, par exemple quand l'ordinateur distant fait partie d'un réseau qui est physiquement sécurisé et isolé, ou bien quand l'ordinateur distant est répertorié comme hôte approuvé dans une configuration WinRM.

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

-SkipCNCheck

Spécifie que le nom commun du certificat du serveur n’a pas besoin de correspondre au nom d’hôte du serveur. Cette option est utilisée seulement dans les opérations à distance utilisant le protocole HTTPS.

Utilisez cette option seulement pour des ordinateurs approuvés.

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

-SkipRevocationCheck

Ne vérifie pas l'état de révocation du certificat serveur.

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

-UICulture

Spécifie la culture de l'interface utilisateur à utiliser pour la session.

Les valeurs valides sont les suivantes :

  • Nom de culture au <languagecode2>-<country/regioncode2> format, tel que ja-JP
  • Variable qui contient un objet CultureInfo
  • Commande qui obtient un objet CultureInfo , tel que Get-Culture

La valeur par défaut est $null, et la culture de l’interface utilisateur définie dans le système d’exploitation lors de la création de la session.

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

-UseUTF16

Indique que cette applet de commande encode la requête au format UTF16 au lieu du format UTF8.

Type:SwitchParameter
Position:Named
Default value:None
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

PSSessionOption

Notes

Si le paramètre SessionOption n’est pas utilisé dans une commande pour créer une session PSSession, les options de session sont déterminées par les valeurs de propriété de la $PSSessionOption variable de préférence, si elle est définie. Pour plus d’informations sur la variable $PSSessionOption, consultez about_Preference_Variables.

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.