about_Remote_Variables

Artigo
11/06/2024

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. 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 $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 de Using é a seguinte:

$Using:<VariableName>

No exemplo a seguir, a $ps variável é criada na sessão local, mas é usada na sessão em que o comando é executado. O Using modificador de escopo é identificado $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 um PSSession.

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

Uma referência de variável, como $using:var expande para o valor de variable $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 Usingo , consulte about_Scopes

Usando splatting

O 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 splatting é uma tabela de hash configurada no computador local. O se Invoke-Command conecta 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 espalhada.

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

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

Para qualquer script ou comando que seja executado fora da sessão, você precisa do Using modificador de escopo para incorporar valores de 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 ou ForEach-Object -Parallel (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, são sempre cópias independentes. Em sessões de thread, eles são passados por referência.

Serialização de valores de 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 entre os limites do processo. O processo de serialização converte objetos em um PSObject que contém as propriedades dos objetos originais, mas não seus métodos.

Para um conjunto limitado de tipos, a desserialização reidrata os objetos de volta ao tipo original. O objeto reidratado é uma cópia da instância do objeto original. Ele tem as 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.

Instâncias de todos os outros tipos são instâncias PSObject . A propriedade PSTypeNames contém o nome do tipo original prefixado com Deserialized, 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 dos parâmetros 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 a usam em um comando remoto. O comando usa $log como 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

Compartilhar via