Partilhar via

about_Ref

  • Artigo

Breve descrição

Descreve como criar e usar uma variável de tipo de referência.

Descrição longa

Você pode passar variáveis para funções por referência ou por valor. Quando você passa uma variável por valor, você está passando uma cópia dos dados. Quando você passa uma variável por referência, você está passando uma referência para o valor original. Isso permite que a função altere o valor da variável que é passada para ela. Os tipos de referência são criados usando [ref], que é o acelerador de tipo para o tipo [System.Management.Automation.PSReference].

O objetivo principal do [ref] é habilitar a passagem de variáveis do PowerShell por referência aos parâmetros do método .NET marcados como ref, outou in. Você também pode definir a sua própria função do PowerShell que aceite parâmetros de tipo [ref]. Nesse uso, [ref] é aplicado a uma variável , e a instância [ref] resultante pode ser usada para modificar indiretamente o valor dessa variável.

No exemplo a seguir, a função altera o valor da variável passada para ela. No PowerShell, os números inteiros são tipos de valor, por isso são passados por valor. Portanto, o valor de $var é inalterado fora do escopo da função.

Function Test($data)
{
    $data = 3
}

$var = 10
Test -data $var
$var

10

No exemplo a seguir, uma variável que contém um Hashtable é passada para uma função. Hashtable é um tipo de objeto, portanto, por padrão, ele é passado para a função por referência.

Ao passar uma variável por referência, a função pode alterar os dados e essa alteração persiste depois que a função é executada.

Function Test($data)
{
    $data.Test = "New Text"
}

$var = @{}
Test -data $var
$var

Name                           Value
----                           -----
Test                           New Text

A função adiciona um novo par chave-valor que persiste fora do escopo da função.

Funções de escrita para aceitar parâmetros de referência

Você pode codificar suas funções para tomar um parâmetro como referência, independentemente do tipo de dados passados. Isso requer que você especifique o tipo de parâmetros como [ref].

Ao usar referências, você deve usar a Value propriedade do [ref] tipo para acessar seus dados.

function Test {
    param([ref]$data)
    $data.Value = 3
}

Para passar uma variável para um parâmetro que espera uma referência, você deve digitar cast sua variável como uma referência.

Importante

Os parênteses e parênteses são AMBOS obrigatórios.

$var = 10
Test -data ([ref]$var)
$var

3

Passando referências para métodos .NET

Alguns métodos .NET podem exigir que você passe uma variável como referência. Quando a definição do método usa as palavras-chave in, outou ref em um parâmetro, ele espera uma referência.

[int] | Get-Member -Static -Name TryParse

Name     MemberType Definition
----     ---------- ----------
TryParse Method     static bool TryParse(string s, [ref] int result)

O TryParse método tenta analisar uma cadeia de caracteres como um inteiro. Se o método for bem-sucedido, ele retornará $truee o resultado será armazenado na variável que você passou por referência.

PS> $number = 0
PS> [int]::TryParse("15", ([ref]$number))
True
PS> $number
15

Referências e âmbitos

As referências permitem que o valor de uma variável no escopo pai seja alterado dentro de um escopo filho.

# Create a value type variable.
$i = 0
# Create a reference type variable.
$iRef = [ref]0
# Invoke a scriptblock to attempt to change both values.
&{$i++;$iRef.Value++}
# Output the results.
"`$i = $i;`$iRef = $($iRef.Value)"

$i = 0;$iRef = 1

Apenas a variável do tipo de referência foi alterada.

Usando [ref] como um detentor de objeto de uso geral

Você também pode usar [ref] como um suporte para objetos de uso geral. Nesse uso, [ref] é aplicado a um valor em vez de uma variável. Normalmente, o valor é uma instância de um tipo de valor , como um número. Na maioria dos cenários, você pode usar uma variável ou parâmetro regular. No entanto, essa técnica é útil em cenários em que passar um portador de valor explícito é indesejado por questões de simplicidade ou quando não é possível, como em valores de parâmetros em blocos de script.

Por exemplo, pode utilizar os valores dos parâmetros do bloco de script para calcular o valor do parâmetro NewName do cmdlet Rename-Item. O cmdlet Rename-Item permite canalizar itens para ele. O comando executa o bloco de script que é passado para o NewName para cada item no pipeline. O bloco de script é executado num escopo filho. Modificar uma variável no escopo do chamador diretamente não ajudará e você não pode passar argumentos para o bloco de script neste contexto.

Neste exemplo, o bloco de script passado para o parâmetro NewName incrementa o valor de $iRef para cada item no pipeline. O bloco de script cria um novo nome adicionando um número ao início do nome do arquivo.

$iRef = [ref] 0
Get-ChildItem -File $setPath |
    Rename-Item -NewName { '{0} - {1}' -f $iRef.Value++,$_.Name }

Diferença entre [ref] e [System.Management.Automation.PSReference]

Uma variável de tipo de referência é criada usando o acelerador de tipo [ref] ou especificando o tipo [System.Management.Automation.PSReference] diretamente. Embora [ref] seja um acelerador de tipo para [System.Management.Automation.PSReference], eles se comportam de forma diferente.

  • Quando você usa [ref] para converter uma variável, o PowerShell cria um objeto de referência que contém uma referência à instância original da variável.
  • Quando você usa [System.Management.Automation.PSReference] para converter uma variável, o PowerShell cria um objeto de referência que contém uma cópia da variável, em vez de uma referência à instância original.

Por exemplo, o script a seguir cria uma variável $x e dois objetos de referência.

PS> $int = 1
PS> $aRef = [ref] $int
PS> $bRef = [System.Management.Automation.PSReference] $int
PS> $int
1
PS> $aRef, $bRef

Value
-----
    1
    1

Neste ponto, ambos os objetos de referência têm o mesmo valor que $int. Ao adicionar valores diferentes aos objetos de referência, podemos ver que $aRef, que foi criado usando [ref], é uma referência à instância original de $int. $bRef, que foi criado usando [System.Management.Automation.PSReference], é uma cópia da variável.

PS> $aRef.Value+=2
PS> $bRef.Value+=5
PS> $int
3
PS> $aRef, $bRef

Value
-----
    3
    6

Consulte também