Invoke-Command

Syntaxe

Invoke-Command
      [-StrictMode <Version>]
      [-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>]
      [-FilePath] <String>
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-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
      [-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]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-Subsystem <String>]
      [-ConnectingTimeout <Int32>]
      [-SSHTransport]
      [-Options <Hashtable>]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<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]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-Subsystem <String>]
      [-ConnectingTimeout <Int32>]
      [-SSHTransport]
      [-Options <Hashtable>]
      [-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 (connexion persistante) sur l’ordinateur distant, puis utilisez le paramètre Session de l’exécution de Invoke-Command la commande dans PSSession. Pour exécuter une commande dans une session déconnectée, utilisez le paramètre InDisconnectedSession . Pour exécuter une commande dans un travail en arrière-plan, utilisez le paramètre AsJob .

Vous pouvez également utiliser Invoke-Command sur un ordinateur local pour exécuter un bloc de script en tant que commande. PowerShell exécute immédiatement le bloc de script 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 La communication à distance PowerShell via SSH.

Certains exemples de code utilisent l’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 situé 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 lorsque la commande est 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 : Appeler une commande avec un bloc de script stocké dans une variable

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

$command = {
    Get-WinEvent -LogName PowerShellCore/Operational |
      Where-Object -FilterScript { $_.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 $command sur 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 des 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. Au lieu de cela, 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 pour 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 travail 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 canalise l’objet de travail dans $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 qui est précédée par le Using modificateur d’étendue pour indiquer qu’elle a été créée dans la session locale, et non dans la session distante.

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. Il 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 -HideComputerName -ScriptBlock {
    Get-Process PowerShell
}

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 passer 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 qui ont 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, Name et Include 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 passer des valeurs de tableau à des positions de paramètre dans un bloc de script. Cet exemple montre comment afficher le contenu du répertoire d’un serveur des .txt fichiers. Le Get-ChildItem paramètre Path est la position 0 et le paramètre Filter est la 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 et $args[1] les $args[0] valeurs de tableau. ArgumentList transmet les $args valeurs de tableau aux positions des Get-ChildItem paramètres 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 Invoke-Command de commande pour exécuter le Sample.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.

$parameters = @{
    ComputerName = (Get-Content Servers.txt)
    FilePath     = 'C:\Scripts\Sample.ps1'
    ArgumentList = 'Process', 'Service'
}
Invoke-Command @parameters

Lorsque vous envoyez la commande, le contenu du fichier est copié dans un bloc de Sample.ps1 script et le bloc de script est exécuté sur chacun des ordinateurs distants. Cette procédure équivaut à utiliser le 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 à passer à 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 du 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
$parameters = @{
    ComputerName  = 'server01'
    UseSSL        = $true
    ScriptBlock   = { Get-HotFix }
    SessionOption = $so
    Credential    = 'server01\user01'
}
Invoke-Command @parameters

L’applet New-PSSessionOption de commande crée un objet d’option de session qui empêche la fin distante de 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.

L’applet Invoke-Command de commande exécute une Get-HotFix commande à distance. Le paramètre SessionOption reçoit 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 serveur Microsoft Exchange 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 sans fin.

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

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 CredSSP (Credential Security Support Provider) requise est activée dans les paramètres client de l’ordinateur local et dans les paramètres de 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 = @{
  ComputerName   = 'Server02'
  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 de l’ordinateur local Server01 vers 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         = [timespan]::FromHours(12)
  }
}
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 Drop sur et la valeur IdleTimeout est définie sur 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 obtenez 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.

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

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\GetInfo.ps1 -SSHConnection $sshConnections

Exemple 22 : Se connecter à une session SSH distante à l’aide d’options SSH

Cet exemple montre comment exécuter un fichier de script sur un ordinateur Linux distant à l’aide d’options SSH. Le paramètre Options prend une table de hachage de valeurs qui sont passées en tant qu’options à la commande sous-jacente ssh , la connexion établie au système distant.

$options = @{
    Port=22
    User = 'UserB'
    Host = 'LinuxServer5'
}
$results = Invoke-Command -FilePath c:\Scripts\CollectEvents.ps1 -KeyFilePath '/Users/UserB/id_rsa' -Options $options

Paramètres

-AllowRedirection

-ApplicationName

-ArgumentList

-AsJob

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-ConnectingTimeout

-ConnectionUri

-ContainerId

-Credential

-EnableNetworkAccess

-FilePath

-HideComputerName

-HostName

-InDisconnectedSession

-InputObject

-JobName

-KeyFilePath

-NoNewScope

-Options

-Port

-RemoteDebug

-RunAsAdministrator

-ScriptBlock

-Session

-SessionName

-SessionOption

-SSHConnection

-SSHTransport

-Subsystem

-ThrottleLimit

-UserName

-UseSSL

-VMId

-VMName

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

Si vous utilisez le paramètre AsJob , cette applet de commande retourne un objet de travail.

PSSession

Si vous utilisez le paramètre InDisconnectedSession , cette applet de commande retourne un objet PSSession .

Object

Par défaut, cette applet de commande retourne la sortie de la commande appelée, qui est la valeur du paramètre ScriptBlock .

Notes

PowerShell inclut les alias suivants pour Invoke-Command:

• Toutes les plateformes :
  • icm

Sur Windows Vista et les versions ultérieures du système d’exploitation Windows, pour utiliser le paramètre ComputerName de Invoke-Command l’exécution d’une 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 garantit que la fin des erreurs sur un ordinateur ne ferme pas la commande sur tous les ordinateurs sur lesquels elle est exécutée. 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 est relative à la session active. Une valeur de 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 valeur de disponibilité de None indique 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 la 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 fonctionnent 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ée 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 La communication à distance PowerShell via SSH.

L’exécutable ssh obtient les données de configuration à partir des sources suivantes dans l’ordre suivant :

1. options de ligne de commande
2. fichier de configuration de l’utilisateur (~/.ssh/config)
3. fichier de configuration à l’échelle du système (/etc/ssh/ssh_config)

Les paramètres d’applet de commande suivants sont mappés dans ssh les paramètres et les options :

Paramètre d’applet de commande	paramètre ssh	option ssh -o équivalente
-KeyFilePath	-i <KeyFilePath>	-o IdentityFile=<KeyFilePath>
-UserName	-l <UserName>	-o User=<UserName>
-Port	-p <Port>	-o Port=<Port>
-ComputerName -Subsystem	-s <ComputerName> <Subsystem>	-o Host=<ComputerName>

Toutes les valeurs transmises explicitement par les paramètres sont prioritaires sur les valeurs passées dans la table de hachage Options . Pour plus d’informations sur les ssh_config fichiers, consultez ssh_config(5).

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