À propos des variables distantesAbout Remote Variables

Description courteShort description

Explique comment utiliser des variables locales et distantes dans des commandes distantes.Explains how to use local and remote variables in remote commands.

Description longueLong description

Vous pouvez utiliser des variables dans les commandes que vous exécutez sur des ordinateurs distants.You can use variables in commands that you run on remote computers. Assignez une valeur à la variable, puis utilisez la variable à la place de la valeur.Assign a value to the variable and then use the variable in place of the value.

Par défaut, les variables des commandes distantes sont supposées être définies dans la session qui exécute la commande.By default, the variables in remote commands are assumed to be defined in the session that runs the command. Les variables définies dans une session locale doivent être identifiées en tant que variables locales dans la commande.Variables that are defined in a local session, must be identified as local variables in the command.

Utilisation de variables distantesUsing remote variables

PowerShell suppose que les variables utilisées dans les commandes distantes sont définies dans la session dans laquelle la commande s’exécute.PowerShell assumes that the variables used in remote commands are defined in the session in which the command runs.

Dans cet exemple, la $ps variable est définie dans la session temporaire dans laquelle la Get-WinEvent commande s’exécute.In this example, the $ps variable is defined in the temporary session in which the Get-WinEvent command runs.

Invoke-Command -ComputerName S1 -ScriptBlock {
  $ps = "*PowerShell*"; Get-WinEvent -LogName $ps
}

Lorsque la commande s’exécute dans une session persistante, PSSession , la variable distante doit être définie dans cette session.When the command runs in a persistent session, PSSession , the remote variable must be defined in that session.

$s = New-PSSession -ComputerName S1
Invoke-Command -Session $s -ScriptBlock {$ps = "*PowerShell*"}
Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $ps}

Utilisation de variables localesUsing local variables

Vous pouvez utiliser des variables locales dans des commandes distantes, mais la variable doit être définie dans la session locale.You can use local variables in remote commands, but the variable must be defined in the local session.

À compter de PowerShell 3,0, vous pouvez utiliser le Using modificateur de portée pour identifier une variable locale dans une commande à distance.Beginning in PowerShell 3.0, you can use the Using scope modifier to identify a local variable in a remote command.

La syntaxe de Using est la suivante :The syntax of Using is as follows:

$Using:<VariableName>

Dans l’exemple suivant, la $ps variable est créée dans la session locale, mais elle est utilisée dans la session dans laquelle la commande s’exécute.In the following example, the $ps variable is created in the local session, but is used in the session in which the command runs. Le Using modificateur de portée identifie $ps en tant que variable locale.The Using scope modifier identifies $ps as a local variable.

$ps = "*PowerShell*"
Invoke-Command -ComputerName S1 -ScriptBlock {
  Get-WinEvent -LogName $Using:ps
}

Le Using modificateur de portée peut être utilisé dans une session PSSession .The Using scope modifier can be used in a PSSession .

$s = New-PSSession -ComputerName S1
$ps = "*PowerShell*"
Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $Using:ps}

Une référence de variable telle que $using:var s’étend à la valeur de la variable $var à partir du contexte de l’appelant.A variable reference such as $using:var expands to the value of variable $var from the caller's context. Vous n’accédez pas à l’objet variable de l’appelant.You do not get access to the caller's variable object. Le Using modificateur de portée ne peut pas être utilisé pour modifier une variable locale au sein de la session PSSession .The Using scope modifier cannot be used to modify a local variable within the PSSession . Par exemple, le code suivant ne fonctionne pas :For example, the following code does not work:

$s = New-PSSession -ComputerName S1
$ps = "*PowerShell*"
Invoke-Command -Session $s -ScriptBlock {$Using:ps = 'Cannot assign new value'}

Pour plus d’informations sur Using , consultez about_ScopesFor more information about Using, see about_Scopes

Utilisation de la projectionUsing splatting

La projection PowerShell passe une collection de noms et de valeurs de paramètres à une commande.PowerShell splatting passes a collection of parameter names and values to a command. Pour plus d’informations, consultez about_Splatting.For more information, see about_Splatting.

Dans cet exemple, la variable de projection $Splat est une table de hachage configurée sur l’ordinateur local.In this example, the splatting variable, $Splat is a hash table that is set up on the local computer. Le Invoke-Command se connecte à une session de l’ordinateur distant.The Invoke-Command connects to a remote computer session. Le scriptblock utilise le Using modificateur de portée avec le symbole at ( @ ) pour représenter la variable dans le volet.The ScriptBlock uses the Using scope modifier with the At (@) symbol to represent the splatted variable.

$Splat = @{ Name = "Win*"; Include = "WinRM" }
Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat }

Autres situations où le modificateur de portée’Using’est nécessaireOther situations where the 'Using' scope modifier is needed

Pour tout script ou commande qui s’exécute hors session, vous avez besoin du Using modificateur de portée pour incorporer les valeurs de variable de l’étendue de la session appelante, afin que le code hors session puisse y accéder.For any script or command that executes out of session, you need the Using scope modifier to embed variable values from the calling session scope, so that out of session code can access them. Le Using modificateur de portée est pris en charge dans les contextes suivants :The Using scope modifier is supported in the following contexts:

  • Exécuter des commandes à distance, démarré avec Invoke-Command à l’aide des paramètres ComputerName , hostname , SSHConnection ou session (session à distance)Remotely executed commands, started with Invoke-Command using the ComputerName , HostName , SSHConnection or Session parameters (remote session)
  • Travaux en arrière-plan, démarrés avec Start-Job (session hors processus)Background jobs, started with Start-Job (out-of-process session)
  • Travaux de thread, démarrés via Start-ThreadJob ou ForEach-Object -Parallel (session de threads distincte)Thread jobs, started via Start-ThreadJob or ForEach-Object -Parallel (separate thread session)

Selon le contexte, les valeurs des variables incorporées sont soit des copies indépendantes des données dans la portée de l’appelant, soit des références à celles-ci.Depending on the context, embedded variable values are either independent copies of the data in the caller's scope or references to it. Dans les sessions à distance et hors processus, il s’agit toujours de copies indépendantes.In remote and out-of-process sessions, they are always independent copies. Dans les sessions de thread, elles sont passées par référence.In thread sessions, they are passed by reference.

Sérialisation de valeurs de variablesSerialization of variable values

Les commandes exécutées à distance et les travaux en arrière-plan s’exécutent hors processus.Remotely executed commands and background jobs run out-of-process. Les sessions hors processus utilisent la sérialisation et la désérialisation basées sur XML pour rendre les valeurs des variables disponibles dans les limites du processus.Out-of-process sessions use XML-based serialization and deserialization to make the values of variables available across the process boundaries. Le processus de sérialisation convertit des objets en PSObject qui contient les propriétés des objets d’origine, mais pas ses méthodes.The serialization process converts objects to a PSObject that contains the original objects properties but not its methods.

Pour un ensemble limité de types, la désérialisation réalimente les objets dans le type d’origine.For a limited set of types, deserialization rehydrates objects back to the original type. L’objet réalimenté est une copie de l’instance d’objet d’origine.The rehydrated object is a copy of the original object instance. Il a les propriétés et les méthodes de type.It has the type properties and methods. Pour les types simples, tels que System. version , la copie est exacte.For simple types, such as System.Version , the copy is exact. Pour les types complexes, la copie n’est pas parfaite.For complex types, the copy is imperfect. Par exemple, les objets de certificat réalimentés n’incluent pas la clé privée.For example, rehydrated certificate objects do not include the private key.

Les instances de tous les autres types sont des instances PSObject .Instances of all other types are PSObject instances. La propriété PSTypeNames contient le nom du type d’origine préfixé avec désérialisé , par exemple, Deserialized.SysTEM. Data. DataTableThe PSTypeNames property contains the original type name prefixed with Deserialized , for example, Deserialized.System.Data.DataTable

Utilisation de variables locales avec le paramètre argumentlistUsing local variables with ArgumentList parameter

Vous pouvez utiliser des variables locales dans une commande à distance en définissant les paramètres de la commande distante et en utilisant le paramètre argumentlist de l' Invoke-Command applet de commande pour spécifier la variable locale comme valeur de paramètre.You can use local variables in a remote command by defining parameters for the remote command and using the ArgumentList parameter of the Invoke-Command cmdlet to specify the local variable as the parameter value.

  • Utilisez le param mot clé pour définir les paramètres de la commande distante.Use the param keyword to define parameters for the remote command. Les noms de paramètres sont des espaces réservés qui n’ont pas besoin de correspondre au nom de la variable locale.The parameter names are placeholders that don't need to match the local variable's name.

  • Utilisez les paramètres définis par le param mot clé dans la commande.Use the parameters defined by the param keyword in the command.

  • Utilisez le paramètre argumentlist de l' Invoke-Command applet de commande pour spécifier la variable locale comme valeur de paramètre.Use the ArgumentList parameter of the Invoke-Command cmdlet to specify the local variable as the parameter value.

Par exemple, les commandes suivantes définissent la $ps variable dans la session locale, puis l’utilisent dans une commande à distance.For example, the following commands define the $ps variable in the local session and then use it in a remote command. La commande utilise $log comme nom de paramètre et la variable locale, $ps , comme valeur.The command uses $log as the parameter name and the local variable, $ps, as its value.

$ps = "*PowerShell*"
Invoke-Command -ComputerName S1 -ScriptBlock {
  param($log)
  Get-WinEvent -LogName $log
} -ArgumentList $ps

Voir aussiSee also

about_PSSessionsabout_PSSessions

about_Remoteabout_Remote

about_Scopesabout_Scopes

about_Splattingabout_Splatting

about_Variablesabout_Variables

Enter-PSSessionEnter-PSSession

Invoke-CommandInvoke-Command

New-PSSessionNew-PSSession

Start-ThreadJobStart-ThreadJob

ForEach-ObjectForEach-Object