about_Remote_Variables

Artigo
03/19/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, em seguida, use a variável no lugar do valor.

Por padrão, presume-se que as variáveis em comandos remotos sejam 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 são definidas na sessão em que 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 na qual o comando é executado. O Using modificador de escopo 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 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 se expande para o valor de 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 seguinte código 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âmetros 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 Invoke-Command se 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 splatted.

$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 executado fora da sessão, você precisa que o Using modificador de escopo incorpore 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 é suportado 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 via Start-ThreadJob ou ForEach-Object -Parallel (sessão de thread separada)

Dependendo do contexto, os valores de variáveis incorporadas são cópias independentes dos dados no escopo do chamador ou referências a ele. Em sessões remotas e fora de 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 além dos 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 de tipo e métodos. 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 de 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 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

Compartilhar via