about_Parameters

Description courte

Décrit comment utiliser des paramètres de commande dans PowerShell.

Description longue

La plupart des commandes PowerShell, telles que les applets de commande, les fonctions et les scripts, s’appuient sur des paramètres pour permettre aux utilisateurs de sélectionner des options ou de fournir des entrées. Les paramètres suivent le nom de la commande et ont le formulaire suivant :

-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>

Le nom du paramètre est précédé d’un trait d’union (-), qui signale à PowerShell que le mot suivant le trait d’union est un nom de paramètre. Le nom et la valeur du paramètre peuvent être séparés par un espace ou un caractère deux-points. Certains paramètres ne nécessitent pas ou n’acceptent pas de valeur de paramètre. D’autres paramètres nécessitent une valeur, mais ne nécessitent pas le nom du paramètre dans la commande.

Le type de paramètres et les exigences de ces paramètres varient. Pour trouver des informations sur les paramètres d’une commande, utilisez l’applet Get-Help de commande. Par exemple, pour trouver des informations sur les paramètres de l’applet Get-ChildItem de commande, tapez :

Get-Help Get-ChildItem

Pour trouver des informations sur les paramètres d’un script, utilisez le chemin d’accès complet au fichier de script. Par exemple :

Get-Help $HOME\Documents\Scripts\Get-Function.ps1

L’applet Get-Help de commande retourne différents détails sur la commande, notamment une description, la syntaxe de la commande, des informations sur les paramètres et des exemples montrant comment utiliser les paramètres dans une commande.

Vous pouvez également utiliser le paramètre Paramètre de l’applet Get-Help de commande pour trouver des informations sur un paramètre particulier. Vous pouvez également utiliser le paramètre Paramètre avec la valeur wild carte character ( * ) pour trouver des informations sur tous les paramètres de la commande. Par exemple, la commande suivante obtient des informations sur tous les paramètres de l’applet Get-Member de commande :

Get-Help Get-Member -Parameter *

Valeurs de paramètres par défaut

Les paramètres facultatifs ont une valeur par défaut, c’est-à-dire la valeur utilisée ou supposée lorsque le paramètre n’est pas spécifié dans la commande.

Par exemple, la valeur par défaut du paramètre ComputerName de nombreuses applets de commande est le nom de l’ordinateur local. Par conséquent, le nom de l’ordinateur local est utilisé dans la commande, sauf si le paramètre ComputerName est spécifié.

Pour rechercher la valeur de paramètre par défaut, consultez la rubrique d’aide de l’applet de commande. La description du paramètre doit inclure la valeur par défaut.

Vous pouvez également définir une valeur par défaut personnalisée pour n’importe quel paramètre d’une applet de commande ou d’une fonction avancée. Pour plus d’informations sur la définition de valeurs par défaut personnalisées, consultez about_Parameters_Default_Values.

Table d’attributs de paramètre

Lorsque vous utilisez les paramètres Full, Parameter ou Online de l’applet Get-Help de commande, Get-Help affiche une table d’attributs de paramètre avec des informations détaillées sur le paramètre.

Ces informations incluent les détails à connaître pour utiliser le paramètre. Par exemple, la rubrique d’aide de l’applet Get-ChildItem de commande inclut les détails suivants sur son paramètre Path :

-Path <string[]>
    Specifies a path of one or more locations. Wildcard characters are
    permitted. The default location is the current directory (.).

Required?                    false
Position?                    0
Default value                Current directory
Accept pipeline input?       true (ByValue, ByPropertyName)
Accept wildcard characters?  true

Les informations de paramètre incluent la syntaxe des paramètres, une description du paramètre et les attributs de paramètre. Les sections suivantes décrivent les attributs de paramètre.

Paramètre requis

Ce paramètre indique si le paramètre est obligatoire, autrement dit, si toutes les commandes qui utilisent cette applet de commande doivent inclure ce paramètre. Lorsque la valeur est True et que le paramètre est manquant dans la commande, PowerShell vous invite à entrer une valeur pour le paramètre.

Position des paramètres

Si le Position paramètre est défini sur un entier non négatif, le nom du paramètre n’est pas obligatoire. Ce type de paramètre est appelé paramètre positionnel, et le nombre indique la position dans laquelle le paramètre doit apparaître par rapport à d’autres paramètres positionnels. Un paramètre nommé peut être répertorié à n’importe quelle position après le nom de l’applet de commande. Si vous incluez le nom du paramètre pour un paramètre positionnel, le paramètre peut être répertorié à n’importe quelle position après le nom de l’applet de commande.

Par exemple, l’applet de commande a des Get-ChildItem paramètres Path et Exclude. Le Position paramètre path est 0, ce qui signifie qu’il s’agit d’un paramètre positionnel. Le Position paramètre d’exclusion est nommé.

Cela signifie que Path ne nécessite pas le nom du paramètre, mais que sa valeur de paramètre doit être la première ou seule valeur de paramètre non nommée dans la commande. Toutefois, étant donné que le paramètre Exclude est un paramètre nommé, vous pouvez le placer à n’importe quelle position dans la commande.

À la suite des paramètres de Position ces deux paramètres, vous pouvez utiliser l’une des commandes suivantes :

Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs

Si vous devez inclure un autre paramètre positionnel sans inclure le nom du paramètre, ce paramètre doit être placé dans l’ordre spécifié par le Position paramètre.

Type de paramètre

Ce paramètre spécifie le type Microsoft .NET Framework de la valeur du paramètre. Par exemple, si le type est Int32, la valeur du paramètre doit être un entier. Si le type est chaîne, la valeur du paramètre doit être une chaîne de caractères. Si la chaîne contient des espaces, la valeur doit être placée entre guillemets, ou les espaces doivent être précédés du caractère d’échappement (`).

Valeur par défaut

Ce paramètre spécifie la valeur que le paramètre suppose si aucune autre valeur n’est fournie. Par exemple, la valeur par défaut du paramètre Path est souvent le répertoire actif. Les paramètres obligatoires n’ont jamais de valeur par défaut. Pour de nombreux paramètres facultatifs, il n’existe aucune valeur par défaut, car le paramètre n’a aucun effet s’il n’est pas utilisé.

Accepte plusieurs valeurs

Ce paramètre indique si un paramètre accepte plusieurs valeurs de paramètre. Lorsqu’un paramètre accepte plusieurs valeurs, vous pouvez taper une liste séparée par des virgules comme valeur du paramètre dans la commande, ou enregistrer une liste séparée par des virgules (un tableau) dans une variable, puis spécifier la variable comme valeur de paramètre.

Par exemple, le paramètre Name de l’applet Get-Service de commande accepte plusieurs valeurs. Les commandes suivantes sont valides :

Get-Service -Name winrm, netlogon
$s = "winrm", "netlogon"
Get-Service -Name $s

Accepte l’entrée de pipeline

Ce paramètre indique si vous pouvez utiliser l’opérateur de pipeline (|) pour envoyer une valeur au paramètre.

Value                    Description
-----                    -----------
False                    Indicates that you cannot pipe a value to the
                         parameter.

True (by Value)          Indicates that you can pipe any value to the
                         parameter, just so the value has the .NET
                         Framework type specified for the parameter or the
                         value can be converted to the specified .NET
                         Framework type.

Lorsqu’un paramètre a la valeur « True (par valeur) », PowerShell tente d’associer toutes les valeurs redirigées à ce paramètre avant d’essayer d’autres méthodes pour interpréter la commande.

True (by Property Name)  Indicates that you can pipe a value to the
                         parameter, but the .NET Framework type of the
                         parameter must include a property with the same
                         name as the parameter.

Par exemple, vous pouvez diriger une valeur vers un paramètre Name uniquement lorsque la valeur a une propriété appelée Name.

Remarque

Un paramètre typé qui accepte l’entrée de pipeline (by Value) ou (by PropertyName) permet d’utiliser des blocs de script de liaison différée sur le paramètre.

Le bloc de script de liaison différée est exécuté automatiquement pendant ParameterBinding. Le résultat est lié au paramètre. La liaison de retard ne fonctionne pas pour les paramètres définis en tant que type ScriptBlock ou System.Object, le bloc de script est transmis sans être appelé.

Vous pouvez en savoir plus sur les blocs de script delay-bind ici about_Script_Blocks.md

Accepte les caractères génériques carte

Ce paramètre indique si la valeur du paramètre peut contenir des caractères génériques carte afin que la valeur du paramètre puisse être mise en correspondance avec plusieurs éléments existants dans le conteneur cible.

Paramètres communs

Les paramètres courants sont des paramètres que vous pouvez utiliser avec n’importe quelle applet de commande. Pour plus d’informations sur les paramètres courants, consultez about_CommonParameters.

Voir aussi