Como Retornar Vários Itens de uma Função PowerShell

1. Usar Array para Retornar Vários Itens de uma Função do PowerShell
2. Usar [PSCustomObject] para Retornar Vários Itens de uma Função do PowerShell
3. Usar Tabelas Hash para Retornar Vários Itens de uma Função do PowerShell
4. Usar Objetos Personalizados para Retornar Vários Itens de uma Função do PowerShell
5. Conclusão

Ao trabalhar com funções do PowerShell, muitas vezes surge a necessidade de retornar vários valores de forma eficiente. Uma abordagem eficaz é utilizar arrays, [PSCustomObject], tabelas hash ou objetos personalizados para encapsular e apresentar esses valores.

Neste artigo, vamos explorar como usar os métodos mencionados para retornar vários itens de uma função do PowerShell. Vamos delinear procedimentos passo a passo para cada método e fornecer exemplos de código para ilustrar sua implementação e mostrar suas saídas.

Usar Array para Retornar Vários Itens de uma Função do PowerShell

Para retornar vários valores de uma função do PowerShell usando um array, siga estas etapas:

Vamos criar uma função simples do PowerShell que retorne vários valores usando um array.

function Get-MultipleValues {
    $values = @()

    $values += "Value1"
    $values += "Value2"
    $values += "Value3"

    return $values
}

$resultArray = Get-MultipleValues

Write-Output "Values returned from the function:"
foreach ($value in $resultArray) {
    Write-Output $value
}

Saída:

Values returned from the function:
Value1
Value2
Value3

Neste exemplo, temos uma função chamada Get-MultipleValues. Dentro da função, declaramos uma variável de array $values.

Em seguida, populamos esse array com três valores: "Value1", "Value2" e "Value3". Por fim, retornamos o array preenchido como a saída da função.

Ao chamar a função, armazenamos o resultado em uma variável ($resultArray) e exibimos os valores dentro do array usando um loop.

Usar [PSCustomObject] para Retornar Vários Itens de uma Função do PowerShell

Você também pode usar [PSCustomObject] para criar objetos personalizados no PowerShell. Ele permite que você defina propriedades e valores para um objeto, tornando-se uma escolha adequada para retornar vários valores de uma função.

Para criar um objeto personalizado usando [PSCustomObject], você simplesmente define as propriedades e seus valores correspondentes assim:

$customObject = [PSCustomObject]@{
    Property1 = 'Value1'
    Property2 = 'Value2'
    ...
}

Para retornar vários valores usando [PSCustomObject] em uma função do PowerShell, comece definindo a função do PowerShell e criando uma instância de [PSCustomObject]. Defina as propriedades e os valores que você deseja retornar dentro do objeto personalizado.

function Get-MultipleValues {
    [CmdletBinding()]
    param (
        [string]$Value1,
        [int]$Value2,
        [string]$Value3
    )

    $resultObject = [PSCustomObject]@{
        Name    = $Value1
        Age     = $Value2
        Address = $Value3
    }

    return $resultObject
}

Agora, você pode chamar a função e recuperar o objeto personalizado contendo vários valores.

$result = Get-MultipleValues -Value1 'Rohan' -Value2 21 -Value3 'UK'

Write-Output "Values returned from the function:"
foreach ($value in $result) {
    Write-Output $value
}

Saída:

Values returned from the function:
Name  Age Address
----  --- -------
Rohan  21 UK

Como podemos ver, o código do PowerShell acima introduz uma função chamada Get-MultipleValues. Esta função, marcada com [CmdletBinding()], indica sua capacidade de utilizar parâmetros comuns de cmdlets.

Dentro da função, três parâmetros são definidos: $Value1 (uma string), $Value2 (um inteiro) e $Value3 (uma string). A função constrói um objeto personalizado chamado $resultObject usando esses parâmetros, atribuindo-os às propriedades Name, Age e Address dentro do objeto personalizado.

A instrução return $resultObject garante que este objeto personalizado seja retornado como a saída da função Get-MultipleValues.

Depois disso, o script chama a função Get-MultipleValues, especificando valores para cada parâmetro: $Value1 é definido como 'Rohan', $Value2 é definido como 21 e $Value3 é definido como 'UK'. O objeto personalizado resultante, incorporando os valores dos parâmetros fornecidos, é armazenado na variável $result.

Em seguida, o script utiliza Write-Output para apresentar uma mensagem no console e inicia um loop, percorrendo as propriedades do objeto personalizado mantido em $result. Para cada propriedade, o script exibe tanto o nome da propriedade quanto seu valor respectivo no console.

Usar Tabelas Hash para Retornar Vários Itens de uma Função do PowerShell

Uma tabela hash no PowerShell é uma coleção não ordenada de pares chave-valor. Cada chave deve ser única, e o valor associado pode ser de qualquer tipo de dado.

Ela também é chamada de dicionário ou array associativo. Tabelas hash são particularmente úteis quando você precisa armazenar e recuperar dados com base em chaves específicas, fornecendo uma maneira estruturada de organizar informações.

Para retornar vários valores de uma função do PowerShell usando tabelas hash, siga estas etapas:

Vamos ter um exemplo que usa a tabela hash para retornar vários valores de uma função chamada user.

Código:

function user() {
    $hash = @{ Name = 'Rohan'; Age = 21; Address = 'UK' }
    return $hash
}

$a = user
Write-Host "$($a.Name) is $($a.Age) and lives in $($a.Address)."

Saída:

Rohan is 21 and lives in UK.

Como podemos ver, este código define uma função chamada user() usando a palavra-chave function. Dentro dessa função, uma tabela hash chamada $hash é criada usando a sintaxe @{}, contendo três pares chave-valor: Name com o valor 'Rohan', Age com o valor 21 e Address com o valor 'UK'.

A instrução return $hash garante que esta tabela hash seja a saída da função user().

Subsequentemente, o script chama a função user() e atribui a tabela hash resultante à variável $a. Isso significa que $a agora contém a tabela hash retornada pela função user().

Finalmente, o cmdlet Write-Host é usado para exibir uma mensagem no console. A mensagem incorpora os valores da tabela hash armazenados em $a, recuperados usando $($a.Name), $($a.Age) e $($a.Address) para acessar os valores de Name, Age e Address, respectivamente.

Agora, vamos criar outra função do PowerShell que calcula a soma e o produto de dois números e retorna os resultados usando uma tabela hash.

function Calculate-SumAndProduct {
    param(
        [int]$num1,
        [int]$num2
    )

    $resultHashTable = @{
        Sum     = $num1 + $num2
        Product = $num1 * $num2
    }

    return $resultHashTable
}

$inputNum1 = 5
$inputNum2 = 7

$result = Calculate-SumAndProduct -num1 $inputNum1 -num2 $inputNum2

Write-Output "Sum: $($result['Sum'])"
Write-Output "Product: $($result['Product'])"

Saída:

Sum: 12
Product: 35

Este código começa definindo uma função chamada Calculate-SumAndProduct, que aceita dois parâmetros int, $num1 e $num2. Dentro da função, uma tabela hash chamada $resultHashTable é criada usando a sintaxe @{}.

Essa tabela hash contém dois pares chave-valor: Sum com um valor igual à soma de $num1 e $num2, e Product com um valor igual ao produto de $num1 e $num2. A função então retorna esta tabela hash, tornando-a a saída da função Calculate-SumAndProduct.

Seguindo em frente no script, dois números de entrada são definidos: $inputNum1 com um valor de 5 e $inputNum2 com um valor de 7. A função Calculate-SumAndProduct é chamada com esses números de entrada, e a tabela hash resultante é armazenada em uma variável chamada $result.

Finalmente, o script usa o cmdlet Write-Output para exibir os valores de soma e produto acessando os valores correspondentes na tabela hash armazenada em $result.

Usar Objetos Personalizados para Retornar Vários Itens de uma Função do PowerShell

Um objeto personalizado no PowerShell é uma instância da classe System.Management.Automation.PSCustomObject. Ele permite que você defina propriedades e valores associados a essas propriedades, imitando um objeto do mundo real.

Objetos personalizados são flexíveis e permitem a organização e recuperação de dados de maneira estruturada.

Para retornar vários valores de uma função do PowerShell usando objetos personalizados, siga estas etapas:

Vamos criar uma função do PowerShell que calcula a soma e o produto de dois números e retorna os resultados usando um objeto personalizado.

function Calculate-SumAndProduct {
    param(
        [int]$num1,
        [int]$num2
    )

    $resultObject = New-Object PSObject
    $resultObject | Add-Member -MemberType NoteProperty -Name "Sum" -Value ($num1 + $num2)
    $resultObject | Add-Member -MemberType NoteProperty -Name "Product" -Value ($num1 * $num2)

    return $resultObject
}

$inputNum1 = 5
$inputNum2 = 7

$result = Calculate-SumAndProduct -num1 $inputNum1 -num2 $inputNum2

Write-Output "Sum: $($result.Sum)"
Write-Output "Product: $($result.Product)"

Saída:

Sum: 12
Product: 35

Neste exemplo, definimos uma função chamada Calculate-SumAndProduct que aceita dois números de entrada ($num1 e $num2). Dentro da função, criamos um objeto personalizado chamado $resultObject e adicionamos propriedades (Sum e Product) a ele, atribuindo os valores calculados respectivos.

Ao chamar a função com números de entrada (5 e 7), armazenamos o resultado em uma variável ($result). Então exibimos a soma e o produto acessando as propriedades do objeto personalizado de resultado.

Conclusão

Este artigo explorou várias técnicas para retornar múltiplos valores de uma função, incluindo o uso de arrays, [PSCustomObject], tabelas hash e objetos personalizados. Cada método oferece suas vantagens e pode ser selecionado com base nos requisitos específicos do seu script.

Arrays fornecem uma maneira direta de retornar múltiplos valores, especialmente quando os itens de dados compartilham um tipo ou estrutura similar. [PSCustomObject] permite que você crie objetos personalizados com propriedades nomeadas, oferecendo uma abordagem estruturada para retornar dados.

Tabelas hash se destacam em cenários onde a recuperação de dados é baseada em chaves específicas, proporcionando uma solução organizada e eficiente. Objetos personalizados, construídos usando a classe [System.Management.Automation.PSCustomObject], oferecem flexibilidade e imitam objetos do mundo real.