Sobre variáveis remotas

Artigo
06/21/2023

Descrição breve

Explica como usar variáveis locais e remotas em comandos remotos.

Descrição longa

Você pode usar variáveis em comandos executados em computadores remotos. Atribua um valor à variável e use a variável no lugar do valor.

Por padrão, as variáveis em comandos remotos são consideradas definidas na sessão que executa o comando. Variáveis definidas em uma sessão local devem ser identificadas como variáveis locais no comando.

Usando variáveis remotas

O PowerShell pressupõe que as variáveis usadas em comandos remotos sejam definidas na sessão na qual o comando é executado.

Neste exemplo, a $ps variável é definida na sessão temporária na qual o Get-WinEvent comando é executado.

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

Quando o comando é executado em uma sessão persistente, PSSession, a variável remota deve ser definida nessa sessão.

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

Usando variáveis locais

Você pode usar variáveis locais em comandos remotos, mas a variável deve ser definida na sessão local.

A partir do PowerShell 3.0, você pode usar o Using modificador de escopo para identificar uma variável local em um comando remoto.

A sintaxe é a Using seguinte:

$Using:<VariableName>

No exemplo a seguir, a $ps variável é criada na sessão local, mas é usada na sessão na qual o comando é executado. O Using modificador de escopo se identifica $ps como uma variável local.

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

O Using modificador de escopo pode ser usado em uma PSSession.

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

Uma referência variável, como, por $using:var exemplo, expande para o valor da variável $var do contexto do chamador. Você não obtém acesso ao objeto variável do chamador. O Using modificador de escopo não pode ser usado para modificar uma variável local dentro do PSSession. Por exemplo, o código a seguir não funciona:

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

Para obter mais informações sobre Using, consulte about_Scopes

Usando splatting

A splatting do PowerShell passa uma coleção de nomes e valores de parâmetro para um comando. Para obter mais informações, consulte about_Splatting.

Neste exemplo, a variável $Splat de splatting é uma tabela de hash configurada no computador local. Conecta-se Invoke-Command a uma sessão de computador remoto. O ScriptBlock usa o Using modificador de escopo com o símbolo At (@) para representar a variável splatted.

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

Outras situações em que o modificador de escopo 'Using' é necessário

Para qualquer script ou comando executado fora da sessão, você precisa do Using modificador de escopo para inserir valores variáveis do escopo da sessão de chamada, para que o código fora da sessão possa acessá-los. O Using modificador de escopo tem suporte nos seguintes contextos:

Comandos executados remotamente, iniciados com Invoke-Command o uso dos parâmetros ComputerName, HostName, SSHConnection ou Session (sessão remota)
Trabalhos em segundo plano, iniciados com Start-Job (sessão fora do processo)
Trabalhos de thread iniciados por meio Start-ThreadJob de (sessão de thread separada)

Dependendo do contexto, os valores de variáveis inseridas são cópias independentes dos dados no escopo do chamador ou referências a ele. Em sessões remotas e fora do processo, elas são sempre cópias independentes. Em sessões de thread, elas são passadas por referência.

Serialização de valores variáveis

Comandos executados remotamente e trabalhos em segundo plano são executados fora do processo. As sessões fora do processo usam serialização e desserialização baseadas em XML para disponibilizar os valores das variáveis nos limites do processo. O processo de serialização converte objetos em um PSObject que contém as propriedades de objetos originais, mas não seus métodos.

Para um conjunto limitado de tipos, a desserialização reidrata objetos de volta ao tipo original. O objeto reidratado é uma cópia da instância de objeto original. Ele tem as propriedades e os métodos de tipo. Para tipos simples, como System.Version, a cópia é exata. Para tipos complexos, a cópia é imperfeita. Por exemplo, objetos de certificado reidratados não incluem a chave privada.

Instâncias de todos os outros tipos são instâncias PSObject . A propriedade PSTypeNames contém o nome de tipo original prefixado com Desserializado, por exemplo, Deserialized.System.Data.DataTable

Usando variáveis locais com o parâmetro ArgumentList

Você pode usar variáveis locais em um comando remoto definindo parâmetros para o comando remoto e usando o parâmetro ArgumentList do Invoke-Command cmdlet para especificar a variável local como o valor do parâmetro.

Use a param palavra-chave para definir parâmetros para o comando remoto. Os nomes de parâmetro são espaços reservados que não precisam corresponder ao nome da variável local.
Use os parâmetros definidos pela param palavra-chave no comando.
Use o parâmetro ArgumentList do Invoke-Command cmdlet para especificar a variável local como o valor do parâmetro.

Por exemplo, os comandos a seguir definem a $ps variável na sessão local e, em seguida, a usam em um comando remoto. O comando usa $log como o nome do parâmetro e a variável local, $pscomo seu valor.

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

Confira também