about_Return

  • Artigo

Breve descrição

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

Descrição longa

A 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 fim 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.

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

Nota

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

Sintaxe

A sintaxe da palavra-chave é a return seguinte:

return [<expression>]

A return palavra-chave pode aparecer sozinha ou pode ser seguida por um valor ou expressão, da seguinte forma:

return
return $a
return (2 + $a)

Exemplos

O exemplo a seguir usa a return palavra-chave para sair de uma função em um ponto específico se uma condicional for atendida. Os números ímpares não são multiplicados porque a instrução return é 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 que a return palavra-chave não seja usada. Os resultados de cada declaração são devolvidos. Por exemplo, as instruções a seguir 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, aguarde. Trabalhando no cálculo..." string não é exibida. Em vez disso, ele é atribuído à $a variável, como no exemplo a seguir:

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

Tanto a cadeia informacional quanto 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, começando no PowerShell 5.0, você pode usar o Information fluxo. O código abaixo corrige o exemplo acima usando o Write-Information cmdlet com um InformationAction de Continue.

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

Valores de retorno e o Pipeline

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

Este conceito é ilustrado pela seguinte função de exemplo 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 de script ou função 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 seu valor de retorno pelo 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 abaixo usa o Measure-Object cmdlet para contar os objetos enviados ao pipeline a partir da função de exemplo pela palavra-chave return .

    function Test-Return
{
    $array = 1, 2, 3
    return Write-Output -NoEnumerate $array
}

Test-Return | Measure-Object

    Count    : 1
Average  :
Sum      :
Maximum  :
Minimum  :
Property :

Consulte também