Parâmetros do Pipeline do PowerShell: Como Criar Funções Prontas para o Pipeline

Você pode ter explorado como o pipeline do PowerShell funciona e como os cmdlets integrados passam dados de um comando para outro. Mas você sabia que pode criar suas próprias funções personalizadas que também utilizam o pipeline? Sim! Com a ligação de parâmetros, suas funções podem agir exatamente como os cmdlets integrados, aceitando dados do pipeline de forma contínua.

Este tutorial irá guiá-lo para equipar suas funções personalizadas com o poder do pipeline, transformando a forma como automatiza e estrutura seus scripts do PowerShell.

Em vez de depender de loops ou entradas manuais, desbloqueie novos níveis de eficiência e flexibilidade em seus scripts!

Habilitando a entrada do Pipeline com ValueFromPipeline

Para que sua função receba informações do pipeline, você deve configurar um ou mais parâmetros para aceitá-lo. Você configurará os parâmetros para usar o atributo ValueFromPipeline ou ValueFromPipelineByPropertyName.

Vamos começar configurando uma função que instala software em vários computadores para passar um array de nomes de computadores para ela sem usar um loop.

Adicione o atributo ValueFromPipeline ao parâmetro ComputerName, permitindo que cada objeto do pipeline de entrada seja tratado como o parâmetro ComputerName.

O PowerShell irá vincular cada objeto do pipeline de entrada a $ComputerName com essa configuração.

function Install-Software {
    param(
        [Parameter(Mandatory)]
        [ValidateSet(1,2)]
        [int]$Version,

        [Parameter(Mandatory, ValueFromPipeline)]
        [string]$ComputerName
    )
    process {
        Write-Host "I installed software version $Version on $ComputerName. Yippee!"
    }
}

Agora, passe um array de nomes de computadores para a função usando o pipeline.

$computers = @("SRV1", "SRV2", "SRV3")
$computers | Install-Software -Version 1

Sem o bloco process, a função só lidaria com o último item. O bloco process permite que a função processe independentemente cada item no array.

Binding por Nome da Propriedade com ValueFromPipelineByPropertyName

Talvez você tenha várias propriedades nos objetos da sua pipeline que precisam corresponder aos parâmetros da sua função. Se for o caso, vamos supor que um arquivo CSV contenha tanto os campos ComputerName quanto Version.

Para demonstrar o binding por nome da propriedade, comece salvando um arquivo CSV contendo essas propriedades:

@(
    [pscustomobject]@{'ComputerName' = 'SRV1'; 'Version' = 1}
    [pscustomobject]@{'ComputerName' = 'SRV2'; 'Version' = 2}
    [pscustomobject]@{'ComputerName' = 'SRV3'; 'Version' = 2}
) | Export-Csv -Path C:\Scripts\software_installs.csv -NoTypeInformation

Atualize a função para aceitar Version e ComputerName por nome da propriedade.

Com ValueFromPipelineByPropertyName, a função corresponde às propriedades em cada objeto (como aqueles importados de um CSV) com os parâmetros na função.

function Install-Software {
    param(
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [ValidateSet(1,2)]
        [int]$Version,

        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [string]$ComputerName
    )
    process {
        Write-Host "I installed software version $Version on $ComputerName. Yippee!"
    }
}

Agora, use Import-Csv para importar o arquivo e encaminhar cada objeto para Install-Software.

Import-Csv -Path C:\Scripts\software_installs.csv | Install-Software

Os campos ComputerName e Version de cada linha se ligam aos respectivos parâmetros na função. Essa abordagem permite o processamento em massa fácil de instalações de software em vários computadores com controle de versão.

Conclusão

Neste tutorial, você aprendeu como habilitar o suporte a pipeline em funções do PowerShell, tornando-as mais versáteis e poderosas. Agora você pode projetar funções personalizadas que aceitam dados da pipeline de forma contínua, semelhante aos cmdlets integrados.

Com funções habilitadas para pipeline, você obtém um controle mais refinado sobre a entrada de dados, simplificando o design do script e melhorando a legibilidade.

Ao continuar trabalhando com o PowerShell, considere integrar essas técnicas para escrever funções eficientes e prontas para a pipeline. Torne seus scripts mais adaptáveis e eficazes na automação de tarefas!