Compartir a través de

about_Parameter_Sets

  • Artículo

Descripción breve

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

Descripción larga

PowerShell usa conjuntos de parámetros para permitirle escribir una sola función que pueda realizar diferentes acciones para distintos escenarios. Los conjuntos de parámetros permiten exponer parámetros diferentes al usuario. Además, para devolver información diferente en función de los parámetros especificados por el usuario. Solo puede usar 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, este 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 debe ser un parámetro obligatorio.

  • Un conjunto de parámetros que contiene varios 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 de un conjunto puede declarar la ValueFromPipeline palabra clave con un valor de true. Varios parámetros pueden definir la ValueFromPipelineByPropertyName palabra clave 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 DefaultParameterSetName palabra clave 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 va a 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 ParameterSetName palabra clave 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 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 de número, los caracteres y las palabras de un archivo de texto. Con parámetros, puede especificar qué valores desea devolver y qué archivos desea medir. Hay cuatro conjuntos de parámetros definidos:

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

Use Get-Command -Syntax muestra la sintaxis de cada conjunto de parámetros. Sin embargo, no muestra el nombre del conjunto de parámetros. En el ejemplo siguiente se muestra qué parámetros se pueden usar 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

En el ejemplo se usa el 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

Error al usar parámetros de varios conjuntos

En este ejemplo, se usan parámetros únicos de distintos 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 únicos para distintos conjuntos de parámetros del Get-ChildItem cmdlet. Cuando los parámetros se ejecutan juntos en el mismo cmdlet, se produce un error. Solo se puede usar un conjunto de parámetros por llamada de cmdlet a la vez.

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

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