Parâmetros do Pipeline do PowerShell: Como Criar Funções Prontas para 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 um vinculaçã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á orientá-lo a equipar suas funções personalizadas com o poder do pipeline, transformando a forma como você 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á-las. Você configurará 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 computador 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 vinculará cada objeto do pipeline de entrada ao $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 computador 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 múltiplas 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 propriedades em cada objeto (como aqueles importados de um CSV) com 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 transparente, semelhante aos cmdlets integrados.

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

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