Invoke-Command

Module:

Microsoft.PowerShell.Core

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

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.

Remarque

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

Autorise la redirection de cette connexion vers un autre URI (Uniform Resource Identifier).

Lorsque vous utilisez le paramètre ConnectionURI , la destination distante peut retourner une instruction pour rediriger vers un 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
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 de ce paramètre doit correspondre à la valeur de la propriété URLPrefix d’un écouteur sur l’ordinateur distant.

Type:	String
Position:	Named
Valeur par défaut:	$PSSessionApplicationName if set on the local computer, otherwise WSMAN
Obligatoire:	False
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-ArgumentList

Fournit les valeurs des paramètres pour le scriptblock. Les paramètres du bloc de script sont transmis par position à partir de la valeur de tableau fournie à ArgumentList. Il s’agit d’une plaque de tableau. Pour plus d’informations sur le comportement d’ArgumentList, consultez about_Splatting.

Type:	Object[]
Alias:	Args
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 pour terminer.

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 du travail, utilisez l’applet Receive-Job de commande.

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
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 :

• Par défaut
• 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), dans laquelle les informations d’identification de l’utilisateur sont transmises à un ordinateur distant à authentifier, 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
Valeurs acceptées:	Basic, Default, Credssp, Digest, Kerberos, Negotiate, NegotiateWithImplicitCredential
Position:	Named
Valeur par défaut:	Default
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 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 , consultez Comment ajouter un ordinateur à la liste d’hôtes approuvée.

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[]
Alias:	Cn
Position:	0
Valeur par défaut:	Local computer
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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édéfini : http://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
Valeur par défaut:	$PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell
Obligatoire:	False
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-ConnectingTimeout

Spécifie la durée en millisecondes autorisée pour la fin de la connexion SSH initiale. Si la connexion ne se termine pas dans le délai spécifié, une erreur est retournée.

Ce paramètre a été introduit dans PowerShell 7.2

Type:	Int32
Position:	Named
Valeur par défaut:	Unlimited
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 :

http://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 pour le segment Transport de l’URI sont HTTP et HTTPS. Si vous spécifiez un URI de connexion avec un segment de transport, mais que vous 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[]
Alias:	URI, CU
Position:	0
Valeur par défaut:	http://localhost:5985/WSMAN
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-ContainerId

Spécifie un tableau d’ID de conteneur.

Type:	String[]
Position:	Named
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	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.

Remarque

Pour plus d’informations sur la protection des données SecureString , consultez Comment secure is SecureString ?.

Type:	PSCredential
Position:	Named
Valeur par défaut:	Current user
Obligatoire:	False
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-EnableNetworkAccess

Indique que cette applet de commande ajoute un jeton de sécurité interactif aux sessions de bouclage. Le jeton interactif vous permet d'exécuter des commandes dans la session de bouclage qui obtiennent des données à partir d'autres ordinateurs. Par exemple, vous pouvez exécuter une commande dans la session qui copie les fichiers XML d'un ordinateur distant vers l'ordinateur local.

Une session de bouclage est une session PSSession qui provient et se termine sur le même ordinateur. Pour créer une session de bouclage, omettez le paramètre ComputerName ou définissez sa valeur sur point (.), localhost ou le nom de l’ordinateur local.

Par défaut, 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 est efficace uniquement 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 d’authentification , qui délègue les informations d’identification de session à d’autres ordinateurs.

Pour protéger l’ordinateur contre les accès malveillants, les sessions de bouclage déconnectées qui ont des jetons interactifs, 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
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-FilePath

Spécifie un script local exécuté par cette applet de commande 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
Alias:	PSPath
Position:	1
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-HideComputerName

Indique que cette applet de commande omet le nom de l’ordinateur de chaque objet 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 modifie pas l’objet.

Type:	SwitchParameter
Alias:	HCN
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-HostName

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

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

Type:	String[]
Position:	Named
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 la commande. Pour vous connecter à la session déconnectée, utilisez les Connect-PSSession applets de commande ou Receive-PSSession les 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 une 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
Alias:	Disconnected
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	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
Valeur par défaut:	Job<n>
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-KeyFilePath

Spécifie un chemin d’accès de fichier de 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
Alias:	IdentityFilePath
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 exécutées dans la session active, autrement dit, les commandes qui omettent les paramètres ComputerName et Session .

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

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-Options

Spécifie une table de hachage des options SSH utilisées lors de la connexion à une session SSH distante. Les options possibles sont toutes les valeurs prises en charge par la version unix de la commande ssh .

Toutes les valeurs transmises explicitement par les paramètres sont prioritaires sur les valeurs passées dans la table de hachage Options . Par exemple, l’utilisation du paramètre Port remplace toute Port paire clé-valeur passée dans la table de hachage Options .

Ce paramètre a été ajouté dans PowerShell 7.3.

Type:	Hashtable
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-RemoteDebug

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

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-RunAsAdministrator

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

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-ScriptBlock

Spécifie les commandes à exécuter. Placez les commandes dans les accolades ({ }) pour créer un bloc de script. Lorsque vous utilisez Invoke-Command pour exécuter une commande à distance, toutes les variables de la commande sont évaluées sur l’ordinateur distant.

Remarque

Les paramètres du scriptblock ne peuvent être transmis qu’à partir d’ArgumentList par position. Impossible de passer les paramètres de commutateur par position. Si vous avez besoin d’un paramètre qui se comporte comme un type SwitchParameter , utilisez plutôt un type booléen .

Type:	ScriptBlock
Alias:	Command
Position:	0
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 ou Get-PSSession une New-PSSession 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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-SessionOption

Spécifie les options avancées de la session. Entrez un objet SessionOption , tel qu’un objet 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’options de session et les valeurs sont des valeurs d’option de session.

Remarque

Si vous spécifiez une table de hachage pour SessionOption, PowerShell convertit la table de hachage en objet System.Management.Automation.Remoting.PSSessionOption . Les valeurs des clés spécifiées dans la table de hachage sont converties en propriété correspondante de l’objet. Cela se comporte différemment de l’appel New-PSSessionOption. Par exemple, les valeurs System.TimeSpan pour les propriétés de délai d’expiration, telles que IdleTimeout, convertissent une valeur entière en graduations au lieu de millisecondes. Pour plus d’informations sur l’objet PSSessionOption et ses propriétés, consultez PSSessionOption

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 session. Toutefois, elles 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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 SSH (Secure Shell). Le paramètre SSHConnection est utile pour créer plusieurs sessions où chaque session nécessite des informations de connexion différentes.

La table 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
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-SSHTransport

Indique que la connexion à distance 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
Valeurs acceptées:	true
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 tel que 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 powershell sous-système.

Type:	String
Position:	Named
Valeur par défaut:	powershell
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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
Valeur par défaut:	32
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 de l’utilisateur.

Si SSH est configuré pour l’authentification utilisateur basée sur des clés, un chemin d’accès de fichier de 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 à 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
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	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 sur 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
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-VMId

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

Type:	Guid[]
Alias:	VMGuid
Position:	0
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-VMName

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

Type:	String[]
Position:	Named
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	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

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