À propos de CommonParameters
DESCRIPTION COURTE
Décrit les paramètres qui peuvent être utilisés avec n’importe quelle applet de commande.
DESCRIPTION DÉTAILLÉE
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 paramètre commun Verbose 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 , ainsi que sur tous les workflows.
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 courants affectent uniquement les commandes dans lesquelles ils sont utilisés.
En plus des paramètres courants, de nombreuses applets de commande proposent les paramètres d’atténuation des risques WhatIf et Confirm . Les applets de commande qui impliquent un risque pour le système ou les données utilisateur offrent généralement ces paramètres.
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 d’atténuation des risques sont les suivants :
- WhatIf (wi)
- Confirmer (cf)
Pour plus d’informations, consultez about_Preference_Variables.
DESCRIPTIONS DES PARAMÈTRES COURANTS
Débogage
L’alias de Debug est db.
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 .
Le paramètre Debug remplace la valeur de la $DebugPreference variable pour la commande actuelle, en définissant la valeur sur $DebugPreferenceContinuer. Étant donné que la valeur par défaut de la $DebugPreference variable est SilentlyContinue, les messages de débogage ne sont pas affichés par défaut.
-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 SilentlyContinue, ce qui est la valeur par défaut.
ErrorAction
L’alias de ErrorAction est ea.
Détermine comment l’applet de commande répond à une erreur sans fin de la commande.
Ce paramètre fonctionne uniquement lorsque la commande génère une erreur sans fin, telle que celles de l’applet Write-Error de commande.
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 l’arrêt des erreurs (telles que des données manquantes, des paramètres non valides ou des autorisations insuffisantes) qui empêchent la réussite d’une commande.
-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 l’exécution de la commande. Contrairement à SilentlyContinue, Ignore n’ajoute pas le message d’erreur à la $Error variable automatique. La valeur Ignore 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 l’exécution de la commande.
-ErrorAction:Stop affiche le message d’erreur et arrête l’exécution de la commande.
-ErrorAction:Suspend n’est pas pris en charge sur PowerShell Core, car il est uniquement disponible pour les flux de travail.
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
L’alias de ErrorVariable est ev.
ErrorVariable stocke les messages d’erreur relatifs à la commande dans la variable spécifiée et dans la $Error variable automatique. 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 $a variable, puis y stocke les erreurs éventuelles :
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. La $Error variable automatique contient des messages d’erreur de toutes les commandes de la session. Vous pouvez utiliser la notation matricielle, telle que $a[0] ou $error[1,2] pour faire référence à des erreurs spécifiques stockées dans les variables.
InformationAction
L’alias d’InformationAction est ia.
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.
-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 l’exécution de la commande. Contrairement à SilentlyContinue, Ignore oublie complètement le message d’information ; elle 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 de s’exécuter.
-InformationAction:Suspend n’est pas pris en charge sur PowerShell Core, 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
L’alias de InformationVariable est iv.
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 sont affichées en fonction de la valeur de la $InformationPreference variable de préférence. Pour plus d’informations sur $InformationPreference, consultez about_Preference_Variables.
OutBuffer
L’alias de OutBuffer est ob et prend une valeur System.Int32 .
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.
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 par 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
L’alias de OutVariable est ov.
Stocke les objets de sortie de la commande dans la variable spécifiée en plus d’envoyer la sortie le long du pipeline.
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
L’alias de PipelineVariable est pv et prend une valeur de chaîne .
PipelineVariable stocke la valeur de l’élément de pipeline actuel sous la forme d’une variable, pour toute commande nommée à mesure qu’elle transite par le pipeline.
Les valeurs valides sont des chaînes, les mêmes que pour les noms de variables.
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 à 10, est redirigée vers la première Foreach-Object commande, dont les résultats sont stockés dans une variable nommée Left.
Les résultats de la première Foreach-Object commande sont dirigés vers une deuxième Foreach-Object commande, qui filtre les objets retournés par la première Foreach-Object commande. Les résultats de la deuxième commande sont stockés dans une variable nommée Right.
Dans la troisième Foreach-Object commande, les résultats des deux Foreach-Object premières commandes canalées, représentées par les variables Gauche et Droite, sont traités à l’aide d’un opérateur de multiplication. La commande indique aux objets stockés dans les variables Gauche et Droite d’être multipliés, et spécifie que les résultats doivent être affichés comme « Membre de la plage gauche * Membre de la plage droite = product ».
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
...
Commentaires
L’alias pour Verbose est vb.
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.
Le paramètre Verbose 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
L’alias de WarningAction est wa.
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.
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: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
L’alias de WarningVariable est wv.
Stocke les avertissements concernant 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 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
Le paramètre WarningVariable ne capture pas les avertissements des appels imbriqués dans des fonctions ou des scripts.
Descriptions des paramètres de gestion des risques
WhatIf
Alias de WhatIf is wi.
Affiche un message qui décrit l’effet de la commande, au lieu d’exécuter la commande.
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, tapez la commande suivante :
Get-Help 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".
Confirmer
L’alias de Confirm est cf.
Demande une confirmation avant d'exécuter la commande.
Le paramètre Confirm remplace la valeur de la $ConfirmPreference variable pour la commande actuelle. La valeur par défaut est true. Pour plus d’informations, tapez la commande suivante :
Get-Help 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 paramètre Confirm 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 options confirmer la réponse sont les suivantes :
| response | Résultats |
|---|---|
| Oui (Y) | Effectuez l’action. |
| Oui à tous (A) | Effectuer toutes les actions et supprimer les requêtes confirm suivantes |
| pour cette commande. | |
| Non (N) : | N’effectuez pas l’action. |
| Non à tous (L) : | N’effectuez aucune action et supprimez la confirmation suivante |
| requêtes pour cette commande. | |
| Suspendre (S) : | Suspendez la commande et créez une session temporaire. |
| Aide ( ?) | Affichez de 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 option Confirmer . 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 options Confirmer pour 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 requête Confirmer.
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