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 sont un ensemble de paramètres d’applet de commande que vous pouvez utiliser avec n’importe quelle applet de commande. Elles sont implémentées par PowerShell, et non par le développeur d’applets de commande, et elles sont automatiquement disponibles pour n’importe quelle applet de commande.
Vous pouvez utiliser les paramètres communs avec n’importe quelle applet de commande, mais ils peuvent ne pas avoir d’effet sur toutes les applets de commande. Par exemple, si une applet de commande ne génère aucune sortie détaillée, l’utilisation du Verbose paramètre commun n’a aucun effet.
Les paramètres communs sont également disponibles sur les fonctions avancées qui utilisent l’attribut CmdletBinding ou l’attribut Parameter .
Plusieurs paramètres courants remplacent les paramètres système par défaut ou les préférences que vous définissez à l’aide des variables de préférence PowerShell. Contrairement aux variables de préférence, les paramètres communs affectent uniquement les commandes dans lesquelles ils sont utilisés.
Pour plus d’informations, consultez about_Preference_Variables.
La liste suivante affiche les paramètres courants. Leurs alias sont répertoriés entre parenthèses.
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Verbose (vb)
- WarningAction (wa)
- WarningVariable (wv)
Les paramètres Action sont des valeurs de type ActionPreference . ActionPreference est une énumération avec les valeurs suivantes :
Nom | Valeur |
---|---|
Break |
6 |
Suspend |
5 |
Ignore |
4 |
Inquire |
3 |
Continue |
2 |
Stop |
1 |
SilentlyContinue |
0 |
Vous pouvez utiliser le nom ou la valeur avec le paramètre .
En plus des paramètres communs, de nombreuses applets de commande offrent des paramètres d’atténuation des risques. Les applets de commande qui impliquent un risque pour le système ou pour les données utilisateur offrent généralement ces paramètres.
Les paramètres d’atténuation des risques sont les suivants :
- WhatIf (wi)
- Confirm (cf)
Descriptions de paramètres courants
-Debug
Affiche des détails au niveau du programmeur sur l’opération effectuée par la commande. Ce paramètre fonctionne uniquement lorsque la commande génère un message de débogage. Par exemple, ce paramètre fonctionne lorsqu’une commande contient l’applet de Write-Debug
commande.
Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Par défaut, le débogage des messages ne s’affiche pas, car la valeur de la $DebugPreference
variable est SilentlyContinue.
En mode interactif, le Debug paramètre remplace la valeur de la $DebugPreference
variable pour la commande actuelle, en définissant la valeur de $DebugPreference
sur Inquire.
En mode non interactif, le Debug paramètre remplace la valeur de la variable pour la $DebugPreference
commande actuelle, en définissant la valeur de $DebugPreference
sur Continuer.
-Debug:$true
a le même effet que -Debug
. Permet -Debug:$false
de supprimer l’affichage des messages de débogage lorsque $DebugPreference
n’est pas SilencieuxContinue, ce qui est la valeur par défaut.
-ErrorAction
Détermine la façon dont l’applet de commande répond à une erreur de non-fin de la commande.
Ce paramètre fonctionne uniquement lorsque la commande génère une erreur de non-fin, telle que celle de l’applet Write-Error
de commande.
Type: ActionPreference
Aliases: ea
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Le paramètre ErrorAction remplace la valeur de la $ErrorActionPreference
variable pour la commande actuelle. Étant donné que la valeur par défaut de la $ErrorActionPreference
variable est Continue, les messages d’erreur s’affichent et l’exécution continue, sauf si vous utilisez le paramètre ErrorAction .
Le paramètre ErrorAction n’a aucun effet sur la fin des erreurs (telles que les données manquantes, les paramètres non valides ou les autorisations insuffisantes) qui empêchent une commande de se terminer correctement.
-ErrorAction:Break
Entre le débogueur lorsqu’une erreur se produit ou qu’une exception est levée.
-ErrorAction:Continue
affiche le message d’erreur et continue l’exécution de la commande. Continue
est la valeur par défaut.
-ErrorAction:Ignore
supprime le message d’erreur et continue d’exécuter la commande. Contrairement à SilentlyContinue, Ignore n’ajoute pas le message d’erreur à la $Error
variable automatique. La valeur Ignorer est introduite dans PowerShell 3.0.
-ErrorAction:Inquire
affiche le message d’erreur et vous invite à confirmer avant de poursuivre l’exécution. Cette valeur est rarement utilisée.
-ErrorAction:SilentlyContinue
supprime le message d’erreur et continue d’exécuter la commande.
-ErrorAction:Stop
affiche le message d’erreur et arrête l’exécution de la commande.
-ErrorAction:Suspend
n’est disponible que pour les workflows qui ne sont pas pris en charge dans PowerShell 6 et au-delà.
Notes
Le paramètre ErrorAction remplace, mais ne remplace pas la valeur de la $ErrorAction
variable de préférence lorsque le paramètre est utilisé dans une commande pour exécuter un script ou une fonction.
-ErrorVariable
ErrorVariable stocke les messages d’erreur concernant la commande dans la variable spécifiée et dans la $Error
variable automatique. Pour plus d’informations, consultez about_Automatic_Variables.
Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
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 $a
variable, puis y stocke les erreurs :
Get-Process -Id 6 -ErrorVariable a
La commande suivante ajoute tous les messages d’erreur à la $a
variable :
Get-Process -Id 2 -ErrorVariable +a
La commande suivante affiche le contenu de $a
:
$a
Vous pouvez utiliser ce paramètre pour créer une variable qui contient uniquement des messages d’erreur provenant de commandes spécifiques et qui n’affecte pas le comportement de la $Error
variable automatique. La $Error
variable automatique contient les messages d’erreur de toutes les commandes de la session. Vous pouvez utiliser la notation de tableau, par $a[0]
exemple ou $error[1,2]
pour faire référence à des erreurs spécifiques stockées dans les variables.
Notes
La variable d’erreur personnalisée contient toutes les erreurs générées par la commande, y compris les erreurs d’appels à des fonctions ou des scripts imbriqués.
-InformationAction
Introduit dans PowerShell 5.0. Dans la commande ou le script dans lequel il est utilisé, le paramètre commun InformationAction remplace la valeur de la $InformationPreference
variable de préférence, qui est définie par défaut sur SilentlyContinue. Lorsque vous utilisez Write-Information
dans un script avec InformationAction, Write-Information
les valeurs sont affichées en fonction de la valeur du paramètre InformationAction . Pour plus d’informations sur $InformationPreference
, consultez about_Preference_Variables.
Type: ActionPreference
Aliases: ia
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
-InformationAction:Break
Entre le débogueur à une occurrence de la Write-Information
commande.
-InformationAction:Stop
arrête une commande ou un script à une occurrence de la Write-Information
commande.
-InformationAction:Ignore
supprime le message d’information et continue à exécuter la commande. Contrairement à SilentlyContinue, Ignore oublie complètement le message d’information ; il n’ajoute pas le message d’information au flux d’informations.
-InformationAction:Inquire
affiche le message d’information que vous spécifiez dans une Write-Information
commande, puis vous demande si vous souhaitez continuer.
-InformationAction:Continue
affiche le message d’information et continue à s’exécuter.
-InformationAction:Suspend
n’est pas pris en charge sur PowerShell 6 et versions ultérieures, car il est uniquement disponible pour les flux de travail.
-InformationAction:SilentlyContinue
aucun effet, car le message d’information n’est pas affiché (par défaut) et le script continue sans interruption.
Notes
Le paramètre InformationAction remplace, mais ne remplace pas la valeur de la $InformationAction
variable de préférence lorsque le paramètre est utilisé dans une commande pour exécuter un script ou une fonction.
-InformationVariable
Introduit dans PowerShell 5.0. Dans la commande ou le script dans lequel il est utilisé, le paramètre commun InformationVariable stocke dans une variable une chaîne que vous spécifiez en ajoutant la Write-Information
commande. Write-Information
les valeurs sont affichées en fonction de la valeur du paramètre commun InformationAction ; si vous n’ajoutez pas le paramètre commun InformationAction , Write-Information
les chaînes s’affichent en fonction de la valeur de la $InformationPreference
variable de préférence. Pour plus d’informations sur $InformationPreference
, consultez about_Preference_Variables.
Notes
La variable d’informations contient tous les messages d’informations générés par la commande, y compris les messages d’informations provenant d’appels à des fonctions ou scripts imbriqués.
Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutBuffer
Détermine le nombre d’objets à accumuler dans une mémoire tampon avant l’envoi d’objets via le pipeline. Si vous omettez ce paramètre, les objets sont envoyés au fur et à mesure qu’ils sont générés.
Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Ce paramètre de gestion des ressources est conçu pour les utilisateurs avancés. Lorsque vous utilisez ce paramètre, PowerShell envoie des données à l’applet de commande suivante dans les lots de OutBuffer + 1
.
L’exemple d’alternative suivant s’affiche entre les blocs de ForEach-Object
traitement qui utilisent l’applet de Write-Host
commande. L’affichage alterne dans les lots de 2 ou OutBuffer + 1
.
1..4 | ForEach-Object {
Write-Host "$($_): First"; $_
} -OutBuffer 1 | ForEach-Object {
Write-Host "$($_): Second" }
1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second
-OutVariable
Stocke les objets de sortie de la commande dans la variable spécifiée en plus d’envoyer la sortie le long du pipeline.
Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Pour ajouter la sortie à la variable, au lieu de remplacer toute sortie qui peut y être déjà stockée, tapez un signe plus (+
) avant le nom de la variable.
Par exemple, la commande suivante crée la $out
variable et y stocke l’objet de processus :
Get-Process PowerShell -OutVariable out
La commande suivante ajoute l’objet process à la $out
variable :
Get-Process iexplore -OutVariable +out
La commande suivante affiche le contenu de la $out
variable :
$out
Notes
La variable créée par le paramètre OutVariable est un [System.Collections.ArrayList]
.
-PipelineVariable
PipelineVariable permet d’accéder à la valeur la plus récente passée au segment de pipeline suivant par la commande qui utilise ce paramètre. N’importe quelle commande du pipeline peut accéder à la valeur à l’aide du pipelineVariable nommé. La valeur est affectée à la variable lorsqu’elle est passée dans le segment de pipeline suivant. Cela facilite l’utilisation de PipelineVariable par rapport à une variable temporaire spécifique, qui peut avoir besoin d’être affectée à plusieurs emplacements.
Contrairement à $_
ou $PSItem
, l’utilisation d’un pipelineVariable permet à n’importe quelle commande de pipeline d’accéder aux valeurs de pipeline passées (et enregistrées) par des commandes autres que la commande immédiatement précédente. Les commandes de pipeline peuvent accéder à la dernière valeur canalée à partir de lors du traitement de l’élément suivant passant par le pipeline. Cela permet à une commande de renvoyer sa sortie à une commande précédente (ou elle-même).
Notes
Les fonctions avancées peuvent avoir jusqu’à trois blocs de script : begin
, process
et end
. Lorsque vous utilisez le paramètre PipelineVariable avec des fonctions avancées, seules les valeurs du premier bloc de script défini sont affectées à la variable pendant l’exécution de la fonction. Pour plus d’informations, consultez Fonctions avancées. PowerShell 7.2 corrige ce comportement.
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Les valeurs valides sont des chaînes, les mêmes que pour les noms de variables.
Attention
PipelineVariable est limité au pipeline dans lequel il est appelé. Les variables extérieures au pipeline, qui utilisent le même nom, sont supprimées avant l’exécution du pipeline. PipelineVariable sort de l’étendue lorsque le pipeline se termine. Si plusieurs commandes dans le pipeline spécifient le même PipelineVariable, il n’y a qu’une seule variable partagée. Cette variable est mise à jour avec la sortie canalée la plus récente de la commande qui spécifie la variable.
Certaines commandes de blocage collectent tous les éléments de pipeline avant de produire une sortie, par exemple Sort-Object
ou Select-Object -Last
. Tout PipelineVariable affecté dans une commande avant une telle commande de blocage contient toujours l’élément canalé final de la commande précédente lorsqu’il est utilisé dans une commande après la commande bloquante.
Voici un exemple de fonctionnement de PipelineVariable . Dans cet exemple, le paramètre PipelineVariable est ajouté à une Foreach-Object
commande pour stocker les résultats de la commande dans des variables. Une plage de nombres, 1 à 5, est redirigée vers la première Foreach-Object
commande, dont les résultats sont stockés dans une variable nommée $temp
.
Les résultats de la première Foreach-Object
commande sont dirigés vers une deuxième Foreach-Object
commande, qui affiche les valeurs actuelles de $temp
et $_
.
# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created is not available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
Write-Output $_
} | ForEach-Object {
Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp
Name Value
---- -----
temp 8
Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
Step2[PROCESS]:$temp=5 - $_=5
Get-Variable: Cannot find a variable with the name 'temp'.
-Verbose
Affiche des informations détaillées sur l’opération effectuée par la commande. Ces informations ressemblent aux informations d’une trace ou d’un journal des transactions. Ce paramètre fonctionne uniquement lorsque la commande génère un message détaillé. Par exemple, ce paramètre fonctionne lorsqu’une commande contient l’applet de Write-Verbose
commande.
Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Le Verbose paramètre remplace la valeur de la $VerbosePreference
variable pour la commande actuelle. Étant donné que la valeur par défaut de la $VerbosePreference
variable est SilentlyContinue, les messages détaillés ne sont pas affichés par défaut.
-Verbose:$true
a le même effet que -Verbose
-Verbose:$false
supprime l’affichage des messages détaillés. Utilisez ce paramètre lorsque la valeur de $VerbosePreference
n’est pas SilentlyContinue (valeur par défaut).
-WarningAction
Détermine la façon dont l’applet de commande répond à un avertissement de la commande . Continue est la valeur par défaut. Ce paramètre fonctionne uniquement lorsque la commande génère un message d’avertissement. Par exemple, ce paramètre fonctionne lorsqu’une commande contient l’applet de Write-Warning
commande.
Type: ActionPreference
Aliases: wa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Le paramètre WarningAction remplace la valeur de la $WarningPreference
variable pour la commande actuelle. Étant donné que la valeur par défaut de la $WarningPreference
variable est Continue, les avertissements s’affichent et l’exécution continue, sauf si vous utilisez le paramètre WarningAction .
-WarningAction:Break
entre dans le débogueur lorsqu’un avertissement se produit.
-WarningAction:Continue
affiche les messages d’avertissement et continue l’exécution de la commande. Continue
est la valeur par défaut.
-WarningAction:Inquire
affiche le message d’avertissement et vous invite à confirmer avant de poursuivre l’exécution. Cette valeur est rarement utilisée.
-WarningAction:SilentlyContinue
supprime le message d’avertissement et continue l’exécution de la commande.
-WarningAction:Stop
affiche le message d’avertissement et arrête l’exécution de la commande.
Notes
Le paramètre WarningAction remplace, mais ne remplace pas la valeur de la $WarningAction
variable de préférence lorsque le paramètre est utilisé dans une commande pour exécuter un script ou une fonction.
-WarningVariable
Stocke les avertissements concernant la commande dans la variable spécifiée.
Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
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 avertissements qui peuvent déjà y être stockés, tapez un signe plus (+
) avant le nom de la variable.
Par exemple, la commande suivante crée la $a
variable, puis y stocke les avertissements :
Get-Process -Id 6 -WarningVariable a
La commande suivante ajoute des avertissements à la $a
variable :
Get-Process -Id 2 -WarningVariable +a
La commande suivante affiche le contenu de $a
:
$a
Vous pouvez utiliser ce paramètre pour créer une variable qui contient uniquement des avertissements provenant de commandes spécifiques. Vous pouvez utiliser la notation de tableau, par $a[0]
exemple ou $warning[1,2]
pour faire référence à des avertissements spécifiques stockés dans la variable.
Notes
La variable d’avertissement contient tous les avertissements générés par la commande, y compris les avertissements provenant d’appels à des fonctions ou des scripts imbriqués.
Descriptions des paramètres de gestion des risques
-WhatIf
Affiche un message qui décrit l’effet de la commande, au lieu d’exécuter la commande.
Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Le paramètre WhatIf remplace la valeur de la $WhatIfPreference
variable pour la commande actuelle. Étant donné que la valeur par défaut de la $WhatIfPreference
variable est 0 (désactivée), le comportement de WhatIf n’est pas effectué sans le paramètre WhatIf . Pour plus d’informations, consultez about_Preference_Variables
-WhatIf:$true
a le même effet que -WhatIf
.
-WhatIf:$false
supprime le comportement WhatIf automatique qui se produit lorsque la valeur de la $WhatIfPreference
variable est 1.
Par exemple, la commande suivante utilise le -WhatIf
paramètre dans une Remove-Item
commande :
Remove-Item Date.csv -WhatIf
Au lieu de supprimer l’élément, PowerShell répertorie les opérations qu’il effectuerait et les éléments qui seraient affectés. Cette commande génère la sortie suivante :
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-Confirm
Demande une confirmation avant d'exécuter la commande.
Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Le Confirm paramètre remplace la valeur de la $ConfirmPreference
variable pour la commande actuelle. La valeur par défaut est true. Pour plus d’informations, consultez about_Preference_Variables
-Confirm:$true
a le même effet que -Confirm
.
-Confirm:$false
supprime la confirmation automatique, qui se produit lorsque la valeur de $ConfirmPreference
est inférieure ou égale au risque estimé de l’applet de commande.
Par exemple, la commande suivante utilise le Confirm paramètre avec une Remove-Item
commande . Avant de supprimer l’élément, PowerShell répertorie les opérations qu’il effectuerait et les éléments qui seraient affectés, et demande l’approbation.
PS C:\ps-test> Remove-Item tmp*.txt -Confirm
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 Confirm options de réponse sont les suivantes :
response | Résultats |
---|---|
Yes (Y ) |
Effectuez l’action. |
Yes to All (A ) |
Effectuer toutes les actions et supprimer les requêtes suivantes Confirm |
pour cette commande. | |
No (N ): |
N’effectuez pas l’action. |
No to All (L ): |
N’effectuez aucune action et supprimez les actions suivantes Confirm |
requêtes pour cette commande. | |
Suspend (S ): |
Suspendez la commande et créez une session temporaire. |
Help (? ) |
Affichez l’aide pour ces options. |
L’option Suspendre met la commande en attente et crée une session imbriquée temporaire dans laquelle vous pouvez travailler jusqu’à ce que vous soyez prêt à choisir une Confirm option. L’invite de commandes de la session imbriquée a deux avertissements supplémentaires (>>) pour indiquer qu’il s’agit d’une opération enfant de la commande parente d’origine. Vous pouvez exécuter des commandes et des scripts dans la session imbriquée. Pour mettre fin à la session imbriquée et revenir aux Confirm options de la commande d’origine, tapez « exit ».
Dans l’exemple suivant, l’option Suspendre (S) est utilisée pour arrêter temporairement une commande pendant que l’utilisateur recherche un paramètre de commande dans l’aide. Après avoir obtenu les informations nécessaires, l’utilisateur tape « exit » pour mettre fin à l’invite imbriquée, puis sélectionne la réponse Oui (y) à la Confirm requête.
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 (defau
lt 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