about_CommonParameters
Mis à jour: mai 2014
S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
Insérez l'introduction ici.
RUBRIQUE
about_CommonParameters
DESCRIPTION COURTE
Décrit les paramètres qui peuvent être utilisés avec toutes les applets de commande.
DESCRIPTION DÉTAILLÉE
Les paramètres communs constituent un ensemble de paramètres d'applet de commande que vous pouvez utiliser avec toutes les applets de commande. Implémentés par Windows PowerShell®, et non par le développeur de l'applet de commande, ils sont automatiquement disponibles dans chaque applet de commande.
Les paramètres communs peuvent être utilisés avec n'importe quelle applet de commande, mais ils sont parfois sans effet dans les applets de commande. Par exemple, si une applet de commande ne génère pas de sortie commentée, le paramètre commun Verbose n'a aucun effet.
Les paramètres communs sont également disponibles pour les fonctions avancées qui possèdent l'attribut CmdletBinding ou Parameter, ainsi que pour tous les workflows.
Plusieurs paramètres communs remplacent les valeurs système par défaut ou les préférences que vous définissez à l'aide des variables de préférence Windows PowerShell. Contrairement aux variables de préférence, les paramètres communs s'appliquent uniquement aux commandes dans lesquelles ils sont utilisés.
Outre les paramètres communs, de nombreuses applets de commande fournissent les paramètres d'atténuation des risques WhatIf et Confirm. Ces paramètres sont généralement fournis dans les applets de commande qui entraînent des risques pour le système ou les données utilisateur.
Les paramètres communs sont répertoriés ci-après. Leurs alias sont indiqués entre parenthèses.
-Debug (db)
-ErrorAction (ea)
-ErrorVariable (ev)
-OutVariable (ov)
-OutBuffer (ob)
-PipelineVariable (pv)
-Verbose (vb)
-WarningAction (wa)
-WarningVariable (wv
Les paramètres d'atténuation des risques sont les suivants :
-WhatIf (wi)
-Confirm (cf)
Pour plus d'informations sur les variables de préférence, tapez :
help about_Preference_Variables
DESCRIPTION DES PARAMÈTRES COMMUNS
-DEBUG[:{$TRUE | $FALSE}]
Alias: db
Affiche des informations pour le programmeur concernant l'opération effectuée par la commande. Ce paramètre s'applique uniquement quand la commande génère un message de débogage. Par exemple, ce paramètre s'applique quand une commande contient l'applet de commande Write-Debug.
Le paramètre Debug remplace la valeur de la variable $DebugPreference pour la commande actuelle par la valeur Inquire. Étant donné que la valeur par défaut de la variable $DebugPreference est SilentlyContinue, les messages de débogage ne sont pas affichés par défaut.
Valeurs valides :
$true (-Debug:$true). Has the same effect as -Debug.
$false (-Debug:$false). Suppresses the display of debugging
messages when the value of the $DebugPreference is not
SilentlyContinue (the default).
-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]
Alias: ea
Détermine comment l'applet de commande répond à une erreur sans fin d'exécution de la commande. Ce paramètre s'applique uniquement quand la commande génère une erreur sans fin d'exécution, comme celles reçues de l'applet de commande Write-Error.
Le paramètre ErrorAction remplace la valeur de la variable $ErrorActionPreference pour la commande actuelle. Étant donné que la valeur par défaut de la variable $ErrorActionPreference est Continue, les messages d'erreur sont affichés et l'exécution se poursuit, sauf si vous utilisez le paramètre ErrorAction.
Le paramètre ErrorAction n'a aucun effet sur les erreurs avec fin d'exécution (par exemple, données manquantes, paramètres non valides ou autorisations insuffisantes) qui empêchent une commande de s'exécuter correctement.
Valeurs valides :
Continue. Affiche le message d'erreur et poursuit l'exécution de la commande. « Continue » est la valeur par défaut.
Ignore. Supprime le message d'erreur et poursuit l'exécution de la commande. Contrairement à SilentlyContinue, la valeur Ignore n'ajoute pas le message d'erreur à la variable automatique $Error. La valeur Ignore a été introduite dans Windows PowerShell 3.0.
Inquire. Affiche le message d'erreur et demande votre confirmation avant de poursuivre l'exécution de la commande. Cette valeur est rarement utilisée.
SilentlyContinue. Supprime le message d'erreur et poursuit l'exécution de la commande.
Stop. Affiche le message d'erreur et arrête l'exécution de la commande.
Suspend. Cette valeur est disponible uniquement dans les workflows Windows PowerShell. Quand un workflow s'exécute et génère une erreur avec fin d'exécution, cette préférence d'action interrompt automatiquement la tâche en cours pour permettre une analyse plus approfondie. Après l'analyse, le workflow peut reprendre.
-ERRORVARIABLE [+]<VARIABLE-NAME>
Alias: ev
Stocke les messages d'erreur liés à la commande dans la variable spécifiée et dans la variable automatique $Error. Pour plus d'informations, tapez la commande suivante :
get-help about_Automatic_Variables
Par défaut, les nouveaux messages d'erreur remplacent les messages d'erreur qui sont déjà stockés dans la variable. Pour ajouter le message d'erreur au contenu de la variable, tapez un signe plus (+) avant le nom de la variable.
Par exemple, la commande suivante crée la variable $a pour y stocker les erreurs :
Get-Process -Id 6 -ErrorVariable a
La commande suivante ajoute les messages d'erreur à la variable $a :
Get-Process -Id 2 -ErrorVariable +a
La commande suivante affiche le contenu de la variable $a :
$a
Vous pouvez utiliser ce paramètre pour créer une variable qui contient uniquement les messages d'erreur générés par des commandes spécifiques. La variable automatique $Error contient les messages d'erreur de toutes les commandes exécutées dans la session. Vous pouvez utiliser la notation de tableau, par exemple $a[0] ou $error[1,2], pour faire référence à des erreurs spécifiques stockées dans les variables.
-OUTBUFFER <INT32>
Alias: ob
Détermine le nombre d'objets à atteindre dans une mémoire tampon avant d'envoyer des objets via le pipeline. Si vous omettez ce paramètre, les objets sont envoyés dès qu'ils sont générés.
Ce paramètre de gestion des ressources est destiné aux utilisateurs expérimentés. Si vous spécifiez ce paramètre, Windows PowerShell n'appelle pas l'applet de commande suivante dans le pipeline tant que le nombre d'objets générés n'a pas atteint la valeur OutBuffer + 1. Ensuite, elle envoie tous les objets qui sont générés.
-OUTVARIABLE [+]<VARIABLE-NAME>
Alias: ov
Stocke les objets de sortie de la commande dans la variable spécifiée et l'affiche sur la ligne de commande.
Pour ajouter la sortie à la variable, au lieu de remplacer toute sortie déjà stockée dans cette variable, tapez un signe plus (+) avant le nom de la variable.
Par exemple, la commande suivante crée la variable $out pour y stocker l'objet processus :
Get-Process PowerShell -OutVariable out
La commande suivante ajoute l'objet processus à la variable $out :
Get-Process iexplore -OutVariable +out
La commande suivante affiche le contenu de la variable $out :
$out
-PIPELINEVARIABLE <STRING>
Alias: pv
PipelineVariable stocke la valeur de l'élément de pipeline actuel en tant que variable, pour chaque commande nommée qui transite par le pipeline.
Les valeurs valides sont des chaînes, comme pour les autres noms de variables.
Voici un exemple du fonctionnement du paramètre PipelineVariable. Dans cet exemple, le paramètre PipelineVariable est ajouté à une commande Foreach-Object pour stocker les résultats de la commande dans des variables. Les nombres de 1 à 10 sont transmis à la première commande Foreach-Object, dont les résultats sont stockés dans une variable nommée Left.
Les résultats de la première commande Foreach-Object sont transmis à une deuxième commande Foreach-Object, qui filtre les objets retournés par la première commande Foreach-Object. Les résultats de la deuxième commande sont stockés dans une variable nommée Right.
Dans la troisième commande Foreach-Object, les résultats des deux premières commandes Foreach-Object redirigées, représentés par les variables Left et Right, sont traités à l'aide d'un opérateur de multiplication. La commande indique de multiplier les objets stockés dans les variables Left et Right, et d'afficher les résultats sous la forme « Membre de la plage Left * Membre de la plage Right = produit ».
1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
>> Foreach-Object -PV Right -Process { 1..10 } |
>> Foreach-Object -Process { "$Left * $Right = " + ($Left * $Right) }
>>
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
-VERBOSE[:{$TRUE | $FALSE}]
Alias: vb
Affiche des informations détaillées sur l'opération effectuée par la commande. Ces informations ressemblent aux informations fournies dans une trace ou un journal des transactions. Ce paramètre s'applique uniquement quand la commande génère un message commenté. Par exemple, ce paramètre s'applique quand une commande contient l'applet de commande Write-Verbose.
Le paramètre Verbose remplace la valeur de la variable $VerbosePreference pour la commande actuelle. Étant donné que la valeur par défaut de la variable $VerbosePreference est SilentlyContinue, les messages commentés ne sont pas affichés par défaut.
Valeurs valides :
$true (-Verbose:$true) has the same effect as -Verbose.
$false (-Verbose:$false) suppresses the display of verbose
messages. Use this parameter when the value of $VerbosePreference
is not SilentlyContinue (the default).
-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]
Alias: wa
Détermine comment l'applet de commande répond à un avertissement de la commande. « Continue » est la valeur par défaut. Ce paramètre s'applique uniquement quand la commande génère un message d'avertissement. Par exemple, ce paramètre s'applique quand une commande contient l'applet de commande Write-Warning.
Le paramètre WarningAction remplace la valeur de la variable $WarningPreference pour la commande actuelle. Étant donné que la valeur par défaut de la variable $WarningPreference est Continue, les avertissements sont affichés et l'exécution se poursuit, sauf si vous utilisez le paramètre WarningAction.
Valeurs valides :
Continue. Affiche le message d'avertissement et poursuit l'exécution de la commande. « Continue » est la valeur par défaut.
Inquire. Affiche le message d'avertissement et demande votre confirmation avant de poursuivre l'exécution de la commande. Cette valeur est rarement utilisée.
SilentlyContinue. Supprime le message d'avertissement et poursuit l'exécution de la commande.
Stop. Affiche le message d'avertissement et arrête l'exécution de la commande.
REMARQUE : Le paramètre WarningAction ne remplace pas la valeur de la variable de préférence $WarningAction quand le paramètre est utilisé dans une commande pour exécuter un script ou une fonction.
-WARNINGVARIABLE [+]<VARIABLE-NAME>
Alias: wv
Stocke les avertissements liés à la commande dans la variable spécifiée.
Tous les avertissements générés sont enregistrés dans la variable, même si les avertissements ne sont pas affichés à l'utilisateur.
Pour ajouter les avertissements au contenu de la variable, au lieu de remplacer les éventuels avertissements déjà stockés dans cette variable, tapez un signe plus (+) avant le nom de la variable.
Par exemple, la commande suivante crée la variable $a pour y stocker les avertissements :
Get-Process -Id 6 -WarningVariable a
La commande suivante ajoute les avertissements à la variable $a :
Get-Process -Id 2 -WarningVariable +a
La commande suivante affiche le contenu de la variable $a :
$a
Vous pouvez utiliser ce paramètre pour créer une variable qui contient uniquement les avertissements générés par des commandes spécifiques. Vous pouvez utiliser la notation de tableau, par exemple $a[0] ou $warning[1,2], pour faire référence à des avertissements spécifiques stockés dans la variable.
REMARQUE : Le paramètre WarningVariable ne capture pas les avertissements issus d'appels imbriqués dans des fonctions ou des scripts.
DESCRIPTION DES PARAMÈTRES D'ATTÉNUATION DES RISQUES
-WHATIF[:{$TRUE | $FALSE}]
Alias: wi
Affiche un message qui décrit l'effet de la commande, mais n'exécute pas la commande.
Le paramètre WhatIf remplace la valeur de la variable $WhatIfPreference pour la commande actuelle. Étant donné que la valeur par défaut de la variable $WhatIfPreference est 0 (désactivée), le comportement WhatIf n'est pas appliqué sans le paramètre WhatIf. Pour plus d'informations, tapez la commande suivante :
Get-Help about_Preference_Variables
Valeurs valides :
$true (-WhatIf:$true). Has the same effect as -WhatIf.
$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
that results when the value of the $WhatIfPreference variable
is 1.
Par exemple, la commande suivante utilise le paramètre WhatIf dans une commande Remove-Item :
PS> Remove-Item Date.csv -WhatIf
Au lieu de supprimer l'élément, Windows PowerShell répertorie quelles opérations seraient effectuées par cet élément et quels autres éléments seraient affectés par sa suppression. Cette commande génère la sortie suivante :
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-CONFIRM[:{$TRUE | $FALSE}]
Alias: cf
Vous invite à confirmer l'exécution de la commande.
Le paramètre Confirm remplace la valeur de la variable $ConfirmPreference pour la commande actuelle. La valeur par défaut est High. Pour plus d'informations, tapez la commande suivante :
Get-Help about_Preference_Variables
Valeurs valides :
$true (-Confirm:$true). Has the same effect as -Confirm.
$false(-Confirm:$false). Suppresses automatic confirmation,
which occurs when the value of $ConfirmPreference is less than
or equal to the estimated risk of the cmdlet.
Par exemple, la commande suivante utilise le paramètre Confirm dans une commande Remove-Item. Avant de supprimer l'élément, Windows PowerShell répertorie quelles opérations seraient effectuées par cet élément et quels autres éléments seraient affectés par sa suppression, et demande une confirmation.
PS C:\ps-test> Remove-Item tmp*.txt -Confirm
Cette commande génère la sortie suivante :
Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend
[?] Help (default is "Y"):
Les réponses possibles à la demande de confirmation sont les suivantes :
Yes (Y) Perform the action.
Yes to All (A) Perform all actions and suppress subsequent
Confirm queries for this command.
No (N): Do not perform the action.
No to All (L): Do not perform any actions and suppress subsequent
Confirm queries for this command.
Suspend (S): Pause the command and create a temporary session.
Help (?) Display help for these options.
L'option Suspend interrompt la commande, et crée une session imbriquée temporaire dans laquelle vous pouvez travailler jusqu'à ce que vous choisissiez une option de confirmation. L'invite de commandes pour la session imbriquée comporte deux signes >> supplémentaires pour indiquer qu'il s'agit d'une opération enfant de la commande parente initiale. Vous pouvez exécuter des commandes et des scripts dans la session imbriquée. Pour terminer la session imbriquée et revenir aux options de confirmation de la commande initiale, tapez « exit ».
Dans l'exemple suivant, l'option Suspend (S) interrompt une commande temporairement pendant que l'utilisateur consulte l'aide sur un paramètre de commande. Après avoir obtenu les informations nécessaires, l'utilisateur tape « exit » pour quitter l'invite de commandes imbriquée, puis il sélectionne la réponse Yes (y) pour confirmer la demande.
PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): s
PS C:\ps-test>>> Get-Help New-Item -Parameter ItemType
-ItemType <string>
Specifies the provider-specified type of the new item.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
PS C:\ps-test>>> exit
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt
MOTS CLÉS
about_Common_Parameters
VOIR AUSSI
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose