New-PSSession
Crée une connexion permanente à un ordinateur local ou distant.
Syntaxe
New-PSSession [[-ComputerName] <string[]>] [-ApplicationName <string>] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-Port <int>] [-SessionOption <PSSessionOption>] [-UseSSL] [-ThrottleLimit <int>] [<CommonParameters>]
New-PSSession [[-Session] <PSSession[]>] [-Name <string[]>] [-ThrottleLimit <int>] [<CommonParameters>]
New-PSSession [-ConnectionURI] <Uri[]> [-AllowRedirection] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [<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, telle 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 la session PSSession pour interagir directement avec un ordinateur distant, utilisez l'applet de commande Enter-PSSession. Pour plus d'informations, consultez about_PSSessions.
Vous pouvez exécuter des commandes sur un ordinateur distant sans créer de session PSSession à l'aide des paramètres ComputerName d'Enter-PSSession ou Invoke-Command. Lorsque vous utilisez le paramètre ComputerName, Windows PowerShell crée une liaison temporaire qui est utilisée pour la session interactive ou pour une commande simple et qui est fermée ensuite.
Paramètres
-AllowRedirection
Autorise la redirection de cette connexion vers un autre URI (Uniform Resource Identifier).
Lorsque vous utilisez le paramètre ConnectionURI, la destination distante peut retourner une instruction pour rediriger vers un URI différent. Par défaut, Windows PowerShell ne redirige pas les connexions, mais vous pouvez utiliser le paramètre AllowRedirection pour lui permettre de rediriger la connexion.
Vous pouvez également limiter le nombre de redirections de la connexion en définissant la propriété MaximumConnectionRedirectionCount de la variable de préférence $PSSessionOption ou la propriété MaximumConnectionRedirectionCount de la valeur du paramètre SessionOption.
La valeur par défaut est 5. Pour plus d'informations, consultez la description du paramètre SessionOption et New-PSSessionOption.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-ApplicationName <string>
Spécifie le segment du nom d'application dans l'URI de connexion. Utilisez ce paramètre pour spécifier le nom d'application lorsque vous n'employez 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 d'application afin de sélectionner un écouteur pour le traitement de la demande de connexion. La valeur de ce paramètre doit correspondre à celle de la propriété URLPrefix d'un écouteur sur l'ordinateur distant.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
WSMAN |
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Authentication <AuthenticationMechanism>
Spécifie le mécanisme permettant d'authentifier les informations d'identification de l'utilisateur. Les valeurs valides sont « Default », « Basic », « Credssp », « Digest », « Kerberos », « Negotiate » et « NegotiateWithImplicitCredential ». La valeur par défaut est « Default ».
L'authentification CredSSP n'est disponible que dans Windows Vista, Windows Server 2008 et les versions ultérieures de Windows.
Pour plus d'informations sur les valeurs de ce paramètre, consultez la description de l'énumération System.Management.Automation.Runspaces.AuthenticationMechanism dans la bibliothèque MSDN (Microsoft Developer Network) à l'adresse https://go.microsoft.com/fwlink/?LinkID=144382.
Attention : l'authentification CredSSP (Credential Security Service Provider), au cours de laquelle les informations d'identification de l'utilisateur sont passées à un ordinateur distant pour être authentifiées, est conçue pour les commandes qui requièrent 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.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
Default |
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-CertificateThumbprint <string>
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 une authentification basée sur les certificats clients. Ils peuvent être mappés uniquement à des comptes d'utilisateur local ; ils ne fonctionnent pas avec des comptes de domaine.
Pour obtenir une empreinte numérique de certificat, utilisez la commande Get-Item ou Get-ChildItem sur le lecteur Cert: de Windows PowerShell.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-ComputerName <string[]>
Crée une connexion permanente (PSSession) à l'ordinateur spécifié. Si vous entrez plusieurs noms d'ordinateurs, New-PSSession crée plusieurs sessions PSSession : une pour chaque ordinateur. La valeur par défaut est l'ordinateur local.
Tapez le nom NetBIOS, une adresse IP ou un 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 se trouve dans un domaine différent de celui de l'utilisateur, le nom de domaine complet est requis. 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 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 des hôtes approuvés » dans about_Remote_Troubleshooting.
Remarque : dans Windows Vista et les versions ultérieures de Windows, pour inclure l'ordinateur local dans la valeur du paramètre ComputerName, vous devez démarrer Windows PowerShell avec l'option Exécuter en tant qu'administrateur.
Obligatoire ? |
false |
Position ? |
1 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByValue, ByPropertyName) |
Accepter les caractères génériques ? |
false |
-ConfigurationName <string>
Spécifie la configuration de session utilisée pour la nouvelle session PSSession.
Entrez un nom de configuration ou l'URI (Uniform Resource Identifier) 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é en tant que préfixe : 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.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-ConnectionURI <Uri[]>
Spécifie un URI (Uniform Resource Identifier) qui définit le point de terminaison de connexion. 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:80/WSMAN
Les valeurs valides pour le segment Transport de l'URI sont HTTP et HTTPS. Si vous ne spécifiez pas de valeur ConnectionURI, vous pouvez utiliser les paramètres UseSSL, ComputerName, Port et ApplicationName pour indiquer les valeurs d'URI.
Si l'ordinateur de destination redirige la connexion vers un URI différent, Windows PowerShell empêche la redirection à moins que vous n'utilisiez le paramètre AllowRedirection dans la commande.
Obligatoire ? |
true |
Position ? |
1 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Credential <PSCredential>
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, comme « User01 », « Domain01\User01 » ou « User@Domain.com », ou entrez un objet PSCredential, tel que celui retourné par l'applet de commande Get-Credential.
Lorsque vous tapez un nom d'utilisateur, vous êtes invité à entrer un mot de passe.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Name <string[]>
Spécifie un nom convivial pour la session PSSession.
Vous pouvez utiliser le nom pour faire référence à la session PSSession lors de l'utilisation d'autres applets de commande, telles que Get-PSSession et Enter-PSSession. Il n'est pas obligatoire que le nom soit unique à l'ordinateur ou à la session active.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-Port <int>
Spécifie le port réseau sur l'ordinateur distant utilisé pour cette commande. La valeur par défaut est le port 80 (le port HTTP).
Avant d'utiliser un autre port, vous devez configurer l'écouteur WinRM sur l'ordinateur distant pour écouter 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="<numéro-port>"}
N'utilisez pas le paramètre Port à moins d'y être obligé. Le paramètre de port de la commande s'applique à l'ensemble des ordinateurs et sessions où la commande s'exécute. Le paramètre d'un autre port peut empêcher l'exécution de la commande sur tous les ordinateurs.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
80 |
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-Session <PSSession[]>
Utilise la session PSSession spécifiée en tant que modèle pour la nouvelle session PSSession. Ce paramètre crée des sessions PSSession ayant les mêmes propriétés que les sessions PSSession spécifiées.
Entrez une variable qui contient les sessions PSSession ou une commande qui crée ou obtient les sessions PSSession, telle qu'une commande New-PSSession ou Get-PSSession.
Le nom d'ordinateur, le nom d'application, l'URI de connexion, le port, le nom de configuration, la limite d'accélération et la valeur SSL (Secure Sockets Layer) des sessions PSSession résultantes sont identiques à ceux des sessions d'origine, mais leurs nom d'affichage, ID et ID d'instance (GUID) sont différents.
Obligatoire ? |
false |
Position ? |
1 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByValue, ByPropertyName) |
Accepter les caractères génériques ? |
false |
-SessionOption <PSSessionOption>
Définit des options avancées pour la session. Entrez un objet SessionOption que vous créez à l'aide de l'applet de commande New-PSSessionOption.
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, la session utilise les valeurs par défaut du système.
Pour obtenir une description des options de session, notamment des valeurs par défaut, consultez New-PSSessionOption. Pour plus d'informations sur la variable de préférence $PSSessionOption, consultez about_Preference_Variables.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-ThrottleLimit <int>
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.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
32 |
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-UseSSL
Utilise le protocole SSL (Secure Sockets Layer) pour établir une connexion avec l'ordinateur distant. Par défaut, SSL n'est pas utilisé.
La Gestion des services Web chiffre tout le contenu Windows PowerShell transmis sur le réseau. UseSSL est une protection supplémentaire qui envoie les données via une connexion HTTPS plutôt que HTTP.
Si vous utilisez ce paramètre, mais que SSL n'est pas disponible sur le port utilisé pour la commande, la commande échoue.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
<CommonParameters>
Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.
Entrées et sorties
Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.
Entrées |
System.String, System.URI, System.Management.Automation.Runspaces.PSSession Vous pouvez diriger un objet ComputerName (chaîne), ConnectionURI (URI) ou Session (PSSession) vers New-PSSession. |
Sorties |
System.Management.Automation.Runspaces.PSSession |
Remarques
Cette applet de commande utilise l'infrastructure de communication à distance Windows PowerShell. Pour utiliser cette applet de commande, l'ordinateur local et tout ordinateur distant doivent être configurés pour la communication à distance Windows PowerShell. Pour plus d'informations, consultez about_Remote_Requirements.
Dans Windows Vista et les versions ultérieures de Windows, pour créer une session PSSession sur l'ordinateur local, vous devez démarrer Windows PowerShell avec l'option Exécuter en tant qu'administrateur.
Lorsque vous avez terminé avec la session PSSession, utilisez l'applet de commande Remove-PSSession pour supprimer la session PSSession et libérer ses ressources.
Exemple 1
C:\PS>$s = new-pssession
Description
-----------
Cette commande crée une session PSSession sur l'ordinateur local et l'enregistre dans la variable $s.
Vous pouvez maintenant utiliser cette session PSSession pour exécuter des commandes sur l'ordinateur local.
Exemple 2
C:\PS>$Server01 = new-pssession -ComputerName Server01
Description
-----------
Cette commande crée une nouvelle session PSSession sur l'ordinateur Server01 et la sauvegarde dans la variable $Server01.
Lorsque vous créez plusieurs sessions PSSession, assignez-les à des variables ayant des noms utiles. Cela vous aidera à gérer les sessions PSSession dans les commandes suivantes.
Exemple 3
C:\PS>$s1, $s2, $s3 = new-session -computername server1,server2,server3
Description
-----------
Cette commande crée trois nouvelles sessions PSSession, une sur chacun des ordinateurs spécifiés par le paramètre ComputerName.
Elle utilise l'opérateur d'affectation (=) pour affecter les nouvelles sessions PSSession à un tableau de variables : $s1, $s2, $s3. Elle attribue la session PSSession Server01 à $s1, la session PSSession Server02 à $s2, et la session PSSession Server03 à $s3.
Lorsque vous attribuez plusieurs objets à un tableau de variables, Windows PowerShell attribue respectivement chaque objet à une variable dans le tableau. S'il y a plus d'objets que de variables, tous les objets restants sont attribués à la dernière variable. S'il y a plus de variables que d'objets, les variables restantes sont vides (null).
Exemple 4
C:\PS>new-pssession -computername Server01 -port 8081 -useSSL -ConfigurationName E12
Description
-----------
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 pour écouter sur le port 8081. Pour plus d'informations, consultez la description du paramètre Port.
Exemple 5
C:\PS>new-pssession -session $s -credential domain01\user01
Description
-----------
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 fait appel au 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 s'exécuter.
Exemple 6
C:\PS>$global:s = new-pssession -computername server1.domain44.corpnet.fabrikam.com -credential domain01\admin01
Description
-----------
Cet exemple montre comment créer une session PSSession avec une portée globale sur un ordinateur qui se trouve dans un autre domaine.
Par défaut, les sessions PSSession créées à la ligne de commande le sont avec une portée locale et les sessions PSSession créées dans un script ont la portée du script.
Pour créer une session PSSession avec une portée globale, créez une nouvelle session PSSession, puis stockez-la dans une variable qui est convertie en portée globale. Dans ce cas, la variable $s est convertie en portée globale.
Cette commande utilise le paramètre ComputerName pour spécifier l'ordinateur distant. Parce que l'ordinateur est dans un domaine différent que le compte d'utilisateur, son nom complet est spécifié en même temps que les informations d'identification de l'utilisateur.
Exemple 7
C:\PS>$rs = get-content c:\test\servers.txt | new-PSsession -throttleLimit 50
Description
-----------
Cette commande crée une session PSSession sur chacun des 200 ordinateurs répertoriés dans le fichier Servers.txt, puis stocke la session PSSession résultante dans la variable $rs. La limite d'accélération des sessions PSSession est 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 sous un autre format convertible en texte.
Exemple 8
C:\PS>$s = new-PSSession -URI http://Server01:91/NewSession -credential domain01\user01
Description
-----------
Cette commande crée une session PSSession sur l'ordinateur Server01 et la stocke dans la variable $s. Elle utilise le paramètre URI pour spécifier le protocole de transport, l'ordinateur distant, le port et une autre configuration de session. Elle utilise également le paramètre Credential pour spécifier un compte d'utilisateur avec l'autorisation de créer une session sur l'ordinateur distant.
Exemple 9
C:\PS>$s = new-PSSession -computername (import-csv servers.csv) -credential domain01\admin01 -throttlelimit 16
C:\PS> invoke-command -session $s -scriptblock {get-process powershell} -AsJob
Description
-----------
Ces commandes créent un jeu de sessions PSSession puis exécutent une tâche en arrière-plan dans chacune d'elles.
La première commande crée une nouvelle session PSSession sur chacun des ordinateurs répertoriés dans le fichier Servers.csv. Elle 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 Import-Csv pour importer le fichier Servers.csv et lire son contenu.
Cette commande utilise le paramètre Credential pour créer les sessions PSSession avec l'autorisation d'un administrateur de domaine et le paramètre ThrottleLimit pour limiter la commande à 16 connexions simultanées. Elle enregistre les sessions PSSession dans la variable $s.
La deuxième commande utilise le paramètre AsJob d'Invoke-Command pour démarrer une tâche en arrière-plan qui exécute une commande « Get-Process PowerShell » dans chacune des sessions PSSession stockées dans $s.
Pour plus d'informations sur les tâches en arrière-plan, consultez about_Jobs et about_Remote_Jobs.
Exemple 10
C:\PS>new-PSSession -ConnectionURI https://management.exchangelabs.com/Management
Description
-----------
Cette commande crée une nouvelle session PSSession qui se connecte à un ordinateur spécifié par un URI, et non par un nom d'ordinateur.
Exemple 11
C:\PS>$so = New-WSManSessionOption -SkipCACheck
PS C:\> new-pssession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -credential server01\admin01
Description
-----------
Cet exemple montre comment créer et utiliser un paramètre SessionOption.
La première commande utilise l'applet de commande New-WSManSessionOption pour créer une option de session. Elle enregistre l'objet SessionOption résultant dans le paramètre $so.
La deuxième commande utilise l'option dans une nouvelle session. Elle utilise l'applet de commande New-PSSession pour créer une nouvelle session. La valeur du paramètre SessionOption est l'objet SessionOption dans la variable $so.
Voir aussi
Concepts
about_PSSessions
about_Remote
Get-PSSession
Remove-PSSession
Enter-PSSession
Exit-PSSession
Invoke-Command