Conjuntos de parámetros de cmdlet

PowerShell usa conjuntos de parámetros para permitirle escribir un único cmdlet que puede realizar acciones diferentes para distintos escenarios. Los conjuntos de parámetros permiten exponer distintos parámetros al usuario. Y, para devolver información diferente en función de los parámetros especificados por el usuario.

Ejemplos de conjuntos de parámetros

Por ejemplo, el cmdlet de PowerShell devuelve información diferente en función de si el Get-EventLog usuario especifica el parámetro List o LogName. Si se especifica el parámetro List, el cmdlet devuelve información sobre los propios archivos de registro, pero no la información de eventos que contienen. Si se especifica el parámetro LogName, el cmdlet devuelve información sobre los eventos de un registro de eventos específico. Los parámetros List y LogName identifican dos conjuntos de parámetros independientes.

Parámetro único

Cada conjunto de parámetros debe tener un parámetro único que el tiempo de ejecución de PowerShell usa para exponer el conjunto de parámetros adecuado. Si es posible, el parámetro único debe ser un parámetro obligatorio. Cuando un parámetro es obligatorio, el usuario debe especificar el parámetro y el tiempo de ejecución de PowerShell usa ese parámetro para identificar el conjunto de parámetros. El parámetro único no puede ser obligatorio si el cmdlet está diseñado para ejecutarse sin especificar ningún parámetro.

Varios conjuntos de parámetros

En la ilustración siguiente, la columna izquierda muestra tres conjuntos de parámetros válidos. El parámetro A es único para el primer conjunto de parámetros, el parámetro B es único para el segundo conjunto de parámetros y el parámetro C es único para el tercer conjunto de parámetros. En la columna derecha, los conjuntos de parámetros no tienen un parámetro único.

Requisitos del conjunto de parámetros

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

• Cada conjunto de parámetros debe tener al menos un parámetro único. Si es posible, haga que este parámetro sea 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 .

• 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.

Nota

Para un cmdlet o una función, hay un límite de 32 conjuntos de parámetros.

Conjuntos de parámetros predeterminados

Cuando se definen varios conjuntos de parámetros, puede usar la palabra DefaultParameterSetName clave del atributo Cmdlet para especificar el conjunto de parámetros predeterminado. PowerShell usa el conjunto de parámetros predeterminado si no puede determinar el conjunto de parámetros que se va a usar en función de la información proporcionada por el comando. Para obtener más información sobre el atributo cmdlet, vea Declaración de atributo de cmdlet.

Declarar conjuntos de parámetros

Para crear un conjunto de parámetros, debe especificar la palabra clave al declarar el atributo ParameterSetName 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. Este atributo 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 un parámetro único. Para obtener más información, vea Declaración de atributo de parámetro.

En el ejemplo siguiente, el parámetro UserName es el parámetro único del conjunto de parámetros y el parámetro ComputerName es el parámetro único Test01 del conjunto de Test02 parámetros. El parámetro SharedParam pertenece a ambos conjuntos y es obligatorio para el conjunto de parámetros, pero opcional para el conjunto de Test01 Test02 parámetros.

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test01")]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test02")]
public string ComputerName
{
  get { return computerName; }
  set { computerName = value; }
}
private string computerName;

[Parameter(Mandatory= true, ParameterSetName = "Test01")]
[Parameter(ParameterSetName = "Test02")]
public string SharedParam
{
    get { return sharedParam; }
    set { sharedParam = value; }
}
private string sharedParam;