about_Parameter_Sets

Artigo
03/29/2024

Breve descrição

Descreve como definir e usar conjuntos de parâmetros em funções avançadas.

Descrição longa

O PowerShell usa conjuntos de parâmetros para permitir que você escreva uma única função que pode executar ações diferentes para diferentes cenários. Os conjuntos de parâmetros permitem que você exponha parâmetros diferentes para o usuário. E, para retornar informações diferentes com base nos parâmetros especificados pelo usuário. Você só pode usar um conjunto de parâmetros de cada vez.

Requisitos do conjunto de parâmetros

Os seguintes requisitos aplicam-se a todos os conjuntos de parâmetros.

Se nenhum conjunto de parâmetros for especificado para um parâmetro, o parâmetro pertencerá a todos os conjuntos de parâmetros.
Cada conjunto de parâmetros deve ter uma combinação única de parâmetros. Se possível, pelo menos um dos parâmetros únicos deve ser um parâmetro obrigatório.
Um conjunto de parâmetros que contém vários parâmetros posicionais deve definir posições exclusivas para cada parâmetro. Não há dois parâmetros posicionais que possam especificar a mesma posição.
Apenas um parâmetro em um conjunto pode declarar a ValueFromPipeline palavra-chave com um valor de true. Vários parâmetros podem definir a ValueFromPipelineByPropertyName palavra-chave com um valor de true.

Nota

Há um limite de 32 conjuntos de parâmetros.

Conjuntos de parâmetros padrão

Quando vários conjuntos de parâmetros são definidos, a DefaultParameterSetName palavra-chave do atributo CmdletBinding especifica o conjunto de parâmetros padrão. O PowerShell usa o conjunto de parâmetros padrão quando não pode determinar o conjunto de parâmetros a ser usado com base nas informações fornecidas ao comando. Para obter mais informações sobre o atributo CmdletBinding , consulte about_Functions_CmdletBindingAttribute.

Declarando conjuntos de parâmetros

Para criar um conjunto de parâmetros, você deve especificar a ParameterSetName palavra-chave do atributo Parameter para cada parâmetro no conjunto de parâmetros. Para parâmetros que pertencem a vários conjuntos de parâmetros, adicione um atributo Parameter para cada conjunto de parâmetros.

O atributo Parameter permite definir o parâmetro de forma diferente para cada conjunto de parâmetros. Por exemplo, você pode definir um parâmetro como obrigatório em um conjunto e opcional em outro. No entanto, cada conjunto de parâmetros deve conter pelo menos um parâmetro exclusivo.

Os parâmetros que não têm um nome de conjunto de parâmetros atribuído pertencem a todos os conjuntos de parâmetros.

Exemplos

A função de exemplo a seguir conta as linhas numéricas, caracteres e palavras em um arquivo de texto. Usando parâmetros, você pode especificar quais valores deseja retornar e quais arquivos deseja medir. Existem quatro conjuntos de parâmetros definidos:

Caminho
CaminhoTudo
Caminho Literal
LiteralPathAll

function Measure-Lines {
    [CmdletBinding(DefaultParameterSetName = 'Path')]
    param (
        [Parameter(Mandatory, ParameterSetName = 'Path', Position = 0)]
        [Parameter(Mandatory, ParameterSetName = 'PathAll', Position = 0)]
        [string[]]$Path,

        [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll', ValueFromPipeline)]
        [Parameter(Mandatory, ParameterSetName = 'LiteralPath', ValueFromPipeline)]
        [string[]]$LiteralPath,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Lines,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Words,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Characters,

        [Parameter(Mandatory, ParameterSetName = 'PathAll')]
        [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll')]
        [switch]$All,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'PathAll')]
        [switch]$Recurse
    )

    begin {
        if ($All) {
            $Lines = $Words = $Characters = $true
        }
        elseif (($Words -eq $false) -and ($Characters -eq $false)) {
            $Lines  = $true
        }
    }
    process {
        if ($Path) {
            $Files = Get-ChildItem -Path $Path -Recurse:$Recurse -File
        }
        else {
            $Files = Get-ChildItem -LiteralPath $LiteralPath -File
        }
        foreach ($file in $Files) {
            $result = [ordered]@{ }
            $result.Add('File', $file.fullname)

            $content = Get-Content -LiteralPath $file.fullname

            if ($Lines) { $result.Add('Lines', $content.Length) }

            if ($Words) {
                $wc = 0
                foreach ($line in $content) { $wc += $line.split(' ').Length }
                $result.Add('Words', $wc)
            }

            if ($Characters) {
                $cc = 0
                foreach ($line in $content) { $cc += $line.Length }
                $result.Add('Characters', $cc)
            }

            New-Object -TypeName psobject -Property $result
        }
    }
}

Cada conjunto de parâmetros deve ter um parâmetro exclusivo ou uma combinação única de parâmetros. Os Path conjuntos de parâmetros e PathAll são muito semelhantes, mas o parâmetro All é exclusivo para o conjunto de PathAll parâmetros. O mesmo acontece com os LiteralPath conjuntos de parâmetros e LiteralPathAll . Embora os PathAll conjuntos de parâmetros e LiteralPathAll tenham o parâmetro All , os parâmetros Path e LiteralPath os diferenciam.

Usar Get-Command -Syntax mostra a sintaxe de cada conjunto de parâmetros. No entanto, ele não mostra o nome do conjunto de parâmetros. O exemplo a seguir mostra quais parâmetros podem ser usados em cada conjunto de parâmetros.

(Get-Command Measure-Lines).ParameterSets |
  Select-Object -Property @{n='ParameterSetName';e={$_.name}},
    @{n='Parameters';e={$_.ToString()}}

ParameterSetName Parameters
---------------- ----------
Path             [-Path] <string[]> [-Lines] [-Words] [-Characters] [-Recurse] [<CommonParameters>]
PathAll          [-Path] <string[]> -All [-Recurse] [<CommonParameters>]
LiteralPath      -LiteralPath <string[]> [-Lines] [-Words] [-Characters] [<CommonParameters>]
LiteralPathAll   -LiteralPath <string[]> -All [<CommonParameters>]

Conjuntos de parâmetros em ação

O exemplo usa o conjunto de PathAll parâmetros.

Measure-Lines test* -All

File                       Lines Words Characters
----                       ----- ----- ----------
C:\temp\test\test.help.txt    31   562       2059
C:\temp\test\test.md          30  1527       3224
C:\temp\test\test.ps1          3     3         79
C:\temp\test\test[1].txt      31   562       2059

Erro ao usar parâmetros de vários conjuntos

Neste exemplo, parâmetros exclusivos de diferentes conjuntos de parâmetros são usados.

Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME

Get-ChildItem: Parameter set cannot be resolved using the specified named
parameters. One or more parameters issued cannot be used together or an
insufficient number of parameters were provided.

Os parâmetros Path e LiteralPath são exclusivos para diferentes conjuntos de parâmetros do Get-ChildItem cmdlet. Quando os parâmetros são executados juntos no mesmo cmdlet, um erro é gerado. Apenas um conjunto de parâmetros pode ser usado por chamada de cmdlet de cada vez.

Como saber qual conjunto de parâmetros é usado

A variável $PSCmdlet automática fornece a propriedade ParameterSetName . Esta propriedade contém o nome do conjunto de parâmetros que está sendo usado. Você pode usar essa propriedade em sua função para determinar qual conjunto de parâmetros está sendo usado para selecionar o comportamento específico do conjunto de parâmetros.

function Get-ParameterSetName {

    [CmdletBinding(DefaultParameterSetName = 'Set1')]
    param (
        [Parameter(ParameterSetName = 'Set1', Position = 0)]
        $Var1,

        [Parameter(ParameterSetName = 'Set2', Position = 0)]
        $Var2,

        [Parameter(ParameterSetName = 'Set1', Position = 1)]
        [Parameter(ParameterSetName = 'Set2', Position = 1)]
        $Var3,

        [Parameter(Position = 2)]
        $Var4
    )

    "Using Parameter set named '$($PSCmdlet.ParameterSetName)'"

    switch ($PSCmdlet.ParameterSetName) {
        'Set1' {
            "`$Var1 = $Var1"
            "`$Var3 = $Var3"
            "`$Var4 = $Var4"
            break
        }
        'Set2' {
            "`$Var2 = $Var2"
            "`$Var3 = $Var3"
            "`$Var4 = $Var4"
            break
        }
    }
}

PS> Get-ParameterSetName 1 2 3

Using Parameter set named 'Set1'
$Var1 = 1
$Var3 = 2
$Var4 = 3

PS> Get-ParameterSetName -Var2 1 2 3

Using Parameter set named 'Set2'
$Var2 = 1
$Var3 = 2
$Var4 = 3

Partilhar via