Sobre o Retorno

Artigo
05/09/2024

Descrição breve

Sai do escopo atual, que pode ser uma função, um script ou um bloco de script.

Descrição longa

O return palavra-chave sai de uma função, script ou bloco de script. Ele pode ser usado para sair de um escopo em um ponto específico, para retornar um valor ou para indicar que o final do escopo foi atingido.

Os usuários que estão familiarizados com linguagens como C ou C# podem querer usar a return palavra-chave para tornar explícita a lógica de deixar um escopo explícito.

No PowerShell, os resultados de cada instrução são retornados como saída, mesmo sem uma instrução que contenha o return palavra-chave. Linguagens como C ou C# retornam apenas o valor ou os valores especificados pelo return palavra-chave.

Observação

A partir do PowerShell 5.0, o PowerShell adicionou uma linguagem para definir classes usando a sintaxe formal. No contexto de uma classe do PowerShell, nada é gerado de um método, exceto o que você especificar uma return instrução. Você pode ler mais sobre classes do PowerShell em about_Classes.

Syntax

A sintaxe do palavra-chave é a return seguinte:

return [<expression>]

O return palavra-chave pode aparecer sozinho ou pode ser seguido por um valor ou expressão, da seguinte maneira:

return
return $a
return (2 + $a)

Exemplos

O exemplo a seguir usa o return palavra-chave para sair de uma função em um ponto específico se um condicional for atendido. Números ímpares não são multiplicados porque a return instrução é encerrada antes que essa instrução possa ser executada.

function MultiplyEven
{
    param($number)

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

1..10 | ForEach-Object {MultiplyEven -Number $_}

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

No PowerShell, os valores podem ser retornados mesmo se o return palavra-chave não for usado. Os resultados de cada instrução são retornados. Por exemplo, as seguintes instruções retornam o valor da $a variável :

$a
return

A instrução a seguir também retorna o valor de $a:

return $a

O exemplo a seguir inclui uma instrução destinada a informar ao usuário que a função está executando um cálculo:

function calculation {
    param ($value)

    "Please wait. Working on calculation..."
    $value += 73
    return $value
}

$a = calculation 14

O "Por favor, espere. Trabalhando no cálculo..." A cadeia de caracteres não é exibida. Em vez disso, ela é atribuída à $a variável , como no exemplo a seguir:

PS> $a
Please wait. Working on calculation...
87

A cadeia de caracteres informativa e o resultado do cálculo são retornados pela função e atribuídos à $a variável.

Se você quiser exibir uma mensagem dentro de sua função, a partir do PowerShell 5.0, poderá usar o Information fluxo. O código a seguir corrige o exemplo acima usando o Write-Information cmdlet com um InformationAction de Continuar.

function calculation {
    param ($value)

    Write-Information "Please wait. Working on calculation..." -InformationAction Continue
    $value += 73
    return $value
}

$a = calculation 14

Please wait. Working on calculation...
C:\PS> $a
87

Retornar valores e o pipeline

Quando você retorna uma coleção do bloco ou função de script, o PowerShell cancela automaticamente os membros e os passa um de cada vez pelo pipeline. Isso ocorre devido ao processamento único do PowerShell. Para obter mais informações, consulte about_pipelines.

Esse conceito é ilustrado pela função de exemplo a seguir que retorna uma matriz de números. A saída da função é canalizada para o Measure-Object cmdlet que conta o número de objetos no pipeline.

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

Count    : 3
Average  :
Sum      :
Maximum  :
Minimum  :
Property :

Para forçar um bloco ou função de script a retornar a coleção como um único objeto para o pipeline, use um dos dois métodos a seguir:

Expressão de matriz unária

Utilizando uma expressão unária, você pode enviar o valor retornado para baixo do pipeline como um único objeto, conforme ilustrado pelo exemplo a seguir.
```
function Test-Return
{
    $array = 1,2,3
    return (, $array)
}
Test-Return | Measure-Object
```
```
Count    : 1
Average  :
Sum      :
Maximum  :
Minimum  :
Property :
```
Write-Output com o parâmetro NoEnumerate .

Você também pode usar o Write-Output cmdlet com o parâmetro NoEnumerate . O exemplo a seguir usa o Measure-Object cmdlet para contar os objetos enviados para o pipeline da função de exemplo pelo return palavra-chave.
```
function Test-Return
{
    $array = 1, 2, 3
    return Write-Output -NoEnumerate $array
}

Test-Return | Measure-Object
```
```
Count    : 1
Average  :
Sum      :
Maximum  :
Minimum  :
Property :
```

Confira também

about_Language_Keywords

Compartilhar via