about_Remote_Variables

Article
10/04/2023

Description courte

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 $ps variable est définie dans la session temporaire dans laquelle la Get-WinEvent commande 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 est Using la suivante :

$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. Le Using modificateur d’étendue identifie $ps comme variable locale.

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

Le Using modificateur d’étendue peut être utilisé dans une session 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. Le Using modificateur d’étendue ne peut pas être utilisé pour modifier une variable locale dans la session 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, consultez about_Scopes

Utilisation de l’platissement

La mise en forme PowerShell transmet une collection de noms de paramètres et de valeurs à une commande. Pour plus d’informations, consultez about_Splatting.

Dans cet exemple, la variable $Splat de platissement est une table de hachage configurée sur l’ordinateur local. Se Invoke-Command connecte à une session d’ordinateur distant. Le ScriptBlock utilise le Using modificateur d’étendue avec le symbole At (@) pour représenter la variable plateté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 Using modificateur d’étendue pour incorporer des valeurs de variable à partir de l’étendue de session appelante, afin que le code hors session puisse y accéder. Le Using modificateur d’étendue est pris en charge dans les contextes suivants :

Commandes exécutées à distance, démarrées à 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, elles sont toujours des copies indépendantes. Dans les sessions de thread, elles sont passées 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 objet 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 vers le type d’origine. L’objet réhydraté est une copie de l’instance d’objet d’origine. Il a les propriétés et méthodes de type. Pour les types simples, tels que System.Version, la copie est exacte. Pour les types complexes, la copie est parfaite. 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 PSObject . La propriété PSTypeNames contient le nom de type d’origine préfixé par Désérialized, 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 Invoke-Command de commande pour spécifier la variable locale comme valeur de paramètre.

Utilisez le param mot clé 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 param mot clé dans la commande.
Utilisez le paramètre ArgumentList de l’applet Invoke-Command de commande pour spécifier la variable locale comme valeur de paramètre.

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

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

Partager via