New-PSSession
Crée une connexion persistante à un ordinateur local ou distant.
Syntax
New-PSSession
[[-ComputerName] <String[]>]
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-ApplicationName <String>]
[-ThrottleLimit <Int32>]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]
New-PSSession
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ConfigurationName <String>]
[-ThrottleLimit <Int32>]
[-ConnectionUri] <Uri[]>
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]
New-PSSession
[[-Session] <PSSession[]>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ThrottleLimit <Int32>]
[<CommonParameters>]
Description
L’applet de commande New-PSSession crée une session Windows PowerShell (PSSession) sur un ordinateur local ou distant. Lorsque vous créez une session PSSession, Windows PowerShell établit une connexion permanente à l’ordinateur distant.
Utilisez une session PSSession pour exécuter plusieurs commandes qui partagent des données, telles qu’une fonction ou la valeur d’une variable. Pour exécuter des commandes dans une session PSSession, utilisez l’applet de commande Invoke-Command. Pour utiliser psSession afin d’interagir directement avec un ordinateur distant, utilisez l’applet de commande Enter-PSSession. Pour plus d’informations, consultez about_PSSessions (https://go.microsoft.com/fwlink/?LinkID=135181).
Vous pouvez exécuter des commandes sur un ordinateur distant sans créer de session PSSession à l’aide des paramètres ComputerName de Enter-PSSession ou Invoke-Command. Lorsque vous utilisez le paramètre ComputerName, Windows PowerShell crée une connexion temporaire qui est utilisée pour la commande, puis est fermée.
Exemples
Exemple 1 : Create une session sur l’ordinateur local
PS C:\> $s = New-PSSession
Cette commande crée une session PSSession sur l’ordinateur local et enregistre la session PSSession dans la variable $s.
Vous pouvez maintenant utiliser cette session PSSession pour exécuter des commandes sur l’ordinateur local.
Exemple 2 : Create une session sur un ordinateur distant
PS C:\> $Server01 = New-PSSession -ComputerName Server01
Cette commande crée une session PSSession sur l’ordinateur Server01 et l’enregistre dans la variable $Server 01.
Lors de la création de plusieurs objets PSSession , affectez-les à des variables avec des noms utiles. Cela vous aidera à gérer les objets PSSession dans les commandes suivantes.
Exemple 3 : sessions Create sur plusieurs ordinateurs
PS C:\> $s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03
Cette commande crée trois objets PSSession , un sur chacun des ordinateurs spécifiés par le paramètre ComputerName .
La commande utilise l’opérateur d’affectation (=) pour affecter les nouveaux objets PSSession à des variables : $s 1, $s 2, $s 3. Il affecte la session PSSession Server01 à $s 1, la session PSSession Server02 à $s 2 et la session PSSession Server03 à $s 3.
Lorsque vous affectez plusieurs objets à une série de variables, Windows PowerShell affecte respectivement chaque objet à une variable de la série. S'il y a plus d'objets que de variables, tous les objets restants sont affectés à la dernière variable. S'il y a plus de variables que d'objets, les autres variables sont vides (null).
Exemple 4 : Create une session avec un port spécifié
PS C:\> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12
Cette commande crée une session PSSession sur l’ordinateur Server01 qui se connecte au port de serveur 8081 et utilise le protocole SSL. La nouvelle session PSSession utilise une autre configuration de session appelée E12.
Avant de définir le port, vous devez configurer l'écouteur WinRM sur l'ordinateur distant afin d'écouter sur le port 8081. Pour plus d’informations, consultez la description du paramètre Port .
Exemple 5 : Create une session basée sur une session existante
PS C:\> New-PSSession -Session $s -Credential Domain01\User01
Cette commande crée une session PSSession avec les mêmes propriétés qu’une session PSSession existante. Vous pouvez utiliser ce format de commande lorsque les ressources d’une session PSSession existante sont épuisées et qu’une nouvelle session PSSession est nécessaire pour décharger une partie de la demande.
La commande utilise le paramètre Session de New-PSSession pour spécifier la session PSSession enregistrée dans la variable $s. Elle utilise les informations d'identification de l'utilisateur Domain1\Admin01 pour terminer la commande.
Exemple 6 : Create une session avec une étendue globale dans un autre domaine
PS C:\> $global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01
Cet exemple montre comment créer une session PSSession avec une étendue globale sur un ordinateur dans un autre domaine.
Par défaut, les objets PSSession créés sur la ligne de commande sont créés avec une étendue locale et les objets PSSession créés dans un script ont une étendue de script.
Pour créer une session PSSession avec une étendue globale, créez une session PSSession, puis stockez-la dans une variable qui est convertie en étendue globale. Dans ce cas, la variable $s est convertie en portée globale.
La commande utilise le paramètre ComputerName pour spécifier l'ordinateur distant. Étant donné que l’ordinateur se trouve dans un domaine différent du compte d’utilisateur, le nom complet de l’ordinateur est spécifié avec les informations d’identification de l’utilisateur.
Exemple 7 : sessions Create pour de nombreux ordinateurs
PS C:\> $rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50
Cette commande crée une session PSSession sur chacun des 200 ordinateurs répertoriés dans le fichier Servers.txt et stocke la session PSSession résultante dans la variable $rs. Les objets PSSession ont une limite de limitation de 50.
Vous pouvez utiliser ce format de commande lorsque les noms des ordinateurs sont stockés dans une base de données, une feuille de calcul, un fichier texte ou tout autre format convertible en texte.
Exemple 8 : Create une session à l’aide d’un URI
PS C:\> $s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01
Cette commande crée une session PSSession sur l’ordinateur Server01 et la stocke dans la variable $s. Il utilise le paramètre URI pour spécifier le protocole de transport, l’ordinateur distant, le port et une autre configuration de session. Il utilise également le paramètre Credential pour spécifier un compte d’utilisateur autorisé à créer une session sur l’ordinateur distant.
Exemple 9 : Exécuter un travail en arrière-plan dans un ensemble de sessions
PS C:\> $s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob
Ces commandes créent un ensemble d’objets PSSession , puis exécutent un travail en arrière-plan dans chacun des objets PSSession .
La première commande crée une session PSSession sur chacun des ordinateurs répertoriés dans le fichier Servers.txt. Il utilise l’applet de commande New-PSSession pour créer la session PSSession. La valeur du paramètre ComputerName est une commande qui utilise l’applet de commande Get-Content pour obtenir la liste des noms d’ordinateurs du fichier Servers.txt.
La commande utilise le paramètre Credential pour créer les objets PSSession qui ont l’autorisation d’un administrateur de domaine, et elle utilise le paramètre ThrottleLimit pour limiter la commande à 16 connexions simultanées. La commande enregistre les objets PSSession dans la variable $s.
La deuxième commande utilise le paramètre AsJob de l’applet de commande Invoke-Command pour démarrer un travail en arrière-plan qui exécute une Get-Process PowerShell
commande dans chacun des objets PSSession dans $s.
Pour plus d’informations sur Windows PowerShell travaux en arrière-plan, consultez about_Jobs et about_Remote_Jobs.
Exemple 10 : Create une session pour un ordinateur à l’aide de son URI
PS C:\> New-PSSession -ConnectionURI https://management.exchangelabs.com/Management
Cette commande crée un objet PSSession qui se connecte à un ordinateur spécifié par un URI au lieu d’un nom d’ordinateur.
Exemple 11 : Create une option de session
PS C:\> $so = New-PSSessionOption -SkipCACheck
PS C:\> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01
Cet exemple montre comment créer un objet d’option de session et utiliser le paramètre SessionOption .
La première commande utilise l’applet de commande New-PSSessionOption pour créer une option de session. Il enregistre l’objet SessionOption résultant dans la variable $so.
La deuxième commande utilise l'option d'une nouvelle session. La commande utilise l'applet de commande New-PSSession pour créer une nouvelle session. La valeur du paramètre SessionOption est l'objet SessionOption de la variable $so.
Paramètres
-AllowRedirection
Indique que cette applet de commande autorise la redirection de cette connexion vers un AUTRE URI (Uniform Resource Identifier).
Quand vous utilisez le paramètre ConnectionURI, la destination distante peut retourner une instruction pour effectuer une redirection vers un autre URI. Par défaut, Windows PowerShell ne redirige pas les connexions, mais vous pouvez utiliser ce paramètre pour lui permettre de rediriger la connexion.
Vous pouvez également limiter le nombre de fois où la connexion est redirigée en modifiant la valeur de l'option de session MaximumConnectionRedirectionCount. Utilisez le paramètre MaximumRedirection de l’applet de commande New-PSSessionOption ou définissez la propriété MaximumConnectionRedirectionCount de la variable de préférence $PSSessionOption . La valeur par défaut est 5.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ApplicationName
Spécifie le segment de nom d'application de l'URI de connexion. Utilisez ce paramètre pour spécifier le nom de l'application quand vous n'utilisez pas le paramètre ConnectionURI dans la commande.
La valeur par défaut est la valeur de la variable de préférence $PSSessionApplicationName sur l'ordinateur local. Si cette variable de préférence n'est pas définie, la valeur par défaut est WSMAN. Cette valeur convient pour la plupart des utilisations. Pour plus d’informations, consultez about_Preference_Variables.
Le service WinRM utilise le nom de l'application pour sélectionner un port d'écoute et traiter la demande de connexion. La valeur du paramètre doit correspondre à la valeur de la propriété URLPrefix d'un écouteur sur l'ordinateur distant.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Authentication
Spécifie le mécanisme permettant d'authentifier les informations d'identification de l'utilisateur. Les valeurs valides pour ce paramètre sont :
- Default
- De base
- Credssp
- Digest
- Kerberos
- Negotiate
- NegotiateWithImplicitCredential
La valeur par défaut est Default.
Pour plus d’informations sur les valeurs de ce paramètre, consultez AuthenticationMechanism, énumération dans la bibliothèque MSDN.
Attention : l’authentification CredSSP (Credential Security Support Provider), dans laquelle les informations d’identification de l’utilisateur sont transmises à un ordinateur distant pour être authentifiées, est conçue pour les commandes qui nécessitent une authentification sur plusieurs ressources, telles que l’accès à un partage réseau distant. Ce mécanisme augmente le risque de sécurité lié à l'opération distante. Si l'ordinateur distant n'est pas fiable, les informations d'identification qui lui sont passées peuvent être utilisées pour contrôler la session réseau.
Type: | AuthenticationMechanism |
Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
Spécifie le certificat de clé publique numérique (X509) d'un compte d'utilisateur qui a l'autorisation d'exécuter cette action. Entrez l’empreinte numérique du certificat.
Les certificats sont utilisés dans l'authentification par certificat client. Ils peuvent être mappés uniquement aux comptes d'utilisateur locaux ; ils ne fonctionnent pas avec les comptes de domaine.
Pour obtenir un certificat, utilisez la commande Get-Item ou Get-ChildItem dans le lecteur Cert: de Windows PowerShell.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ComputerName
Spécifie un tableau de noms d’ordinateurs. Cette applet de commande crée une connexion permanente (PSSession) à l’ordinateur spécifié. Si vous entrez plusieurs noms d’ordinateurs, New-PSSession crée plusieurs objets PSSession , un pour chaque ordinateur. La valeur par défaut est l'ordinateur local.
Tapez le nom NetBIOS, l'adresse IP ou le nom de domaine complet d'un ou de plusieurs ordinateurs distants. Pour spécifier l’ordinateur local, tapez le nom de l’ordinateur, localhost ou un point (.). Lorsque l'ordinateur distant se trouve dans un domaine différent de celui de l'utilisateur, le nom de domaine complet est obligatoire. Vous pouvez également diriger un nom d’ordinateur, entre guillemets, vers New-PSSession.
Pour utiliser une adresse IP dans la valeur du paramètre ComputerName , la commande doit inclure le paramètre Credential . En outre, l'ordinateur doit être configuré pour le transport HTTPS ou l'adresse IP de l'ordinateur distant doit être incluse dans la liste TrustedHosts pour WinRM de l'ordinateur local. Pour obtenir des instructions sur l’ajout d’un nom d’ordinateur à la liste TrustedHosts, consultez « Comment ajouter un ordinateur à la liste d’hôtes approuvés » dans about_Remote_Troubleshooting (https://go.microsoft.com/fwlink/?LinkID=135188).
Pour inclure l’ordinateur local dans la valeur du paramètre ComputerName, démarrez Windows PowerShell à l’aide de l’option Exécuter en tant qu’administrateur.
Type: | String[] |
Aliases: | Cn |
Position: | 0 |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-ConfigurationName
Spécifie la configuration de session utilisée pour la nouvelle session PSSession.
Entrez un nom de configuration ou l'URI de ressource complet d'une configuration de session.
Si vous spécifiez uniquement le nom de la configuration, l’URI de schéma suivant est ajouté : https://schemas.microsoft.com/PowerShell
.
La configuration d'une session se trouve sur l'ordinateur distant. Si la configuration de session spécifiée n'existe pas sur l'ordinateur distant, la commande échoue.
La valeur par défaut est la valeur de la variable de préférence $PSSessionConfigurationName sur l'ordinateur local. Si cette variable de préférence n'est pas définie, la valeur par défaut est Microsoft.PowerShell. Pour plus d’informations, consultez about_Preference_Variables.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-ConnectionUri
Spécifie un URI qui définit le point de terminaison de connexion pour la session. L’URI doit être complet. Le format de cette chaîne est le suivant :
<Transport> ://<ComputerName> :<Port>/<ApplicationName>
La valeur par défaut est la suivante :
https://localhost:5985/WSMAN
Si vous ne spécifiez pas un ConnectionURI, vous pouvez utiliser les paramètres UseSSL, ComputerName, Port et ApplicationName pour spécifier les valeurs ConnectionURI.
Les valeurs valides du segment Transport de l'URI sont HTTP et HTTPS. Si vous spécifiez un URI de connexion avec un segment transport, mais que vous ne spécifiez pas de port, la session est créée avec des ports standards : 80 pour HTTP et 443 pour HTTPS. Pour utiliser les ports par défaut pour la communication à distance Windows PowerShell, spécifiez le port 5985 pour HTTP ou 5986 pour HTTPS.
Si l'ordinateur de destination redirige la connexion vers un URI différent, Windows PowerShell empêche la redirection, sauf si vous utilisez le paramètre AllowRedirection dans la commande.
Type: | Uri[] |
Aliases: | URI, CU |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Credential
Spécifie un compte d’utilisateur qui a l’autorisation d’exécuter cette action. La valeur par défaut est l’utilisateur actuel.
Tapez un nom d’utilisateur, tel que User01, Domain01\User01 ou User@Domain.com, ou entrez un objet PSCredential , tel qu’un objet retourné par l’applet de commande Get-Credential.
Lorsque vous tapez un nom d’utilisateur, cette applet de commande vous invite à entrer un mot de passe.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-EnableNetworkAccess
Indique que cette applet de commande ajoute un jeton de sécurité interactif aux sessions de bouclage. Le jeton interactif vous permet d'exécuter des commandes dans la session de bouclage qui obtiennent des données à partir d'autres ordinateurs. Par exemple, vous pouvez exécuter une commande dans la session qui copie les fichiers XML d'un ordinateur distant vers l'ordinateur local.
Une session de bouclage est une session PSSession qui provient et se termine sur le même ordinateur. Pour créer une session de bouclage, omettez le paramètre ComputerName ou définissez sa valeur sur point (.), localhost ou le nom de l’ordinateur local.
Par défaut, cette applet de commande crée des sessions de bouclage à l’aide d’un jeton réseau, qui peut ne pas fournir suffisamment d’autorisations pour s’authentifier sur des ordinateurs distants.
Le paramètre EnableNetworkAccess n'est effectif que dans les sessions de bouclage. Si vous utilisez EnableNetworkAccess lorsque vous créez une session sur un ordinateur distant, la commande réussit, mais le paramètre est ignoré.
Vous pouvez également activer l’accès à distance dans une session de bouclage à l’aide de la valeur CredSSP du paramètre Authentication , qui délègue les informations d’identification de session à d’autres ordinateurs.
Pour protéger l’ordinateur contre les accès malveillants, les sessions de bouclage déconnectées qui ont des jetons interactifs, qui sont ceux créés à l’aide du paramètre EnableNetworkAccess , ne peuvent être reconnectées qu’à partir de l’ordinateur sur lequel la session a été créée. Les sessions déconnectées qui utilisent l'authentification CredSSP peuvent être reconnectées à partir d'autres ordinateurs. Pour plus d’informations, consultez Disconnect-PSSession.
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 |
-Name
Spécifie un nom convivial pour la session PSSession.
Vous pouvez utiliser le nom pour faire référence à la session PSSession lorsque vous utilisez d’autres applets de commande, telles que Get-PSSession et Enter-PSSession. Le nom n'a pas obligatoirement à être unique sur l'ordinateur ou dans la session active.
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Port
Spécifie le port réseau sur l’ordinateur distant utilisé pour cette connexion. Pour établir une connexion à un ordinateur distant, l’ordinateur distant doit être à l’écoute sur le port utilisé par la connexion. Les ports par défaut sont 5985, qui est le port WinRM pour HTTP, et 5986, qui est le port WinRM pour HTTPS.
Avant d’utiliser un autre port, vous devez configurer l’écouteur WinRM sur l’ordinateur distant pour qu’il écoute sur ce port. Utilisez les commandes suivantes pour configurer l'écouteur :
1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}
N'utilisez pas le paramètre Port à moins que vous n'y soyez obligé. Le paramètre de port de la commande s'applique à tous les ordinateurs ou sessions sur lesquels la commande s'exécute. Un autre paramètre de port peut empêcher la commande de s'exécuter sur tous les ordinateurs.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Session
Spécifie un tableau d’objets PSSession que cette applet de commande utilise comme modèle pour la nouvelle session PSSession. Ce paramètre crée de nouveaux objets PSSession qui ont les mêmes propriétés que les objets PSSession spécifiés.
Entrez une variable qui contient les objets PSSession ou une commande qui crée ou obtient les objets PSSession , comme une commande New-PSSession ou Get-PSSession.
Les objets PSSession résultants ont le même nom d’ordinateur, le nom de l’application, l’URI de connexion, le port, le nom de configuration, la limite de limitation et la même valeur SSL (Secure Sockets Layer) que les originaux, mais ils ont un nom d’affichage, un ID et un ID de instance (GUID).
Type: | PSSession[] |
Position: | 0 |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-SessionOption
Spécifie les options avancées pour la session. Entrez un objet SessionOption , tel que celui que vous créez à l’aide de l’applet de commande New-PSSessionOption, ou une table de hachage dans laquelle les clés sont des noms d’options de session et les valeurs sont des valeurs d’option de session.
Les valeurs par défaut des options sont déterminées par la valeur de la variable de préférence PSSessionOption, si elle est définie. Sinon, les valeurs par défaut sont établies par les options définies dans la configuration de session.
Les valeurs des options de la session sont prioritaires sur les valeurs par défaut des sessions définies dans la variable de préférence $PSSessionOption 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 obtenir une description des options de session qui incluent les valeurs par défaut, consultez New-PSSessionOption. Pour plus d’informations sur la variable de préférence $PSSessionOption, consultez about_Preference_Variables. Pour plus d’informations sur les configurations de session, consultez about_Session_Configurations.
Type: | PSSessionOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThrottleLimit
Spécifie le nombre maximal de connexions simultanées qui peuvent être établies pour exécuter cette commande. Si vous omettez ce paramètre ou entrez la valeur 0 (zéro), la valeur par défaut 32 est utilisée.
La limite d'accélération s'applique uniquement à la commande actuelle, et non à la session ou à l'ordinateur.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseSSL
Indique que cette applet de commande utilise le protocole SSL pour établir une connexion à l’ordinateur distant. Par défaut, SSL n'est pas utilisé.
WS-Management chiffre tout le contenu Windows PowerShell transmis sur le réseau. Le paramètre UseSSL offre une protection supplémentaire qui envoie les données via une connexion HTTPS au lieu d’une connexion HTTP.
Si vous utilisez ce paramètre, mais que SSL n’est pas disponible sur le port utilisé pour la commande, la commande échoue.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Entrées
System.String, System.URI, System.Management.Automation.Runspaces.PSSession
Vous pouvez diriger une chaîne, un URI ou un objet de session vers cette applet de commande.
Sorties
Notes
Cette applet de commande utilise l'infrastructure d'accès à distance de Windows PowerShell. Pour utiliser cette applet de commande, l'ordinateur local et les ordinateurs distants doivent être configurés pour la communication à distance de Windows PowerShell. Pour plus d'informations, consultez about_Remote_Requirements.
Pour créer une session PSSession sur l’ordinateur local, démarrez Windows PowerShell avec l’option Exécuter en tant qu’administrateur.
Lorsque vous avez terminé la session PSSession, utilisez l’applet de commande Remove-PSSession pour supprimer la session PSSession et libérer ses ressources.