RUBRIQUE
about_CommonParameters
DESCRIPTION COURTE
Décrit les paramètres qui peuvent être utilisés avec n'importe
quelle applet de commande.
DESCRIPTION LONGUE
Les paramètres courants correspondent à un jeu de paramètres
d'applet de commande que vous pouvez utiliser avec n'importe
quelle applet de commande. Implémentés par Windows PowerShell,
et non par le développeur de l'applet de commande, ils sont
automatiquement disponibles pour toute applet de commande.
Vous pouvez utiliser les paramètres courants avec n'importe
quelle applet de commande, mais ils peuvent ne pas avoir d'effet
sur toutes les applets. Par exemple, si une applet de commande
ne génère pas de sortie détaillée, l'utilisation du paramètre
courant Verbose n'a pas d'effet.
Plusieurs paramètres courants remplacent les valeurs par défaut
du système 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 courants affectent
uniquement les commandes dans lesquelles ils sont utilisés.
En plus des paramètres courants, de nombreuses applets de
commande offrent les paramètres d'atténuation des risques WhatIf
et Confirm. Les applets de commande qui présentent un risque pour
le système ou les données des utilisateurs proposent généralement
ces paramètres.
Les paramètres courants sont :
-Verbose
-Debug
-WarningAction
-WarningVariable
-ErrorAction
-ErrorVariable
-OutVariable
-OutBuffer
Les paramètres d'atténuation des risques sont les suivants :
-WhatIf
-Confirm
Pour plus d'informations sur les variables de préférence, tapez :
help about_preference_variables
Description des paramètres courants
-Verbose[:{$true | $false}]
Affiche des informations détaillées sur l'opération exécutée
par la commande. Ces informations sont semblables à celles
d'une trace ou d'un journal des transactions. Ce paramètre
n'a d'effet que si la commande génère un message commenté.
Par exemple, ce paramètre fonctionne lorsqu'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 s'affichent
pas par défaut.
Valeurs valides :
$true (-Verbose:$true) a le même effet que -Verbose.
$false (-Verbose:$false) supprime l'affichage des
messages commentés. Utilisez ce paramètre lorsque la valeur de
$VerbosePreference n'est pas SilentlyContinue (valeur par défaut).
-Debug[:{$true | $false}]
Affiche les informations de programmation relatives à l'opération
exécutée par la commande. Ce paramètre n'a d'effet que si la commande
génère un message de débogage. Par exemple, ce paramètre fonctionne
lorsqu'une commande contient l'applet de commande Write-Debug.
Le paramètre Debug remplace la valeur de la variable
$DebugPreference pour la commande actuelle. Étant donné que
la valeur par défaut de la variable $DebugPreference est
SilentlyContinue, les messages de débogage ne s'affichent pas par défaut.
Valeurs valides :
$true (-Debug:$true). A le même effet que -Debug.
$false (-Debug:$false). Supprime l'affichage des messages de
débogage lorsque la valeur de la variable $DebugPreference n'est pas
SilentlyContinue (valeur par défaut).
-WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]
Détermine comment l'applet de commande répond à un
avertissement de la commande. La valeur par défaut est
" Continue ". Ce paramètre n'a d'effet que si la commande
génère un message d'avertissement. Par exemple, ce paramètre
fonctionne lorsqu'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 s'affichent et l'exécution continue à moins que
vous n'utilisiez le paramètre WarningAction.
Valeurs valides :
SilentlyContinue. Supprime le message d'avertissement et
continue à exécuter la commande.
Continue. Affiche le message d'avertissement et continue
à exécuter la commande. La valeur par défaut est " Continue ".
Inquire. Affiche le message d'avertissement et vous invite à
confirmer la poursuite de l'exécution. Cette valeur est rarement
utilisée.
Stop. Affiche le message d'avertissement et arrête
l'exécution de la commande.
-WarningVariable [+]<nom de variable>
Stocke des avertissements relatifs à la commande dans la variable
spécifiée.
Pour ajouter les avertissements au contenu de la variable, au
lieu de remplacer les avertissements qui peuvent déjà être
stockés dans cette dernière, tapez un signe plus (+) avant le
nom de la variable.
Par exemple, la commande suivante crée la variable $a, puis
stocke dans cette dernière tous les avertissements :
get-process -id 6 -WarningVariable a
La commande suivante ajoute tous 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
contenant uniquement les avertissements de commandes
spécifiques. Vous pouvez utiliser la notation sous forme de
tableau, telle que $a[0] ou $warning[1,2], pour faire
référence à des avertissements spécifiques qui sont stockés
dans la variable.
-ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]
Détermine comment l'applet de commande répond à une erreur
sans fin d'exécution de la commande. Ce paramètre n'a d'effet
que si la commande génère un message de débogage. Par exemple,
ce paramètre fonctionne lorsqu'une commande contient 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 s'affichent et l'exécution continue
à moins que vous n'utilisiez le paramètre ErrorAction.
Le paramètre ErrorAction n'a aucun effet sur les erreurs avec fin
d'exécution (telles que des données manquantes, des paramètres non
valides ou des autorisations insuffisantes) qui empêchent une
commande de réussir.
Valeurs valides :
SilentlyContinue. Supprime le message d'erreur et continue à
exécuter la commande.
Continue. Affiche le message d'erreur et continue à
exécuter la commande. La valeur par défaut est " Continue ".
Inquire. Affiche le message d'erreur et vous invite à
confirmer la poursuite de l'exécution. Cette valeur est
rarement utilisée.
Stop. Affiche le message d'erreur et arrête l'exécution de la
commande.
-ErrorVariable [+]<nom de variable>
Stocke les messages d'erreur relatifs à 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 ceux
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 variable.
Par exemple, la commande suivante crée la variable $a, puis
stocke dans cette dernière toutes les erreurs :
get-process -id 6 -ErrorVariable a
La commande suivante ajoute tous 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
contenant uniquement les messages d'erreur de commandes
spécifiques. La variable automatique $Error contient des messages
d'erreur de toutes les commandes utilisées dans la session.
Vous pouvez utiliser la notation sous forme de tableau, telle
que $a[0] ou $error[1,2], pour faire référence à des erreurs
spécifiques qui sont stockées dans les variables.
-OutVariable [+]<nom de variable>
Stocke les objets de sortie de la commande dans la variable
spécifiée et affiche cette dernière à la ligne de commande.
Pour ajouter la sortie à la variable, au lieu de remplacer
les sorties qui peuvent déjà être stockées dans cette
dernière, tapez un signe plus (+) avant le nom de la variable.
Par exemple, la commande suivante crée la variable $out et
stocke dans cette dernière 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
-OutBuffer <Int32>
Détermine le nombre d'objets devant être accumulés dans une
mémoire tampon avant qu'un des objets ne soit envoyé à travers
le pipeline. Si vous omettez ce paramètre, les objets sont
envoyés à mesure qu'ils sont générés.
Ce paramètre de gestion des ressources est conçu pour les
utilisateurs expérimentés.
Lorsque vous utilisez ce paramètre, Windows PowerShell
n'appelle pas l'applet de commande suivante du pipeline tant
que le nombre d'objets générés n'est pas égal à OutBuffer + 1.
Il envoie ensuite tous les objets à mesure qu'ils sont générés.
Description des paramètres de gestion des risques
-WhatIf[:{$true | $false}]
Affiche un message décrivant l'effet de la commande, au lieu
d'exécuter cette dernière.
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é), le comportement du paramètre WhatIf n'est pas
mise en œuvre sans le paramètre WhatIf. Pour plus
d'informations, tapez la commande suivante :
get-help about_preference_variables
Valeurs valides :
$true (-WhatIf:$true). A le même effet que -WhatIf.
$false (-WhatIf:$false). Annule le comportement automatique
du paramètre WhatIf généré lorsque la valeur de la variable
$WhatIfPreference est 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 les
opérations pouvant être exécutées et les éléments susceptibles d'être
affectés. Cette commande produit la sortie suivante :
What if : Opération " Supprimer le fichier " en cours sur
la cible " C:\ps-test\date.csv ".
-Confirm[:{$true | $false}]
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 (-WhatIf:$true). A le même effet que -Confirm.
$false(-Confirm:$false). Annule la confirmation
automatique, qui se produit lorsque la valeur de la variable
$ConfirmPreference est inférieure ou égale au risque estimé de
l'applet de commande.
Par exemple, la commande ci-dessous utilise le paramètre
Confirm avec une commande Remove-Item. Avant de supprimer
l'élément, Windows PowerShell répertorie les opérations
pouvant être exécutées et les éléments susceptibles d'être
affectés, puis demande l'approbation.
PS C:\ps-test> remove-item tmp*.txt -confirm
Cette commande produit la sortie suivante :
Confirmer
Êtes-vous sûr de vouloir effectuer cette action ?
Opération " Supprimer le fichier " en cours sur la cible
" C:\ps-test\tmp1.txt " [O] Oui [T] Oui pour tout [N] Non
[U] Non pour tout [S] Suspendre [?] Aide (la valeur par
défaut est " O "):
VOIR AUSSI
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose