Invoke-Command

Module:

Microsoft.PowerShell.Core

Exécute des commandes sur des ordinateurs locaux et distants.

Syntax

Invoke-Command
      [-ScriptBlock] <ScriptBlock>
      [-NoNewScope]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <String[]>]
      [-Credential <PSCredential>]
      [-Port <Int32>]
      [-UseSSL]
      [-ConfigurationName <String>]
      [-ApplicationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <String[]>]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <String>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <String[]>]
      [-Credential <PSCredential>]
      [-Port <Int32>]
      [-UseSSL]
      [-ConfigurationName <String>]
      [-ApplicationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <String[]>]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-Credential <PSCredential>]
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [[-ConnectionUri] <Uri[]>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <String>]
      [<CommonParameters>]

Invoke-Command
      [-Credential <PSCredential>]
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [[-ConnectionUri] <Uri[]>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMId] <Guid[]>
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMId] <Guid[]>
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]

Invoke-Command
      [-Port <Int32>]
      [-AsJob]
      [-HideComputerName]
      -ScriptBlock <ScriptBlock>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-SSHTransport]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-Subsystem <String>]
      [<CommonParameters>]

Invoke-Command
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -ContainerId <String[]>
      [<CommonParameters>]

Invoke-Command
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -ContainerId <String[]>
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      -ScriptBlock <ScriptBlock>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      -FilePath <String>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-SSHTransport]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      -FilePath <String>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Description

L’applet Invoke-Command de commande exécute des commandes sur un ordinateur local ou distant et retourne toutes les sorties des commandes, y compris les erreurs. À l’aide d’une seule Invoke-Command commande, vous pouvez exécuter des commandes sur plusieurs ordinateurs.

Pour exécuter une seule commande sur un ordinateur distant, utilisez le paramètre ComputerName. Pour exécuter une série de commandes associées qui partagent des données, utilisez l’applet New-PSSession de commande pour créer une session PSSession (une connexion persistante) sur l’ordinateur distant, puis utilisez le paramètre Session de l’exécution de Invoke-Command la commande dans la session PSSession. Pour exécuter une commande dans une session déconnectée, utilisez le paramètre InDisconnectedSession. Pour exécuter une commande dans une tâche en arrière-plan, utilisez le paramètre AsJob.

Vous pouvez également utiliser Invoke-Command sur un ordinateur local pour un bloc de script en tant que commande. PowerShell exécute le bloc de script immédiatement dans une étendue enfant de l’étendue actuelle.

Avant d’utiliser Invoke-Command pour exécuter des commandes sur un ordinateur distant, lisez about_Remote.

À compter de PowerShell 6.0, vous pouvez utiliser Secure Shell (SSH) pour établir une connexion et appeler des commandes sur des ordinateurs distants. SSH doit être installé sur l’ordinateur local et l’ordinateur distant doit être configuré avec un point de terminaison SSH PowerShell. L’avantage d’une session à distance PowerShell basée sur SSH est qu’elle fonctionne sur plusieurs plateformes (Windows, Linux, macOS). Pour la session basée sur SSH, vous utilisez les paramètres HostName ou SSHConnection pour spécifier l’ordinateur distant et les informations de connexion pertinentes. Pour plus d’informations sur la configuration de la communication à distance SSH PowerShell, consultez Communication à distance PowerShell via SSH.

Certains exemples de code utilisent la platissement pour réduire la longueur de ligne. Pour plus d’informations, consultez about_Splatting.

Exemples

Exemple 1 : Exécuter un script sur un serveur

Cet exemple exécute le Test.ps1 script sur l’ordinateur Server01.

Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01

Le paramètre FilePath spécifie un script qui se trouve sur l’ordinateur local. Le script s'exécute sur l'ordinateur distant et les résultats sont retournés à l'ordinateur local.

Exemple 2 : Exécuter une commande sur un serveur distant

Cet exemple exécute une Get-Culture commande sur l’ordinateur distant Server01.

Invoke-Command -ComputerName Server01 -Credential Domain01\User01 -ScriptBlock { Get-Culture }

Le paramètre ComputerName spécifie le nom de l’ordinateur distant. Le paramètre Credential est utilisé pour exécuter la commande dans le contexte de sécurité de Domain01\User01, un utilisateur autorisé à exécuter des commandes. Le paramètre ScriptBlock spécifie la commande à exécuter sur l’ordinateur distant.

En réponse, PowerShell demande le mot de passe et une méthode d’authentification pour le compte User01. Ensuite, il exécute la commande sur l'ordinateur Server01 et retourne le résultat.

Exemple 3 : Exécuter une commande dans une connexion persistante

Cet exemple exécute la même Get-Culture commande dans une session, à l’aide d’une connexion persistante, sur l’ordinateur distant nommé Server02.

$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
Invoke-Command -Session $s -ScriptBlock {Get-Culture}

L’applet New-PSSession de commande crée une session sur l’ordinateur distant Server02 et l’enregistre dans la $s variable. En règle générale, vous créez une session uniquement lorsque vous exécutez une série de commandes sur l’ordinateur distant.

L’applet Invoke-Command de commande exécute la Get-Culture commande sur Server02. Le paramètre Session spécifie la session enregistrée dans la $s variable.

En réponse, PowerShell exécute la commande dans la session sur l’ordinateur Server02.

Exemple 4 : Utiliser une session pour exécuter une série de commandes qui partagent des données

Cet exemple compare les effets de l’utilisation des paramètres ComputerName et Session de Invoke-Command. Il montre comment utiliser une session pour exécuter une série de commandes qui partagent les mêmes données.

Invoke-Command -ComputerName Server02 -ScriptBlock {$p = Get-Process PowerShell}
Invoke-Command -ComputerName Server02 -ScriptBlock {$p.VirtualMemorySize}
$s = New-PSSession -ComputerName Server02
Invoke-Command -Session $s -ScriptBlock {$p = Get-Process PowerShell}
Invoke-Command -Session $s -ScriptBlock {$p.VirtualMemorySize}

17930240

Les deux premières commandes utilisent le paramètre ComputerName pour Invoke-Command exécuter des commandes sur l’ordinateur distant Server02. La première commande utilise l’applet Get-Process de commande pour obtenir le processus PowerShell sur l’ordinateur distant et l’enregistrer dans la $p variable. La deuxième commande obtient la valeur de la propriété VirtualMemorySize du processus PowerShell.

Lorsque vous utilisez le paramètre ComputerName , PowerShell crée une session pour exécuter la commande. La session est fermée une fois la commande terminée. La $p variable a été créée dans une connexion, mais elle n’existe pas dans la connexion créée pour la deuxième commande.

Le problème est résolu en créant une session persistante sur l’ordinateur distant, puis en exécutant les deux commandes de la même session.

L’applet New-PSSession de commande crée une session persistante sur l’ordinateur Server02 et enregistre la session dans la $s variable. Les Invoke-Command lignes qui suivent utilisent le paramètre Session pour exécuter les deux commandes de la même session. Étant donné que les deux commandes s’exécutent dans la même session, la $p valeur reste active.

Exemple 5 : Entrer une commande stockée dans une variable locale

Cet exemple montre comment créer une commande stockée en tant que bloc de script dans une variable locale. Lorsque le bloc de script est enregistré dans une variable locale, vous pouvez spécifier la variable comme valeur du paramètre ScriptBlock .

$command = { Get-WinEvent -LogName PowerShellCore/Operational |
  Where-Object {$_.Message -like "*certificate*"} }
Invoke-Command -ComputerName S1, S2 -ScriptBlock $command

La $command variable stocke la Get-WinEvent commande mise en forme en tant que bloc de script. Exécute Invoke-Command la commande stockée sur $command les ordinateurs distants S1 et S2.

Exemple 6 : Exécuter une seule commande sur plusieurs ordinateurs

Cet exemple montre comment utiliser Invoke-Command pour exécuter une seule commande sur plusieurs ordinateurs.

$parameters = @{
  ComputerName = "Server01", "Server02", "TST-0143", "localhost"
  ConfigurationName = 'MySession.PowerShell'
  ScriptBlock = { Get-WinEvent -LogName PowerShellCore/Operational }
}
Invoke-Command @parameters

Le paramètre ComputerName spécifie une liste séparée par des virgules de noms d’ordinateurs. La liste des ordinateurs inclut la valeur localhost, qui représente l’ordinateur local. Le paramètre ConfigurationName spécifie une autre configuration de session. Le paramètre ScriptBlock s’exécute Get-WinEvent pour obtenir les journaux d’événements PowerShellCore/Operational de chaque ordinateur.

Exemple 7 : Obtenir la version du programme hôte sur plusieurs ordinateurs

Cet exemple obtient la version du programme hôte PowerShell s’exécutant sur 200 ordinateurs distants.

$version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {(Get-Host).Version}

Étant donné qu’une seule commande est exécutée, vous n’avez pas besoin de créer de connexions persistantes à chacun des ordinateurs. À la place, la commande utilise le paramètre ComputerName pour indiquer les ordinateurs. Pour spécifier les ordinateurs, il utilise l’applet Get-Content de commande pour obtenir le contenu du fichier Machine.txt, un fichier de noms d’ordinateurs.

L’applet Invoke-Command de commande exécute une Get-Host commande sur les ordinateurs distants. Il utilise la notation par points pour obtenir la propriété Version de l’hôte PowerShell.

Ces commandes s’exécutent une à la fois. Une fois les commandes terminées, la sortie des commandes de tous les ordinateurs est enregistrée dans la $version variable. La sortie inclut le nom de l'ordinateur d'où proviennent les données.

Exemple 8 : Exécuter un travail en arrière-plan sur plusieurs ordinateurs distants

Cet exemple exécute une commande sur deux ordinateurs distants. La Invoke-Command commande utilise le paramètre AsJob afin que la commande s’exécute en tant que travail en arrière-plan. Les commandes s’exécutent sur les ordinateurs distants, mais le travail existe sur l’ordinateur local. Les résultats sont transmis à l’ordinateur local.

$s = New-PSSession -ComputerName Server01, Server02
Invoke-Command -Session $s -ScriptBlock {Get-EventLog system} -AsJob

Id   Name    State      HasMoreData   Location           Command
---  ----    -----      -----         -----------        ---------------
1    Job1    Running    True          Server01,Server02  Get-EventLog system

$j = Get-Job
$j | Format-List -Property *

HasMoreData   : True
StatusMessage :
Location      : Server01,Server02
Command       : Get-EventLog system
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : e124bb59-8cb2-498b-a0d2-2e07d4e030ca
Id            : 1
Name          : Job1
ChildJobs     : {Job2, Job3}
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
StateChanged  :

$results = $j | Receive-Job

L’applet New-PSSession de commande crée des sessions sur les ordinateurs distants Server01 et Server02. L’applet Invoke-Command de commande exécute un travail en arrière-plan dans chacune des sessions. La commande utilise le paramètre AsJob pour exécuter la commande en tant que tâche en arrière-plan. Cette commande retourne un objet de tâche qui contient deux objets de tâche enfants, un pour chacune des tâches exécutées sur les deux ordinateurs distants.

La Get-Job commande enregistre l’objet de travail dans la $j variable. La $j variable est ensuite redirigée vers l’applet Format-List de commande pour afficher toutes les propriétés de l’objet de travail dans une liste. La dernière commande obtient les résultats des travaux. Il dirige l’objet de travail vers $j l’applet Receive-Job de commande et stocke les résultats dans la $results variable.

Exemple 9 : Inclure des variables locales dans une commande exécutée sur un ordinateur distant

Cet exemple montre comment inclure les valeurs des variables locales dans une commande exécutée sur un ordinateur distant. La commande utilise le modificateur d’étendue Using pour identifier une variable locale dans une commande distante. Par défaut, toutes les variables sont supposées être définies dans la session à distance. Le Using modificateur d’étendue a été introduit dans PowerShell 3.0. Pour plus d’informations sur le Using modificateur d’étendue, consultez about_Remote_Variables et about_Scopes.

$Log = "PowerShellCore/Operational"
Invoke-Command -ComputerName Server01 -ScriptBlock {Get-WinEvent -LogName $Using:Log -MaxEvents 10}

La $Log variable stocke le nom du journal des événements, PowerShellCore/Operational. L’applet Invoke-Command de commande s’exécute Get-WinEvent sur Server01 pour obtenir les dix événements les plus récents du journal des événements. La valeur du paramètre LogName est la $Log variable préfixée par le Using modificateur d’étendue pour indiquer qu’elle a été créée dans la session locale, et non dans la session à distance.

Exemple 10 : Masquer le nom de l’ordinateur

Cet exemple montre l’effet de l’utilisation du paramètre HideComputerName de Invoke-Command. HideComputerName ne modifie pas l’objet retourné par cette applet de commande. Elle modifie uniquement l’affichage. Vous pouvez toujours utiliser les applets de commande Format pour afficher la propriété PsComputerName de l’un des objets affectés.

Invoke-Command -ComputerName S1, S2 -ScriptBlock {Get-Process PowerShell}

PSComputerName    Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
--------------    -------  ------    -----      ----- -----   ------     --   -----------
S1                575      15        45100      40988   200     4.68     1392 PowerShell
S2                777      14        35100      30988   150     3.68     67   PowerShell

Invoke-Command -ComputerName S1, S2 -ScriptBlock {Get-Process PowerShell} -HideComputerName

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
-------  ------    -----      ----- -----   ------     --   -----------
575      15        45100      40988   200     4.68     1392 PowerShell
777      14        35100      30988   150     3.68     67   PowerShell

Les deux premières commandes utilisent Invoke-Command pour exécuter une Get-Process commande pour le processus PowerShell. La sortie de la première commande inclut la propriété PsComputerName, qui contient le nom de l'ordinateur sur lequel la commande a été exécutée. La sortie de la deuxième commande, qui utilise HideComputerName, n’inclut pas la colonne PsComputerName .

Exemple 11 : Utiliser le mot clé Param dans un bloc de script

Le Param mot clé et le paramètre ArgumentList sont utilisés pour transmettre des valeurs de variable à des paramètres nommés dans un bloc de script. Cet exemple montre comment afficher les noms de fichiers qui commencent par la lettre a et avoir l’extension .pdf .

Pour plus d’informations sur le Param mot clé, consultez about_Language_Keywords.

$parameters = @{
    ComputerName = "Server01"
    ScriptBlock = { Param ($param1,$param2) Get-ChildItem -Name $param1 -Include $param2 }
    ArgumentList = "a*", "*.pdf"
}
Invoke-Command @parameters

aa.pdf
ab.pdf
ac.pdf
az.pdf

Invoke-Command utilise le paramètre ScriptBlock qui définit deux variables et $param1$param2. Get-ChildItem utilise les paramètres nommés, nom et inclure avec les noms de variables. ArgumentList transmet les valeurs aux variables.

Exemple 12 : Utiliser la variable automatique $args dans un bloc de script

La $args variable automatique et le paramètre ArgumentList sont utilisés pour transmettre des valeurs de tableau aux positions de paramètre dans un bloc de script. Cet exemple montre comment afficher le contenu du répertoire d’un serveur de .txt fichiers. Le Get-ChildItem paramètre Path est position 0 et le paramètre Filter est position 1.

Pour plus d’informations sur la $args variable, consultez about_Automatic_Variables

$parameters = @{
    ComputerName = "Server01"
    ScriptBlock = { Get-ChildItem $args[0] $args[1] }
    ArgumentList = "C:\Test", "*.txt*"
}
Invoke-Command @parameters

Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           6/12/2019    15:15            128 alog.txt
-a---           7/27/2019    15:16            256 blog.txt
-a---           9/28/2019    17:10             64 zlog.txt

Invoke-Commandutilise un paramètre ScriptBlock et Get-ChildItem spécifie les valeurs de tableau et $args[1] de $args[0] tableau. ArgumentList transmet les $args valeurs de tableau aux Get-ChildItem positions de paramètre pour Path et Filter.

Exemple 13 : Exécuter un script sur tous les ordinateurs répertoriés dans un fichier texte

Cet exemple utilise l’applet de commande pour exécuter le Invoke-CommandSample.ps1 script sur tous les ordinateurs répertoriés dans le Servers.txt fichier. La commande utilise le paramètre FilePath pour spécifier le fichier de script. Cette commande vous permet d’exécuter le script sur les ordinateurs distants, même si le fichier de script n’est pas accessible aux ordinateurs distants.

Invoke-Command -ComputerName (Get-Content Servers.txt) -FilePath C:\Scripts\Sample.ps1 -ArgumentList Process, Service

Lorsque vous envoyez la commande, le contenu du Sample.ps1 fichier est copié dans un bloc de script et le bloc de script est exécuté sur chacun des ordinateurs distants. Cette procédure est équivalente à l'utilisation du paramètre ScriptBlock pour envoyer le contenu du script.

Exemple 14 : Exécuter une commande sur un ordinateur distant à l’aide d’un URI

Cet exemple montre comment exécuter une commande sur un ordinateur distant identifié par un URI (Uniform Resource Identifier). Cet exemple particulier exécute une Set-Mailbox commande sur un serveur Exchange distant.

$LiveCred = Get-Credential
$parameters = @{
  ConfigurationName = 'Microsoft.Exchange'
  ConnectionUri = 'https://ps.exchangelabs.com/PowerShell'
  Credential = $LiveCred
  Authentication = 'Basic'
  ScriptBlock = {Set-Mailbox Dan -DisplayName "Dan Park"}
}
Invoke-Command @parameters

La première ligne utilise l’applet Get-Credential de commande pour stocker les informations d’identification windows Live ID dans la $LiveCred variable. PowerShell invite l’utilisateur à entrer les informations d’identification windows Live ID.

La $parameters variable est une table de hachage contenant les paramètres à transmettre à l’applet Invoke-Command de commande. L’applet Invoke-Command de commande exécute une Set-Mailbox commande à l’aide de la configuration de session Microsoft.Exchange . Le paramètre ConnectionURI spécifie l'URL du point de terminaison de serveur Exchange. Le paramètre Credential spécifie les informations d’identification stockées dans la $LiveCred variable. Le paramètre AuthenticationMechanism spécifie l'utilisation de l'authentification de base. Le paramètre ScriptBlock spécifie un bloc de script qui contient la commande.

Exemple 15 : Utiliser une option de session

Cet exemple montre comment créer et utiliser un paramètre SessionOption .

$so = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
Invoke-Command -ComputerName server01 -UseSSL -ScriptBlock { Get-HotFix } -SessionOption $so -Credential server01\user01

L’applet New-PSSessionOption de commande crée un objet d’option de session qui provoque la fin distante de ne pas vérifier l’autorité de certification, le nom canonique et les listes de révocation lors de l’évaluation de la connexion HTTPS entrante. L’objet SessionOption est enregistré dans la $so variable.

Notes

La désactivation de ces vérifications est pratique pour la résolution des problèmes, mais évidemment pas sécurisée.

L’applet Invoke-Command de commande exécute une Get-HotFix commande à distance. Le paramètre SessionOption est donné à la $so variable.

Exemple 16 : Gérer la redirection d’URI dans une commande distante

Cet exemple montre comment utiliser les paramètres AllowRedirection et SessionOption pour gérer la redirection d’URI dans une commande distante.

$max = New-PSSessionOption -MaximumRedirection 1
$parameters = @{
  ConnectionUri = "https://ps.exchangelabs.com/PowerShell"
  ScriptBlock = { Get-Mailbox dan }
  AllowRedirection = $true
  SessionOption = $max
}
Invoke-Command @parameters

L’applet New-PSSessionOption de commande crée un objet PSSessionOption enregistré dans la $max variable. La commande utilise le paramètre MaximumRedirection pour définir la propriété MaximumConnectionRedirectionCount de l'objet PSSessionOption sur 1.

L’applet Invoke-Command de commande exécute une Get-Mailbox commande sur un Microsoft Exchange Server distant. Le paramètre AllowRedirection fournit une autorisation explicite pour rediriger la connexion vers un autre point de terminaison. Le paramètre SessionOption utilise l’objet de session stocké dans la $max variable.

Par conséquent, si l’ordinateur distant spécifié par ConnectionURI retourne un message de redirection, PowerShell redirige la connexion, mais si la nouvelle destination retourne un autre message de redirection, la valeur du nombre de redirections 1 est dépassée et Invoke-Command retourne une erreur de non-fin.

Exemple 17 : Accéder à un partage réseau dans une session distante

Cet exemple montre comment accéder à un partage réseau à partir d’une session distante. Trois ordinateurs sont utilisés pour illustrer l’exemple. Server01 est l’ordinateur local, Server02 est l’ordinateur distant et Net03 contient le partage réseau. Server01 se connecte à Server02, puis Server02 effectue un deuxième tronçon vers Net03 pour accéder au partage réseau. Pour plus d’informations sur la façon dont PowerShell Remoting prend en charge les tronçons entre les ordinateurs, consultez Création du deuxième tronçon dans PowerShell Remoting.

La délégation de support de sécurité des informations d’identification requise (CredSSP) est activée dans les paramètres client sur l’ordinateur local et dans les paramètres du service sur l’ordinateur distant. Pour exécuter les commandes de cet exemple, vous devez être membre du groupe Administrateurs sur l’ordinateur local et l’ordinateur distant.

Enable-WSManCredSSP -Role Client -DelegateComputer Server02
$s = New-PSSession Server02
Invoke-Command -Session $s -ScriptBlock {Enable-WSManCredSSP -Role Server -Force}
$parameters = @{
  Session = $s
  ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
  Authentication = "CredSSP"
  Credential = "Domain01\Admin01"
}
Invoke-Command @parameters

L’applet Enable-WSManCredSSP de commande active la délégation CredSSP à partir de l’ordinateur local Server01 sur l’ordinateur distant Server02. Le paramètre Rôle spécifie le client pour configurer le paramètre client CredSSP sur l’ordinateur local.

New-PSSession crée un objet PSSession pour Server02 et stocke l’objet dans la $s variable.

L’applet Invoke-Command de commande utilise la $s variable pour se connecter à l’ordinateur distant, Server02. Le paramètre ScriptBlock s’exécute Enable-WSManCredSSP sur l’ordinateur distant. Le paramètre Rôle spécifie le serveur pour configurer le paramètre de serveur CredSSP sur l’ordinateur distant.

La $parameters variable contient les valeurs de paramètre à connecter au partage réseau. L’applet Invoke-Command de commande exécute une Get-Item commande dans la session dans $s. Cette commande obtient un script à partir du \\Net03\Scripts partage réseau. La commande utilise le paramètre d’authentification avec la valeur CredSSP et le paramètre Credential avec la valeur Domain01\Admin01.

Exemple 18 : Démarrer des scripts sur de nombreux ordinateurs distants

Cet exemple exécute un script sur plus d’une centaine d’ordinateurs. Pour réduire au minimum l'impact sur l'ordinateur local, elle se connecte à chaque ordinateur, lance le script, puis se déconnecte de chaque ordinateur. Le script continue de s'exécuter dans les sessions déconnectées.

$parameters = @{
  ComputerName = (Get-Content -Path C:\Test\Servers.txt)
  InDisconnectedSession = $true
  FilePath = "\\Scripts\Public\ConfigInventory.ps1"
  SessionOption = @{OutputBufferingMode="Drop";IdleTimeout=43200000}
}
Invoke-Command @parameters

La commande utilise Invoke-Command pour exécuter le script. La valeur du paramètre ComputerName est une Get-Content commande qui obtient les noms des ordinateurs distants à partir d’un fichier texte. Le paramètre InDisconnectedSession déconnecte les sessions dès qu'il démarre la commande. La valeur du paramètre FilePath est le script qui Invoke-Command s’exécute sur chaque ordinateur.

La valeur de SessionOption est une table de hachage. La valeur OutputBufferingMode est définie sur Drop et la valeur IdleTimeout est définie sur 432000000 millisecondes (12 heures).

Pour obtenir les résultats des commandes et des scripts qui s’exécutent dans des sessions déconnectées, utilisez l’applet de Receive-PSSession commande.

Exemple 19 : Exécuter une commande sur un ordinateur distant à l’aide de SSH

Cet exemple montre comment exécuter une commande sur un ordinateur distant à l’aide de Secure Shell (SSH). Si SSH est configuré sur l’ordinateur distant pour demander des mots de passe, vous obtiendrez une invite de mot de passe. Sinon, vous devez utiliser l’authentification utilisateur basée sur des clés SSH.

Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * }

Exemple 20 : Exécuter une commande sur un ordinateur distant à l’aide de SSH et spécifier une clé d’authentification utilisateur

Cet exemple montre comment exécuter une commande sur un ordinateur distant à l’aide de SSH et spécifier un fichier de clé pour l’authentification utilisateur. Vous ne serez pas invité à entrer un mot de passe, sauf si l’authentification par clé échoue et que l’ordinateur distant est configuré pour autoriser l’authentification par mot de passe de base.

Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * } -KeyFilePath /UserA/UserAKey_rsa

Exemple 21 : Exécuter un fichier de script sur plusieurs ordinateurs distants à l’aide de SSH en tant que travail

Cet exemple montre comment exécuter un fichier de script sur plusieurs ordinateurs distants à l’aide de SSH et du jeu de paramètres SSHConnection . Le paramètre SSHConnection prend un tableau de tables de hachage qui contiennent des informations de connexion pour chaque ordinateur. Cet exemple nécessite que les ordinateurs distants cibles aient configuré SSH pour prendre en charge l’authentification utilisateur basée sur des clés.

$sshConnections =
@{ HostName="WinServer1"; UserName="Domain\UserA"; KeyFilePath="C:\Users\UserA\id_rsa" },
@{ HostName="UserB@LinuxServer5"; KeyFilePath="/Users/UserB/id_rsa" }
$results = Invoke-Command -FilePath c:\Scripts\CollectEvents.ps1 -SSHConnection $sshConnections

Paramètres

-AllowRedirection

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, 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 New-PSSessionOption de commande ou définissez la propriété MaximumConnectionRedirectionCount de la $PSSessionOption variable de préférence. La valeur par défaut est 5.

Type:	SwitchParameter
Position:	Named
Default value:	False
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 lorsque vous n’utilisez pas le paramètre ConnectionURI dans la commande.

La valeur par défaut est la valeur de la $PSSessionApplicationName variable de préférence 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:	$PSSessionApplicationName if set on the local computer, otherwise WSMAN
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ArgumentList

Fournit les valeurs des variables locales dans la commande. Les variables dans la commande sont remplacées par ces valeurs avant l'exécution de la commande sur l'ordinateur distant. Entrez les valeurs dans une liste séparée par des virgules. Les valeurs sont associées aux variables dans l’ordre dans lequel elles sont répertoriées. L’alias de ArgumentList est Args.

Les valeurs du paramètre ArgumentList peuvent être des valeurs réelles, telles que 1024, ou elles peuvent être des références à des variables locales, telles que $max.

Pour utiliser des variables locales dans une commande, utilisez le format de commande suivant :

{param($<name1>[, $<name2>]...) <command-with-local-variables>} -ArgumentList <value> ou <local-variable>

Le mot clé param répertorie les variables locales utilisées dans la commande. ArgumentList fournit les valeurs des variables, dans l’ordre dans lequel elles sont répertoriées. Pour plus d’informations sur le comportement d’ArgumentList, consultez about_Splatting.

Type:	Object[]
Aliases:	Args
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AsJob

Indique que cette applet de commande exécute la commande en tant que travail en arrière-plan sur un ordinateur distant. Utilisez ce paramètre pour exécuter des commandes qui prennent beaucoup de temps.

Lorsque vous utilisez le paramètre AsJob , la commande retourne un objet qui représente le travail, puis affiche l’invite de commandes. Vous pouvez continuer à travailler dans la session pendant l'exécution de la tâche. Pour gérer le travail, utilisez les *-Job applets de commande. Pour obtenir les résultats de la tâche, utilisez l'applet de commande Receive-Job.

Le paramètre AsJob ressemble à l’utilisation de l’applet Invoke-Command de commande pour exécuter une Start-Job applet de commande à distance. Toutefois, avec AsJob, le travail est créé sur l’ordinateur local, même si le travail s’exécute sur un ordinateur distant. Les résultats du travail distant sont automatiquement retournés à l’ordinateur local.

Pour plus d’informations sur les travaux en arrière-plan PowerShell, consultez about_Jobs et about_Remote_Jobs.

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

-Authentication

Spécifie le mécanisme utilisé pour authentifier les informations d’identification de l’utilisateur. L’authentification CredSSP est disponible uniquement dans Windows Vista, Windows Server 2008 et versions ultérieures du système d’exploitation Windows.

Les valeurs acceptables pour ce paramètre sont les suivantes :

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

Attention

l'authentification CredSSP (Credential Security Support 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 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. Pour plus d’informations, consultez le fournisseur de support de sécurité des informations d’identification.

Type:	AuthenticationMechanism
Accepted values:	Basic, Default, Credssp, Digest, Kerberos, Negotiate, NegotiateWithImplicitCredential
Position:	Named
Default value:	Default
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 de se connecter à la session déconnectée. Entrez l’empreinte numérique du certificat.

Les certificats sont utilisés dans l'authentification par certificat client. Ils ne peuvent être mappés qu’à des comptes d’utilisateur locaux et ne fonctionnent pas avec des comptes de domaine.

Pour obtenir une empreinte numérique de certificat, utilisez une ou Get-ChildItem une Get-Item commande dans le lecteur PowerShell Cert: .

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

-ComputerName

Spécifie les ordinateurs sur lesquels la commande s'exécute. La valeur par défaut est l'ordinateur local.

Lorsque vous utilisez le paramètre ComputerName , PowerShell crée une connexion temporaire utilisée uniquement pour exécuter la commande spécifiée, puis est fermée. Si vous avez besoin d’une connexion persistante, utilisez le paramètre Session .

Tapez le nom NETBIOS, l'adresse IP ou le nom de domaine complet d'un ou de plusieurs ordinateurs dans une liste séparée par des virgules. Pour spécifier l’ordinateur local, tapez le nom de l’ordinateur, localhost ou un point (.).

Pour utiliser une adresse IP dans la valeur de ComputerName, la commande doit inclure le paramètre Credential . L’ordinateur doit être configuré pour le transport HTTPS ou l’adresse IP de l’ordinateur distant doit être inclus dans la liste WinRM TrustedHosts de l’ordinateur local. Pour obtenir des instructions sur l’ajout d’un nom d’ordinateur à la liste TrustedHosts , voir How to Add a Computer to the Trusted Host List.

Sur Windows Vista et les versions ultérieures du système d’exploitation Windows, pour inclure l’ordinateur local dans la valeur de ComputerName, vous devez exécuter PowerShell à l’aide de l’option Exécuter en tant qu’administrateur .

Type:	String[]
Aliases:	Cn
Position:	0
Default value:	Local computer
Required:	False
Accept pipeline input:	False
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 configuration, l’URI de schéma suivant est prépendé : https://schemas.microsoft.com/PowerShell.

Lorsqu’il est utilisé avec SSH, ce paramètre spécifie le sous-système à utiliser sur la cible comme défini dans sshd_config. La valeur par défaut pour SSH est le powershell sous-système.

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 $PSSessionConfigurationName variable de préférence 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:	$PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ConnectionUri

Spécifie un URI (Uniform Resource Identifier) qui définit le point de terminaison de connexion de 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 d’URI de connexion, vous pouvez utiliser les paramètres UseSSL et Port pour spécifier les valeurs d’URI de connexion.

Les valeurs valides du segment Transport de l'URI sont HTTP et HTTPS. Si vous spécifiez un URI de connexion avec un segment de transport, mais ne spécifiez pas de port, la session est créée avec les ports standard : 80 pour HTTP et 443 pour HTTPS. Pour utiliser les ports par défaut pour la communication à distance PowerShell, spécifiez le port 5985 pour HTTP ou 5986 pour HTTPS.

Si l’ordinateur de destination redirige la connexion vers un AUTRE URI, 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:	https://localhost:5985/WSMAN
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContainerId

Spécifie un tableau d’ID de conteneur.

Type:	String[]
Position:	Named
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 ou Domain01\User01, ou entrez un objet PSCredential généré par l’applet Get-Credential de commande. Si vous tapez un nom d’utilisateur, vous êtes invité à entrer le mot de passe.

Les informations d’identification sont stockées dans un objet PSCredential et le mot de passe est stocké en tant que SecureString.

Notes

Pour plus d’informations sur la protection des données SecureString , consultez Comment SecureString est-il sécurisé ?.

Type:	PSCredential
Position:	Named
Default value:	Current user
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 dot (.), localhost ou le nom de l’ordinateur local.

Par défaut, les sessions de bouclage sont créées à l’aide d’un jeton réseau, ce qui peut ne pas fournir l’autorisation suffisante pour s’authentifier auprès 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 autoriser 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 l’accès malveillant, les sessions de bouclage déconnectées qui ont des jetons interactifs, qui sont ceux créés à l’aide d’EnableNetworkAccess, peuvent être reconnectées uniquement à 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 PowerShell 3.0.

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

-FilePath

Spécifie un script local que cette applet de commande s’exécute sur un ou plusieurs ordinateurs distants. Entrez le chemin d’accès et le nom de fichier du script, ou dirigez un chemin d’accès de script vers Invoke-Command. Le script doit exister sur l’ordinateur local ou dans un répertoire auquel l’ordinateur local peut accéder. Utilisez ArgumentList pour spécifier les valeurs des paramètres dans le script.

Lorsque vous utilisez ce paramètre, PowerShell convertit le contenu du fichier de script spécifié en bloc de script, transmet le bloc de script à l’ordinateur distant et l’exécute sur l’ordinateur distant.

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

-HideComputerName

Indique que cette applet de commande omet le nom d’ordinateur de chaque objet à partir de l’affichage de sortie. Par défaut, le nom de l'ordinateur qui a généré l'objet apparaît dans l'affichage.

Ce paramètre affecte uniquement l'affichage de la sortie. Il ne change pas l’objet.

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

-HostName

Spécifie un tableau de noms d’ordinateurs pour une connexion ssh (Secure Shell). Ceci est similaire au paramètre ComputerName , sauf que la connexion à l’ordinateur distant est effectuée à l’aide de SSH plutôt que de Windows WinRM.

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

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

-InDisconnectedSession

Indique que cette applet de commande exécute une commande ou un script dans une session déconnectée.

Lorsque vous utilisez le paramètre InDisconnectedSession , Invoke-Command crée une session persistante sur chaque ordinateur distant, démarre la commande spécifiée par le paramètre ScriptBlock ou FilePath , puis se déconnecte de la session. Les commandes continuent à s’exécuter dans les sessions déconnectées. InDisconnectedSession vous permet d’exécuter des commandes sans maintenir une connexion aux sessions distantes. Et, étant donné que la session est déconnectée avant que les résultats ne soient retournés, InDisconnectedSession vérifie que tous les résultats de commande sont retournés à la session reconnectée, au lieu d’être fractionnés entre les sessions.

Vous ne pouvez pas utiliser InDisconnectedSession avec le paramètre Session ou le paramètre AsJob .

Les commandes qui utilisent InDisconnectedSession retournent un objet PSSession qui représente la session déconnectée. Ils ne retournent pas la sortie de commande. Pour vous connecter à la session déconnectée, utilisez les applets de commande ou Receive-PSSession les Connect-PSSession applets de commande. Pour obtenir les résultats des commandes exécutées dans la session, utilisez l’applet Receive-PSSession de commande. Pour exécuter des commandes qui génèrent la sortie dans une session déconnectée, définissez la valeur de l’option de session OutputBufferingMode sur Drop. Si vous envisagez de vous connecter à la session déconnectée, définissez le délai d’inactivité dans la session afin qu’il fournisse suffisamment de temps pour vous connecter avant de supprimer la session.

Vous pouvez définir le mode de mise en mémoire tampon de sortie et le délai d’inactivité dans le paramètre SessionOption ou dans la $PSSessionOption variable de préférence. Pour plus d’informations sur les options de session, consultez New-PSSessionOption et about_Preference_Variables.

Pour plus d'informations sur la fonctionnalité Sessions déconnectées, consultez about_Remote_Disconnected_Sessions.

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

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

-InputObject

Spécifie l'entrée de la commande. Entrez une variable contenant les objets, ou tapez une commande ou une expression qui les obtient.

Lorsque vous utilisez le paramètre InputObject , utilisez la $Input variable automatique dans la valeur du paramètre ScriptBlock pour représenter les objets d’entrée.

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

-JobName

Spécifie un nom convivial pour la tâche en arrière-plan. Par défaut, les travaux sont nommés Job<n>, où <n> est un nombre ordinal.

Si vous utilisez le paramètre JobName dans une commande, la commande est exécutée en tant que travail et Invoke-Command retourne un objet de travail, même si vous n’incluez pas AsJob dans la commande.

Pour plus d’informations sur les travaux en arrière-plan PowerShell, consultez about_Jobs.

Type:	String
Position:	Named
Default value:	Job<n>
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyFilePath

Spécifie un chemin d’accès de fichier clé utilisé par Secure Shell (SSH) pour authentifier un utilisateur sur un ordinateur distant.

SSH permet à l’utilisateur d’effectuer l’authentification via des clés privées et publiques comme alternative à l’authentification par mot de passe de base. Si l’ordinateur distant est configuré pour l’authentification par clé, ce paramètre peut être utilisé pour fournir la clé qui identifie l’utilisateur.

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

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

-NoNewScope

Indique que cette applet de commande exécute la commande spécifiée dans l’étendue actuelle. Par défaut, Invoke-Command exécute des commandes dans leur propre étendue.

Ce paramètre est valide uniquement dans les commandes qui sont exécutées dans la session active, autrement dit, dans les commandes qui omettent les deux paramètres ComputerName et Session.

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

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

-Port

Spécifie le port réseau sur l’ordinateur distant utilisé pour cette commande. 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 (port WinRM pour HTTP) et 5986 (port WinRM pour HTTPS).

Avant d'utiliser un autre port, configurez l'écouteur WinRM sur l'ordinateur distant pour qu'il écoute sur ce port. Pour configurer l’écouteur, tapez les deux commandes suivantes à l’invite PowerShell :

Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse

New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>

N’utilisez pas le paramètre Port , sauf si vous devez. Le port défini dans la commande s'applique à tous les ordinateurs ou toutes les sessions sur lesquelles 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

-RemoteDebug

Utilisé pour exécuter la commande appelée en mode débogage dans la session PowerShell distante.

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

-RunAsAdministrator

Indique que cette applet de commande appelle une commande en tant qu’administrateur.

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

-ScriptBlock

Spécifie les commandes à exécuter. Placez les commandes en accolades { } pour créer un bloc de script. Ce paramètre est obligatoire.

Par défaut, les variables de la commande sont évaluées sur l'ordinateur distant. Pour inclure des variables locales dans la commande, utilisez ArgumentList.

Type:	ScriptBlock
Aliases:	Command
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Session

Spécifie un tableau de sessions dans lequel cette applet de commande exécute la commande. Entrez une variable qui contient des objets PSSession ou une commande qui crée ou obtient les objets PSSession , tels qu’une New-PSSession ou Get-PSSession une commande.

Lorsque vous créez une session PSSession, PowerShell établit une connexion persistante à l’ordinateur distant. Utilisez une session PSSession pour exécuter une série de commandes associées qui partagent des données. Pour exécuter une seule commande ou une série de commandes non liées, utilisez le paramètre ComputerName . Pour plus d’informations, consultez about_PSSessions.

Type:	PSSession[]
Position:	0
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionName

Spécifie un nom convivial pour une session déconnectée. Vous pouvez utiliser le nom pour faire référence à la session dans les commandes suivantes, telles qu’une Get-PSSession commande. Ce paramètre est valide uniquement avec le paramètre InDisconnectedSession.

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

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

-SessionOption

Spécifie les options avancées de la session. Entrez un objet SessionOption , tel qu’un que vous créez à l’aide de l’applet New-PSSessionOption de commande, ou une table de hachage dans laquelle les clés sont des noms d’option 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 $PSSessionOption variable de préférence, 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 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 la session. Toutefois, ils ne sont pas prioritaires sur les valeurs maximales, les quotas ou les limites définies dans la configuration de session.

Pour obtenir une description des options de session qui inclut les valeurs par défaut, consultez New-PSSessionOption. Pour plus d’informations sur la $PSSessionOption variable de préférence, 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

-SSHConnection

Ce paramètre prend un tableau de tables de hachage où chaque table de hachage contient un ou plusieurs paramètres de connexion nécessaires pour établir une connexion Secure Shell (SSH). Le paramètre SSHConnection est utile pour créer plusieurs sessions où chaque session nécessite des informations de connexion différentes.

Le tableau de hachage contient les membres suivants :

• ComputerName (ou HostName)
• Port
• UserName
• KeyFilePath (ou IdentityFilePath)

ComputerName (ou HostName) est la seule paire clé-valeur requise.

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

Type:	Hashtable[]
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-SSHTransport

Indique que la connexion distante est établie à l’aide de Secure Shell (SSH).

Par défaut, PowerShell utilise Windows WinRM pour se connecter à un ordinateur distant. Ce commutateur force PowerShell à utiliser le paramètre HostName pour établir une connexion distante basée sur SSH.

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

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

-Subsystem

Spécifie le sous-système SSH utilisé pour la nouvelle session PSSession.

Cela spécifie le sous-système à utiliser sur la cible comme défini dans sshd_config. Le sous-système démarre une version spécifique de PowerShell avec des paramètres prédéfinis. Si le sous-système spécifié n’existe pas sur l’ordinateur distant, la commande échoue.

Si ce paramètre n’est pas utilisé, la valeur par défaut est le sous-système « powershell ».

Type:	String
Position:	Named
Default value:	powershell
Required:	False
Accept pipeline input:	True
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, 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:	32
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UserName

Spécifie le nom d’utilisateur du compte utilisé pour exécuter une commande sur l’ordinateur distant. La méthode d’authentification utilisateur dépend de la configuration de Secure Shell (SSH) sur l’ordinateur distant.

Si SSH est configuré pour l’authentification par mot de passe de base, vous êtes invité à entrer le mot de passe utilisateur.

Si SSH est configuré pour l’authentification utilisateur basée sur des clés, un chemin d’accès au fichier clé peut être fourni via le paramètre KeyFilePath et aucune invite de mot de passe ne se produit. Si le fichier de clé utilisateur client se trouve dans un emplacement connu SSH, le paramètre KeyFilePath n’est pas nécessaire pour l’authentification basée sur des clés et l’authentification utilisateur se produit automatiquement en fonction du nom d’utilisateur. Pour plus d’informations, consultez la documentation SSH de votre plateforme sur l’authentification utilisateur basée sur des clés.

Ce paramètre n’est pas obligatoire. Si le paramètre UserName n’est pas spécifié, le nom d’utilisateur connecté actuel est utilisé pour la connexion.

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

Type:	String
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 (Secure Sockets Layer) pour établir une connexion à l’ordinateur distant. Par défaut, SSL n’est pas utilisé.

WS-Management chiffre tout le contenu PowerShell transmis sur le réseau. Le paramètre UseSSL est une protection supplémentaire qui envoie les données à un protocole HTTPS, au lieu de 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:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-VMId

Spécifie un tableau d’ID de machines virtuelles.

Type:	Guid[]
Aliases:	VMGuid
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-VMName

Spécifie un tableau de noms d'ordinateurs virtuels.

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

Entrées

ScriptBlock

Vous pouvez diriger une commande dans un bloc de script vers Invoke-Command. Utilisez la $Input variable automatique pour représenter les objets d’entrée dans la commande.

Sorties

System.Management.Automation.PSRemotingJob, System.Management.Automation.Runspaces.PSSession, or the output of the invoked command

Cette applet de commande retourne un objet de travail, si vous utilisez le paramètre AsJob . Si vous spécifiez le paramètre InDisconnectedSession , Invoke-Command retourne un objet PSSession . Sinon, elle retourne la sortie de la commande appelée, qui est la valeur du paramètre ScriptBlock .

Notes

Sur Windows Vista et les versions ultérieures du système d’exploitation Windows, pour utiliser le paramètre ComputerName de l’exécution d’une Invoke-Command commande sur l’ordinateur local, vous devez exécuter PowerShell à l’aide de l’option Exécuter en tant qu’administrateur .

Lorsque vous exécutez des commandes sur plusieurs ordinateurs, PowerShell se connecte aux ordinateurs dans l’ordre dans lequel ils apparaissent dans la liste. Toutefois, la sortie de commande s’affiche dans l’ordre dans lequel elle est reçue des ordinateurs distants, ce qui peut être différent.

Erreurs résultant de la commande qui Invoke-Command s’exécute sont incluses dans les résultats de la commande. Les erreurs qui seraient des erreurs avec fin d'exécution dans une commande locale sont traitées comme des erreurs sans fin d'exécution dans une commande à distance. Cette stratégie permet de s’assurer que la fin des erreurs sur un ordinateur ne ferme pas la commande sur tous les ordinateurs sur lesquels il est exécuté. Cette pratique est utilisée même quand une commande à distance est exécutée sur un seul ordinateur.

Si l’ordinateur distant n’est pas dans un domaine approuvé par l’ordinateur local, il se peut que l’ordinateur ne puisse pas authentifier les informations d’identification de l’utilisateur. Pour ajouter l’ordinateur distant à la liste des hôtes approuvés dans WS-Management, utilisez la commande suivante dans le WSMAN fournisseur, où <Remote-Computer-Name> se trouve le nom de l’ordinateur distant :

Set-Item -Path WSMan:\Localhost\Client\TrustedHosts -Value \<Remote-Computer-Name\>

Lorsque vous déconnectez une session PSSession à l’aide du paramètre InDisconnectedSession , l’état de session est Déconnecté et la disponibilité est None. La valeur de la propriété State dépend de la session active. La valeur Disconnected signifie que la session PSSession n’est pas connectée à la session active. Toutefois, cela ne signifie pas que la session PSSession est déconnectée de toutes les sessions. Elle peut être connectée à une autre session. Pour déterminer si vous pouvez vous connecter ou vous reconnecter à la session, utilisez la propriété Availability.

Une propriété Availability avec la valeur None signifie que vous pouvez vous connecter à la session. La valeur Busy indique que vous ne pouvez pas vous connecter à la session PSSession , car elle est connectée à une autre session. Pour plus d’informations sur les valeurs de la propriété State des sessions, consultez RunspaceState. Pour plus d’informations sur les valeurs de la propriété Availability des sessions, consultez RunspaceAvailability.

Les paramètres HostName et SSHConnection ont été inclus à partir de PowerShell 6.0. Ils ont été ajoutés pour fournir une communication à distance PowerShell basée sur Secure Shell (SSH). PowerShell et SSH sont pris en charge sur plusieurs plateformes (Windows, Linux, macOS) et la communication à distance PowerShell fonctionne sur ces plateformes où PowerShell et SSH sont installés et configurés. Cela est distinct de la communication à distance Windows précédente basée sur WinRM et la plupart des fonctionnalités et limitations spécifiques de WinRM ne s’appliquent pas. Par exemple, les quotas basés sur WinRM, les options de session, la configuration de point de terminaison personnalisé et les fonctionnalités de déconnexion/reconnexion ne sont actuellement pas prises en charge. Pour plus d’informations sur la configuration de la communication à distance SSH PowerShell, consultez Communication à distance PowerShell via SSH.

Liens associés

• about_PSSessions
• about_Remote
• about_Remote_Disconnected_Sessions
• about_Remote_Troubleshooting
• about_Remote_Variables
• about_Scopes
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Invoke-Item
• New-PSSession
• Remove-PSSession
• Fournisseur WSMan