Partager via

about_Remote_Variables

Brève description

Explique comment utiliser des variables locales et distantes dans des commandes distantes.

Description longue

Vous pouvez utiliser des variables dans les commandes que vous exécutez sur des ordinateurs distants. Affectez une valeur à la variable, puis utilisez la variable à la place de la valeur.

Par défaut, les variables des commandes distantes sont supposées être définies dans la session qui exécute la commande. Les variables définies dans une session locale doivent être identifiées comme variables locales dans la commande.

Utilisation de variables distantes

PowerShell suppose que les variables utilisées dans les commandes distantes sont définies dans la session dans laquelle la commande s’exécute.

Dans cet exemple, la variable $ps est définie dans la session temporaire dans laquelle la commande Get-WinEvent s’exécute.

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.

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

Utilisation de variables locales

Vous pouvez utiliser des variables locales dans des commandes distantes, mais la variable doit être définie dans la session locale.

À compter de PowerShell 3.0, vous pouvez utiliser le modificateur d’étendue Using: pour identifier une variable locale dans une commande distante.

La syntaxe de Using: est la suivante :

$Using:<VariableName>

Dans l’exemple suivant, la variable $ps est créée dans la session locale, mais elle est utilisée dans la session dans laquelle la commande s’exécute. Le modificateur d’étendue Using: identifie $ps en tant que variable locale.

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

Le modificateur d'étendue Using: peut être utilisé dans une 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. Vous n’avez pas accès à l’objet variable de l’appelant. Impossible d’utiliser le modificateur d’étendue Using: pour modifier une variable locale dans le PSSession. Par exemple, le code suivant ne fonctionne pas :

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

Pour plus d'informations sur Using:, voir about_Scopes

Utilisation du splatting

Le splatting PowerShell transmet un ensemble de noms et de valeurs de paramètres à une commande. Pour plus d'informations, consultez À propos de la projection.

Dans cet exemple, la variable splatting $Splat est une table de hachage configurée sur l'ordinateur local. Le Invoke-Command se connecte à une session d’ordinateur distant. Le ScriptBlock utilise le modificateur de portée Using: avec le symbole At (@) pour représenter la variable éclatée.

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

Autres situations où le modificateur d’étendue Using: est nécessaire

Pour tout script ou commande qui s’exécute hors session, vous avez besoin du modificateur d’étendue Using: pour incorporer des valeurs de variable à partir de l’étendue de session appelante, afin que le code hors session puisse y accéder. Le modificateur d’étendue Using: est pris en charge dans les contextes suivants :

  • Commandes exécutées à distance, démarrées avec Invoke-Command à l’aide des paramètres ComputerName, HostName, SSHConnection ou Session (session distante)
  • Travaux en arrière-plan, démarrés avec Start-Job (session hors processus)
  • Travaux de thread, démarrés via Start-ThreadJob ou ForEach-Object -Parallel (session de thread distincte)

Selon le contexte, les valeurs de variables incorporées sont soit des copies indépendantes des données dans l’étendue de l’appelant, soit des références à celles-ci. Dans les sessions distantes et hors processus, il s'agit toujours de copies indépendantes. Dans les sessions threading, ils sont transmis par référence.

Sérialisation des valeurs de variables

Les commandes exécutées à distance et les travaux en arrière-plan s’exécutent hors processus. 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. Le processus de sérialisation convertit les objets en un PSObject qui contient les propriétés d’objets d’origine, mais pas ses méthodes.

Pour un ensemble limité de types, la désérialisation réhydrate les objets pour les ramener à leur type d'origine. L’objet réhydraté est une copie de l’instance d’objet d’origine. Elle possède les propriétés et les méthodes du type. Pour les types simples, tels que System.Version, la copie est exacte. Pour les types complexes, la copie est imparfaite. Par exemple, les objets de certificat réhydratés n’incluent pas la clé privée.

Les instances de tous les autres types sont des instances de PSObject. La propriété pstypenames contient le nom de type d’origine précédé de désérialisé, par exemple, Deserialized.System.Data.DataTable

Utilisation de variables locales avec le paramètre ArgumentList

Vous pouvez utiliser des variables locales dans une commande distante en définissant des paramètres pour la commande distante et en utilisant le paramètre ArgumentList de l’applet de commande Invoke-Command pour spécifier la variable locale comme valeur de paramètre.

  • Utilisez le mot clé param pour définir des paramètres pour la commande distante. Les noms de paramètres sont des espaces réservés qui n’ont pas besoin de correspondre au nom de la variable locale.

  • Utilisez les paramètres définis par le mot clé param dans la commande.

  • Utilisez le paramètre ArgumentList de l’applet de commande Invoke-Command pour spécifier la variable locale comme valeur de paramètre.

Par exemple, les commandes suivantes définissent la variable $ps dans la session locale, puis l’utilisent dans une commande distante. La commande utilise $Log comme nom de paramètre et la variable locale, $ps, comme valeur.

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

Voir aussi

  • Last updated on