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 aceita parâmetros do 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, inteiros são tipos de valor, portanto, 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 suporte de objetos de uso geral

Você também pode usar [ref] como um suporte de objetos para fins gerais. 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, esta técnica é útil em cenários em que passar um portador de valor explícito é indesejável por questões de brevidade ou não é possível, como em valores de parâmetro de bloco de script.

Por exemplo, você pode usar valores de parâmetro de bloco de script para calcular o valor de NewName parâmetro do cmdlet Rename-Item. O cmdlet Rename-Item permite canalizar itens para ele. O comando executa o bloco de script passado para o NewName em 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 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

Consulte também