acerca de los conjuntos de parámetros

Breve descripción

Describe cómo definir y utilizar conjuntos de parámetros en funciones avanzadas.

Descripción larga

PowerShell usa conjuntos de parámetros para permitirle escribir una única función que puede realizar diferentes acciones para diferentes escenarios. Los conjuntos de parámetros le permiten exponer diferentes parámetros al usuario. Y para devolver información diferente según los parámetros especificados por el usuario. Sólo puede utilizar un conjunto de parámetros a la vez.

Requisitos del conjunto de parámetros

Los siguientes requisitos se aplican a todos los conjuntos de parámetros.

Si no se especifica ningún conjunto de parámetros para un parámetro, el parámetro pertenece a todos los conjuntos de parámetros.
Cada conjunto de parámetros debe tener una combinación única de parámetros. Si es posible, al menos uno de los parámetros únicos debería ser un parámetro obligatorio.
Un conjunto de parámetros que contiene múltiples parámetros posicionales debe definir posiciones únicas para cada parámetro. No hay dos parámetros posicionales que puedan especificar la misma posición.
Solo un parámetro en un conjunto puede declarar la palabra clave ValueFromPipeline con un valor de true. Varios parámetros pueden definir la palabra clave ValueFromPipelineByPropertyName con un valor de true.

Nota

Hay un límite de 32 conjuntos de parámetros.

Conjuntos de parámetros predeterminados

Cuando se definen varios conjuntos de parámetros, la palabra clave DefaultParameterSetName del atributo CmdletBinding especifica el conjunto de parámetros predeterminado. PowerShell usa el conjunto de parámetros predeterminado cuando no puede determinar el conjunto de parámetros que se usará en función de la información proporcionada al comando. Para obtener más información sobre el atributo CmdletBinding, consulte about_Functions_CmdletBindingAttribute.

Declaración de conjuntos de parámetros

Para crear un conjunto de parámetros, debe especificar la palabra clave ParameterSetName del atributo Parameter para cada parámetro del conjunto de parámetros. Para los parámetros que pertenecen a varios conjuntos de parámetros, agregue un atributo Parameter para cada conjunto de parámetros.

El atributo Parameter le permite definir el parámetro de forma diferente para cada conjunto de parámetros. Por ejemplo, puede definir un parámetro como obligatorio en un conjunto y opcional en otro. Sin embargo, cada conjunto de parámetros debe contener al menos un parámetro único.

Los parámetros que no tienen un nombre de conjunto de parámetros asignado pertenecen a todos los conjuntos de parámetros.

Ejemplos

La siguiente función de ejemplo cuenta las líneas numéricas, los caracteres y las palabras en un archivo de texto. Usando parámetros, puede especificar qué valores desea devolver y qué archivos desea medir. Hay cuatro conjuntos de parámetros definidos:

Camino
PathAll
LiteralPath
RutaliteralTodos

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 debe tener un parámetro único o una combinación única de parámetros. Los conjuntos de parámetros Path y PathAll son muy similares, pero el parámetro All es exclusivo del conjunto de parámetros PathAll. Lo mismo ocurre con los conjuntos de parámetros LiteralPath y LiteralPathAll. Aunque los conjuntos de parámetros PathAll y LiteralPathAll tienen el parámetro All, Path y LiteralPath< Los parámetros los diferencian.

Use Get-Command -Syntax le muestra la sintaxis de cada conjunto de parámetros. Sin embargo, no muestra el nombre del conjunto de parámetros. El siguiente ejemplo muestra qué parámetros se pueden utilizar en 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 en acción

El ejemplo utiliza el conjunto de parámetros PathAll.

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

Error al utilizar parámetros de varios conjuntos

En este ejemplo, se utilizan parámetros únicos de diferentes conjuntos de parámetros.

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.

Los parámetros Path y LiteralPath son exclusivos de diferentes conjuntos de parámetros del cmdlet Get-ChildItem. Cuando los parámetros se ejecutan juntos en el mismo cmdlet, se genera un error. Solo se puede utilizar un conjunto de parámetros por llamada de cmdlet a la vez.

Cómo saber qué conjunto de parámetros se utiliza

La variable automática $PSCmdlet proporciona la propiedad ParameterSetName. Esta propiedad contiene el nombre del conjunto de parámetros que se utiliza. Puede utilizar esta propiedad en su función para determinar qué conjunto de parámetros se utiliza para seleccionar el comportamiento específico del 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