Compartilhar via

about_Ref

Descrição breve

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. Ao passar uma variável por valor, você está passando uma cópia dos dados. Quando você passa uma variável porde 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 tipos para o tipo [System.Management.Automation.PSReference].

A principal finalidade 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 sua própria função do PowerShell que usa 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 inteiros são tipos de valor, sendo assim, são passados por valor. Portanto, o valor de $var não é alterado 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 contendo a 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 após a execução da função.

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.

Escrevendo funções para aceitar parâmetros de referência

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

Ao usar referências, você deve usar a Value[ref] propriedade do 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 your variable como uma referência.

Importante

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

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

3

Passando referências a 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, out, ou 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 escopos

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 suporte de objetos de uso geral

Você também pode usar [ref] como um suporte de objeto 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 nos quais passar um portador de valor explícito é indesejado por brevidade ou não é possível, como no caso de valores de parâmetros de bloco de script.

Por exemplo, você pode usar valores de parâmetros de blocos de scripts para calcular o valor do parâmetro NewName do cmdlet Rename-Item. O cmdlet Rename-Item permite que você redirecione itens para ele. O comando executa o bloco de script passado para o NewName para cada item no pipeline. O bloco de script é executado em um 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 nesse 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 de [System.Management.Automation.PSReference] diretamente. Embora [ref] seja um acelerador de tipo para [System.Management.Automation.PSReference], ele se comporta de maneira 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

Confira também