Como Retornar Valor no PowerShell

1. Usando a Palavra-chave return no PowerShell
2. Valores de Retorno no Pipeline no PowerShell
3. Definindo Classes no PowerShell 5

Em geral, a palavra-chave return encerra uma função, script ou bloco de script. Assim, por exemplo, podemos usá-la para sair de um escopo em um ponto específico, retornar um valor ou indicar que o fim do escopo foi alcançado.

No entanto, no Windows PowerShell, usar a palavra-chave return pode ser um pouco confuso, pois seu script pode imprimir uma saída que você pode não ter esperado.

Este artigo discutirá como a palavra-chave return funciona e como usá-la corretamente no Windows PowerShell.

Usando a Palavra-chave return no PowerShell

O bloco de script abaixo é a forma básica da sintaxe da palavra-chave return.

return <expression>

A palavra-chave return pode aparecer sozinha, ou um valor ou expressão pode segui-la. A palavra-chave return sozinha retornará a linha de comando ao seu ponto de chamada anterior.

return
return $a
return (1 + $a)

O exemplo abaixo usa a palavra-chave return para sair de uma função se uma condição for atendida em um ponto específico. Neste exemplo, os números ímpares não são multiplicados porque a instrução de retorno vem antes que aquela instrução possa ser executada.

function MultiplyOnlyEven {
    param($num)

    if ($num % 2) { return "$num is not even" }
    $num * 2
    return
}

1..10 | ForEach-Object { MultiplyOnlyEven -Num $_ }

Saída:

1 is not even
4
3 is not even
8
5 is not even
12
7 is not even
16
9 is not even
20

O Windows PowerShell tem semânticas de retorno confusas quando vistas de uma perspectiva mais nativa de programação. Existem duas ideias principais que precisamos considerar:

1. Toda saída é capturada e retornada.
2. A palavra-chave return indica um ponto de saída lógico.

Dito isso, os seguintes blocos de script retornarão o valor da variável $a.

Palavra-chave de retorno com uma expressão:

$a = "Hello World"
return $a

Palavra-chave de retorno sem uma expressão:

$a = "Hello World"
$a
return

A palavra-chave return também não é necessária no segundo bloco de script, pois chamar a variável na linha de comando retornará explicitamente essa variável mencionada.

Valores de Retorno no Pipeline no PowerShell

Quando você retorna um valor do seu bloco de script ou função, o Windows PowerShell automaticamente remove os membros e os empurra um de cada vez através do pipeline. A razão por trás desse caso de uso se deve ao processamento de um por vez do Windows PowerShell.

A função a seguir demonstra que essa ideia retornará um array de números.

function Test-Return {
    $array = 1, 2, 3
    return $array
}
Test-Return | Measure-Object | Select-Object Count

Saída:

Count
-----
    3

Ao usar o cmdlet Test-Return, a saída da função abaixo é encadeada ao cmdlet Measure-Object. O cmdlet contará o número de objetos no pipeline e, ao ser executado, a contagem retornada é três.

Para fazer um bloco de script ou função retornar apenas um único objeto para o pipeline, use um dos seguintes métodos:

Utilizando Expressão de Array Unária no PowerShell

Utilizar uma expressão unária pode enviar seu valor de retorno pelo pipeline como um único objeto, conforme demonstrado pelo seguinte exemplo.

function Test-Return {
    $array = 1, 2, 3
    return (, $array)
}
Test-Return | Measure-Object | Select-Object Count

Saída:

Count
-----
    1

Use Write-Output Com o Parâmetro NoEnumerate no PowerShell

Também podemos usar o cmdlet Write-Output com o parâmetro -NoEnumerate. O exemplo abaixo usa o cmdlet Measure-Object para contar os objetos enviados ao pipeline a partir da função de exemplo pela palavra-chave return.

Código de Exemplo:

function Test-Return {
    $array = 1, 2, 3
    return Write-Output -NoEnumerate $array
}
Test-Return | Measure-Object | Select-Object Count

Saída:

Count
-----
    1

Outro método de forçar o pipeline a retornar apenas um único objeto foi introduzido na versão 5 do PowerShell, que discutiremos na próxima seção do artigo.

Definindo Classes no PowerShell 5

Com a versão 5.0 do Windows PowerShell, agora podemos criar e definir nossas classes personalizadas. Transforme sua função em uma classe e a palavra-chave return retornará apenas o único objeto imediatamente anterior a ela.

Código de Exemplo:

class test_class {
    [int]return_what() {
        Write-Output "Hello, World!"
        return 1000
    }
}
$tc = New-Object -TypeName test_class
$tc.return_what()

Saída:

1000

Se a classe acima for uma função, ela retornará todos os valores armazenados no pipeline.

Saída:

Hello World!
1000