HOWTO · PowerShell
Como Retornar Vários Itens de uma Função PowerShell
Este tutorial ensinará você a retornar múltiplos valores de uma função PowerShell.
Nesta página
Uma função do PowerShell pode emitir vários valores pelo fluxo de sucesso. Para valores relacionados, retorne um array; para valores que serão consultados por chave, use uma tabela hash; e, para um registro com propriedades nomeadas, use [PSCustomObject]. O chamador captura os valores emitidos atribuindo a chamada da função a uma variável.
A palavra-chave return encerra o escopo atual da função e pode emitir um valor, mas não é necessária para produzir saída. Ela também não agrupa várias expressões em um único resultado: toda saída do fluxo de sucesso produzida antes de a função terminar faz parte do resultado. Use um dos formatos a seguir quando quiser que o chamador receba uma coleção ou um registro bem definido.
Como as funções do PowerShell retornam saída
As funções do PowerShell enviam a saída pelo fluxo de sucesso ao chamador. Um comando como Write-Output emite valores, e uma expressão deixada na função também é enviada a esse fluxo. O chamador pode capturar essa saída por atribuição, por exemplo: $result = Get-Data.
return $value emite $value e encerra a função. É útil quando você quer finalizar a execução em um ponto específico, mas não é um contêiner especial para vários valores. Evite emitir uma saída incidental pelo fluxo de sucesso, como uma mensagem de status, quando o chamador espera apenas um objeto de dados; essa saída adicional também será capturada.
Retornar vários valores como um array
Use um array quando o resultado for uma sequência ordenada de valores que o chamador processará em conjunto. O PowerShell envia os elementos do array pelo fluxo de sucesso; capture a chamada com @(...) se quiser que a variável continue sendo um array mesmo que a função retorne apenas um item.
Execute este exemplo:
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
function Get-Colors {
return @('red', 'green', 'blue')
}
$colors = @(Get-Colors)
foreach ($color in $colors) {
Write-Output $color
}
O chamador recebe as três strings e pode percorrê-las em um loop ou passar a sequência para outro comando. Um array preserva a ordem, mas não atribui um nome descritivo a cada valor; use um formato baseado em chaves ou propriedades quando o chamador precisar identificar os valores pelo que representam.
Retornar valores nomeados com uma tabela hash
Uma tabela hash agrupa valores sob chaves exclusivas. Escolha esse formato quando o chamador precisar recuperar valores por uma chave conhecida, especialmente quando o conjunto de chaves for mais útil do que uma sequência posicional.
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
function Get-UserRecord {
return @{
Name = 'Rohan'
Age = 21
Address = 'UK'
}
}
$user = Get-UserRecord
Write-Output "$($user['Name']) is $($user['Age']) and lives in $($user['Address'])."
O chamador acessa uma entrada com $user['Name']; o PowerShell também permite o acesso no estilo de propriedades, como em $user.Name. Prefira a notação com colchetes quando uma chave contiver espaços ou puder ser confundida com o nome de um membro. Uma tabela hash facilita a consulta por chave, mas suas chaves não definem o esquema de um registro.
Retornar um objeto estruturado com [PSCustomObject]
Use [PSCustomObject] para representar um único registro com propriedades nomeadas. Assim, o chamador recebe um só objeto, cujos campos podem ser acessados diretamente e cujos nomes indicam o significado de cada valor.
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
function Get-UserRecord {
return [PSCustomObject]@{
Name = 'Rohan'
Age = 21
Address = 'UK'
}
}
$user = Get-UserRecord
Write-Output "Name: $($user.Name)"
Write-Output "Age: $($user.Age)"
Write-Output "Address: $($user.Address)"
Acesse os campos com $user.Name ou inspecione-os com comandos como Format-List. Percorrer $user em um loop não percorre suas propriedades; o registro é tratado como um objeto. Para processar os próprios campos, acesse as propriedades explicitamente, por exemplo, com $user.PSObject.Properties.
Escolher o formato de retorno adequado
Escolha um array para uma lista ordenada que o chamador percorrerá em um loop, ordenará ou encaminhará por um pipeline. Escolha uma tabela hash quando o chamador precisar consultar valores por chave e uma coleção simples de pares chave-valor for suficiente. Escolha [PSCustomObject] quando a saída representar um único registro com campos nomeados que o chamador acessará ou exibirá.
Seja qual for o formato escolhido, limite a saída da função pelo fluxo de sucesso ao resultado pretendido. Capture a chamada uma vez e, em seguida, use iteração do array, consulta por chave ou acesso a propriedades, conforme o formato do resultado. Isso deixa claro o contrato da função e evita que mensagens incidentais sejam confundidas com os dados retornados.