Compartilhar via

about_Remote_Variables

Descrição curta

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. As 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 variável $ps é definida na sessão temporária na qual o comando Get-WinEvent é 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 modificador de escopo Using: para identificar uma variável local em um comando remoto.

A sintaxe de Using: é a seguinte:

$Using:<VariableName>

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

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

O modificador de escopo Using: pode ser utilizado 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 $Using:var, é expandida para o valor da variável $var do contexto do chamador. Você não obtém acesso ao objeto variável do chamador. O modificador de escopo Using: não pode ser usado para modificar uma variável local no 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.

Como usar o splatting

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

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

$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 modificador de escopo Using: 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 modificador de escopo Using: tem suporte nos seguintes contextos:

  • Comandos executados remotamente, iniciados com Invoke-Command usando os 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 Start-ThreadJob ou ForEach-Object -Parallel (sessão de thread separada)

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

Serialização de valores variáveis

Comandos executados remotamente e trabalhos em segundo plano são executados fora do processo. Sessões fora de processo usam serialização e desserialização baseadas em XML para disponibilizar os valores das variáveis entre os 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 para o tipo original. O objeto reidratado é uma cópia da instância de objeto original. Possui propriedades e 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.

As instâncias de todos os outros tipos são instâncias de PSObject. A propriedade pstypenames contém o nome de tipo original prefixado com Desserializados, 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 cmdlet Invoke-Command para especificar a variável local como o valor do parâmetro.

  • Use a palavra-chave param 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 palavra-chave param no comando.

  • Use o parâmetro ArgumentList do cmdlet Invoke-Command para especificar a variável local como o valor do parâmetro.

Por exemplo, os comandos a seguir definem a variável $ps 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, $ps, como seu valor.

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

Consulte também

  • Last updated on