Invoke-Command

Invoke-Command [-ScriptBlock] <scriptblock> [[-ComputerName] <string[]>] [-ApplicationName <string>] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-Port <int>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-UseSSL] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-FilePath] <string> [[-ComputerName] <string[]>] [-ApplicationName <string>] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-Port <int>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-UseSSL] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-FilePath] <string> [[-Session] <PSSession[]>] [-AsJob] [-HideComputerName] [-JobName <string>] [-ThrottleLimit <int>] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-FilePath] <string> [[-ConnectionURI] <Uri[]>] [-AllowRedirection] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-ScriptBlock] <scriptblock> [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-ScriptBlock] <scriptblock> [[-Session] <PSSession[]>] [-AsJob] [-HideComputerName] [-JobName <string>] [-ThrottleLimit <int>] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-ScriptBlock] <scriptblock> [[-ConnectionURI] <Uri[]>] [-AllowRedirection] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

C:\PS>invoke-command -filepath c:\scripts\test.ps1 -computerName Server01

Disks: C:, D:, E:
Status: Warning, Normal, Normal

Description
-----------
Cette commande exécute le script Test.ps1 sur l'ordinateur Server01. 

Elle utilise le paramètre FilePath pour spécifier un script se trouvant sur l'ordinateur local. Le script s'exécute sur l'ordinateur distant et les résultats sont renvoyés à l'ordinateur local.

C:\PS>invoke-command -computername server01 -credential domain01\user01 -scriptblock {get-culture}

Description
-----------
Cette commande exécute une commande Get-Culture sur l'ordinateur distant Server01. 

Elle utilise le paramètre ComputerName pour spécifier le nom d'ordinateur et le paramètre Credential pour exécuter la commande dans le contexte de sécurité de « Domain01\User01 », un utilisateur qui a l'autorisation d'exécuter des commandes. Elle utilise le paramètre ScriptBlock pour spécifier la commande à exécuter sur l'ordinateur distant.

En réponse, Windows PowerShell affiche une boîte de dialogue qui demande le mot de passe et une méthode d'authentification pour le compte User01. Il exécute alors la commande sur l'ordinateur Server01 et retourne le résultat.

C:\PS>$s = new-pssession -computername server02 -credential domain01\user01

C:\PS> invoke-command -session $s -scriptblock {get-culture}

Description
-----------
Cet exemple exécute la même commande « Get-Culture » dans une session (une connexion permanente) sur l'ordinateur distant Server02. En général, vous créez une session uniquement lorsque vous exécutez une série de commandes sur l'ordinateur distant.

La première commande utilise l'applet de commande New-PSSession pour créer une session sur l'ordinateur distant Server02. Elle enregistre ensuite la session dans la variable $s.

La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter la commande Get-Culture sur Server02. Elle utilise le paramètre Session pour spécifier la session enregistrée dans la variable $s. 

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

C:\PS>invoke-command -computername Server02 -scriptblock {$p = get-process powershell}

C:\PS> invoke-command -computername Server02 -scriptblock {$p.virtualmemorysize}
C:\PS>

C:\PS> $s = new-pssession -computername Server02
C:\PS> invoke-command -session $s -scriptblock {$p = get-process powershell}
C:\PS> invoke-command -session $s -scriptblock {$p.virtualmemorysize}
17930240

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

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

La première commande réussit. Toutefois, la deuxième commande échoue ; en effet, lorsque vous utilisez le paramètre ComputerName, Windows PowerShell crée une connexion uniquement pour exécuter la commande. Il ferme ensuite la connexion lorsque la commande est terminée. La variable $p 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 par la création d'une session (connexion permanente) sur l'ordinateur distant et par l'exécution des deux commandes connexes dans la même session.

La troisième commande utilise l'applet de commande New-PSSession pour créer une session sur l'ordinateur Server02. Elle enregistre ensuite la session dans la variable $s. Les quatrième et cinquième commandes répètent la série de commandes utilisée dans le premier jeu, mais dans ce cas, la commande Invoke-Command utilise le paramètre Session pour exécuter les deux commandes dans la même session. 

Dans ce cas, parce que les deux commandes s'exécutent dans la même session, elles réussissent, et la valeur $p reste active dans la session $s pour une utilisation ultérieure.

C:\PS>$command = { get-eventlog -log "windows powershell" | where {$_.message -like "*certificate*"} }

C:\PS> invoke-command -computername S1, S2 -scriptblock $command

Description
-----------
Cet exemple montre comment entrer une commande qui est enregistrée dans une variable locale. 

Lorsque la commande entière est enregistrée dans une variable locale, vous pouvez spécifier la variable comme la valeur du paramètre ScriptBlock. Vous n'avez pas à utiliser le mot clé « param » ou la variable ArgumentList pour envoyer la valeur de la variable locale.

La première commande enregistre une commande Get-Eventlog dans la variable $command. Elle est mise en forme comme un bloc de script.

La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter la commande de $command sur les ordinateurs distants S1 et S2.

C:\PS>invoke-command -computername server01, server02, TST-0143, localhost -configurationname MySession.PowerShell -scriptblock {get-eventlog "windows powershell"}

Description
-----------
Cet exemple montre comment utiliser l'applet de commande Invoke-Command pour exécuter une commande simple sur plusieurs ordinateurs. 

Elle utilise le paramètre ComputerName pour spécifier les ordinateurs. Les noms d'ordinateurs sont présentés dans une liste séparée par des virgules. La liste d'ordinateurs inclut la valeur « localhost », qui représente l'ordinateur local.

Cette commande utilise le paramètre ConfigurationName pour spécifier une autre configuration de session pour Windows PowerShell et le paramètre ScriptBlock pour spécifier la commande.

Dans cet exemple, la commande qui se trouve dans le bloc de script obtient les événements dans le journal des événements Windows PowerShell sur chaque ordinateur distant.

C:\PS>$version = invoke-command -computername (get-content machines.txt) -scriptblock {(get-host).version}

Description
-----------
Cette commande obtient la version de l'hôte Windows PowerShell qui s'exécute sur 200 ordinateurs distants. 

Parce qu'une seule commande est exécutée, il n'est pas nécessaire de créer des connexions permanentes (sessions) avec chacun des ordinateurs. À la place, la commande utilise le paramètre ComputerName pour indiquer les ordinateurs.

Elle utilise l'applet de commande Invoke-Command pour exécuter une commande Get-Host. Elle utilise la notation par points pour obtenir la propriété Version de l'hôte Windows PowerShell.

Pour spécifier les ordinateurs, elle utilise l'applet de commande Get-Content afin d'obtenir le contenu du fichier Machine.txt, un fichier de noms d'ordinateurs.

Ces commandes sont exécutées de façon synchrone (une par une). Lorsque les commandes s'achèvent, la sortie des commandes de tous les ordinateurs est enregistrée dans la variable $version. La sortie inclut le nom de l'ordinateur duquel proviennent les données.

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s -scriptblock {get-eventlog system} -AsJob

Id   Name    State      HasMoreData   Location           Command
---  ----    -----      -----         -----------        --------             -------
1    Job1    Running    True          Server01,Server02  get-eventlog system


C:\PS> $j = Get-Job

C:\PS> $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  :

C:\PS> $results = $j | Receive-Job

Description
-----------
Ces commandes exécutent une tâche en arrière-plan sur deux ordinateurs distants. Étant donné que la commande Invoke-Command utilise le paramètre AsJob, les commandes sont exécutées sur les ordinateurs distants, mais la tâche réside réellement sur l'ordinateur local et les résultats sont transmis à l'ordinateur local.

La première commande utilise l'applet de commande New-PSSession pour créer des sessions sur les ordinateurs distants Server01 et Server02.

La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter une tâche en arrière-plan dans chacune des sessions. Elle 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 traitement qui contient deux objets tâche enfants, un pour chacune des tâches exécutées sur les deux ordinateurs distants.

La troisième commande utilise une commande Get-Job pour enregistrer l'objet de traitement dans la variable $j. 

La quatrième commande utilise un opérateur de pipeline (|) pour envoyer la valeur de la variable $j à l'applet de commande Format-List, qui affiche toutes les propriétés de l'objet de traitement dans une liste.

La cinquième commande obtient les résultats des tâches. Elle dirige l'objet de traitement stocké dans $j vers l'applet de commande Receive-Job et stocke les résultats dans la variable $results.

C:\PS>$MWFO-LOg = Microsoft-Windows-Forwarding/Operational

C:\PS> invoke-command -computername server01 -scriptblock {param($log, $num) get-eventlog -logname $log -newest $num} -ArgumentList $MWFO-log, 10

Description
-----------
Cet exemple montre comment inclure les valeurs des variables locales dans une commande exécutée sur un ordinateur distant.

La première commande enregistre le nom du journal des événements Microsoft-Windows-Forwarding/Operational dans la variable $MWFO-Log.

La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter une commande Get-EventLog sur l'ordinateur distant Server01 qui obtient les 10 derniers événements du journal des événements Microsoft-Windows-Forwarding/Operational sur Server01.

Cette commande utilise le mot clé « param » pour créer deux variables, $log et $num, qui servent d'espaces réservés dans la commande Get-EventLog. Ces espaces réservés ont des noms arbitraires qui ne doivent pas correspondre à ceux des variables locales qui fournissent leurs valeurs.

Les valeurs du paramètre ArgumentList démontrent les deux méthodes différentes pour spécifier des valeurs dans la liste d'arguments. La valeur de l'espace réservé $log est la variable $MFWO-Log, définie dans la première commande. La valeur de la variable $num est 10.

Avant que la commande ne soit envoyée à l'ordinateur distant, les variables sont remplacées par les valeurs spécifiées.

C:\PS>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


C:\PS> 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

Description
-----------
Cet exemple montre l'effet de l'utilisation du paramètre HideComputerName d'Invoke-Command. 

Les deux premières commandes utilisent l'applet de commande Invoke-Command pour exécuter une commande Get-Process 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 s'est exécutée. La sortie de la deuxième commande, qui utilise le paramètre HideComputerName, n'inclut pas la colonne PsComputerName.

Le fait d'utiliser le paramètre HideComputerName ne modifie pas l'objet. Vous pouvez toujours utiliser les applets de commande Format pour afficher la propriété PsComputerName de n'importe lequel des objets affectés.

C:\PS>invoke-command -comp (get-content servers.txt) -filepath c:\scripts\sample.ps1 -argumentlist Process, Service

Description
-----------
Cet exemple utilise l'applet de commande Invoke-Command pour exécuter le script Sample.ps1 sur tous les ordinateurs répertoriés dans le fichier Servers.txt. La commande utilise le paramètre FilePath pour spécifier le fichier script. Elle 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.

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

C:\PS>$LiveCred = Get-Credential

C:\PS> Invoke-Command -ConfigurationName Microsoft.Exchange `
         -ConnectionUri https://ps.exchangelabs.com/powershell `
         -Credential $LiveCred  -Authentication Basic `
         -scriptblock {Invoke-Command {Set-Mailbox dan -DisplayName "Dan Park"}

Description
-----------
Cet exemple montre comment exécuter une commande sur un ordinateur distant identifié par un URI (adresse Internet). Cet exemple particulier exécute une commande Set-Mailbox sur un serveur Exchange distant. Le backtick (`) utilisé dans la commande est le caractère de continuation de ligne dans Windows PowerShell.

La première commande utilise l'applet de commande Get-Credential pour stocker des informations d'identification Windows Live ID dans la variable $LiveCred. Lorsque la boîte de dialogue des informations d'identification s'affiche, entrez les informations d'identification Windows Live ID.

La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter une commande Set-Mailbox. Elle utilise le paramètre ConfigurationName pour spécifier que la commande doit fonctionner dans une session qui utilise la configuration de session Microsoft.Exchange. Le paramètre ConnectionURI spécifie l'URL du point de terminaison de serveur Exchange. 

Le paramètre d'information d'identification spécifie les informations d'identification Windows Live stockées dans la variable $LiveCred. 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.

C:\PS>$max = New-PSSessionOption -MaximumRedirection 1

C:\PS> Invoke-Command -ConnectionUri https://ps.exchangelabs.com/powershell `
         -scriptblock {Invoke-Command {Get-Mailbox dan} `
         -AllowRedirection -SessionOption $max

Description
-----------
Cette commande indique comment utiliser les paramètres AllowRedirection et SessionOption pour gérer la redirection URI dans une commande distante.

La première commande utilise l'applet de commande New-PSSessionOption pour créer un objet PSSessionOpption qu'elle enregistre dans la variable $max. Elle fait appel au paramètre MaximumRedirection pour définir la propriété MaximumConnectionRedirectionCount de l'objet PSSessionOption sur 1. 

La deuxième commande utilise l'applet de commande Invoke-Command pour mettre en œuvre une commande Get-Mailbox sur un serveur distant exécutant Microsoft Exchange Server. Elle utilise le paramètre AllowRedirection pour donner l'autorisation explicite de rediriger la connexion vers un autre point de terminaison. Elle fait également appel au paramètre SessionOption pour spécifier l'objet session dans la variable $max.

En conséquence, si l'ordinateur distant spécifié par le paramètre ConnectionURI retourne un message de redirection, Windows PowerShell redirigera la connexion, mais si la nouvelle destination retourne un autre message de redirection, la valeur du nombre de redirection 1 est dépassée, et Invoke-Command retourne une erreur sans fin d'exécution.

C:\PS>$so = New-PSSessionOption -SkipCACheck

PS C:\> invoke-command $s { get-hotfix } -SessionOption $so -credential server01\user01

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

La première commande utilise l'applet de commande New-PSSessionOption pour créer une option de session. Elle enregistre l'objet SessionOption résultant dans le paramètre $so.

La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter une commande Get-Hotfix à distance. La valeur du paramètre SessionOption est l'objet SessionOption dans la variable $so.

C:\PS>enable-wsmanCredSSP -delegate server02

C:\PS> connect-wsman Server02

C:\PS> set-item wsman:\server02*\service\auth\credSSP -value $true

C:\PS> $s = new-pssession server02

C:\PS> invoke-command -session $s -script {get-item \\Net03\Scripts\LogFiles.ps1} -authentication credssp -credential domain01\admin01

Description
-----------
Cet exemple indique comment accéder à un partage réseau à partir d'une session à distance. 

La commande requiert que la délégation CredSSP soit activée dans les paramètres du client de l'ordinateur local et dans les paramètres de service de 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.

La première commande utilise l'applet de commande Enable-WSManCredSSP pour activer la délégation CredSSP à partir de l'ordinateur local Server01 sur l'ordinateur distant Server02. Le paramètre du client CredSSP est ainsi configuré sur l'ordinateur local.

La deuxième commande utilise l'applet de commande Connect-WSman pour se connecter à l'ordinateur Server02. Cette action ajoute un nœud pour l'ordinateur Server02 au lecteur WSMan: de l'ordinateur local, vous permettant d'afficher et de modifier les paramètres du service Gestion des services Web sur l'ordinateur Server02.

La troisième commande utilise l'applet de commande Set-Item pour redéfinir la valeur de l'élément CredSSP dans le nœud Service de l'ordinateur Server02 sur True. Cette action active CredSSP dans les paramètres de service de l'ordinateur distant.

La quatrième commande utilise l'applet de commande New-PSSession pour créer une session PSSession sur l'ordinateur Server02. Elle enregistre la session PSSession dans la variable $s.

La cinquième commande utilise l'applet de commande Invoke-Command pour exécuter une commande Get-Item de la session dans $s qui obtient un script du partage réseau Net03\Scripts. La commande utilise le paramètre Credential, ainsi que le paramètre Authentication avec la valeur CredSSP.