Types de paramètres des applets de commande

Cette rubrique décrit les différents types de paramètres que vous pouvez déclarer dans les applets de commande. Les paramètres d’applet de commande peuvent être positionnels, nommés, obligatoires, facultatifs ou commutateurs.

Paramètres positionnels et nommés

Tous les paramètres d’applet de commande sont nommés ou positionnels. Un paramètre nommé nécessite que vous tapez le nom et l’argument du paramètre lors de l’appel de l’applet de commande. Un paramètre positionnel nécessite uniquement que vous tapez les arguments dans l’ordre relatif. Le système mappe ensuite le premier argument sans nom au premier paramètre positionnel. Le système mappe le deuxième argument sans nom au deuxième paramètre sans nom, et ainsi de suite. Par défaut, tous les paramètres d’applet de commande sont nommés.

Pour définir un paramètre nommé, omettez le mot clé Position dans la déclaration d’attribut Paramètre, comme indiqué dans la déclaration de paramètre suivante.

[Parameter(ValueFromPipeline=true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Pour définir un paramètre positionnel, ajoutez le mot clé Position dans la déclaration d’attribut Paramètre, puis spécifiez une position. Dans l’exemple suivant, le paramètre UserName est déclaré comme paramètre positionnel avec la position 0. Cela signifie que le premier argument de l’appel est automatiquement lié à ce paramètre.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Remarque

Une bonne conception d’applet de commande recommande que les paramètres les plus utilisés soient déclarés en tant que paramètres positionnels afin que l’utilisateur n’ait pas à entrer le nom du paramètre lors de l’exécution de l’applet de commande.

Les paramètres positionnels et nommés acceptent des arguments uniques ou plusieurs arguments séparés par des virgules. Plusieurs arguments sont autorisés uniquement si le paramètre accepte une collection telle qu’un tableau de chaînes. Vous pouvez combiner des paramètres positionnels et nommés dans la même applet de commande. Dans ce cas, le système récupère d’abord les arguments nommés, puis tente de mapper les arguments non nommés restants aux paramètres positionnels.

Les commandes suivantes montrent les différentes façons dont vous pouvez spécifier des arguments uniques et multiples pour les paramètres de l’applet de commande Get-Command. Notez que dans les deux derniers exemples, -Name n’a pas besoin d’être spécifié, car le paramètre Name est défini comme paramètre positionnel.

Get-Command -Name Get-Service
Get-Command -Name Get-Service,Set-Service
Get-Command Get-Service
Get-Command Get-Service,Set-Service

Paramètres obligatoires et facultatifs

Vous pouvez également définir des paramètres d’applet de commande comme paramètres obligatoires ou facultatifs. (Un paramètre obligatoire doit être spécifié avant que le runtime PowerShell appelle l’applet de commande.) Par défaut, les paramètres sont définis comme facultatifs.

Pour définir un paramètre obligatoire, ajoutez le mot clé Mandatory dans la déclaration d’attribut Paramètre et définissez-le sur true, comme indiqué dans la déclaration de paramètre suivante.

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

Pour définir un paramètre facultatif, omettez le mot clé Mandatory dans la déclaration d’attribut Paramètre, comme indiqué dans la déclaration de paramètre suivante.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Changer de paramètres

PowerShell fournit un type System.Management.Automation.SwitchParameter qui vous permet de définir un paramètre dont la valeur par défaut false, sauf si le paramètre est spécifié lorsque l’applet de commande est appelée. Dans la mesure du possible, utilisez les paramètres de commutateur au lieu des paramètres booléens.

Prenons l’exemple suivant : De nombreuses applets de commande PowerShell retournent la sortie. Toutefois, ces applets de commande ont un paramètre de commutateur PassThru qui remplace le comportement par défaut. Lorsque vous utilisez le paramètre PassThru, l’applet de commande retourne des objets de sortie au pipeline.

Pour définir un paramètre de commutateur, déclarez la propriété en tant que type [SwitchParameter], comme indiqué dans l’exemple suivant.

[Parameter()]
public SwitchParameter GoodBye
{
  get { return goodbye; }
  set { goodbye = value; }
}
private bool goodbye;

Pour que l’applet de commande agisse sur le paramètre lorsqu’elle est spécifiée, utilisez la structure suivante dans l’une des méthodes de traitement d’entrée.

protected override void ProcessRecord()
{
  WriteObject("Switch parameter test: " + userName + ".");
  if (goodbye)
  {
    WriteObject(" Goodbye!");
  }
} // End ProcessRecord

Par défaut, les paramètres de commutateur sont exclus des paramètres positionnels. Vous pouvez remplacer cela dans l’attribut paramètre de, mais cela peut confondre les utilisateurs.

Les paramètres de commutateur de conception afin que l’utilisation du paramètre modifie le comportement par défaut de la commande en mode moins courant ou plus compliqué. Le comportement le plus simple d’une commande doit être le comportement par défaut qui ne nécessite pas l’utilisation des paramètres de commutateur. Basez le comportement contrôlé par le commutateur sur la valeur du commutateur, et non la présence du paramètre.

Il existe plusieurs façons de tester la présence d’un paramètre de commutateur :

• Invocation.BoundParameters contient le nom du paramètre switch en tant que clé
• PSCmdlet.ParameterSetName lorsque le commutateur définit un jeu de paramètres unique

Par exemple, il est possible de fournir une valeur explicite pour le commutateur à l’aide de -MySwitch:$false ou de la plaque. Si vous testez uniquement la présence du paramètre, la commande se comporte comme si la valeur de commutateur est $true au lieu de $false.

Voir aussi

écriture d’une applet de commande Windows PowerShell