about_Parameter_Sets
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
ValueFromPipelinepalabra clave con un valor detrue. Varios parámetros pueden definir laValueFromPipelineByPropertyNamepalabra clave con un valor detrue.
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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de