Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier les répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer de répertoire.
Les instructions suivantes doivent être suivies lorsque vous écrivez vos applets de commande. Ils sont séparés en instructions pour concevoir des applets de commande et des instructions pour écrire votre code d’applet de commande. Si vous ne suivez pas ces instructions, vos applets de commande peuvent échouer et vos utilisateurs peuvent avoir une mauvaise expérience lorsqu’ils utilisent vos applets de commande.
Dans cette rubrique
Recommandations en matière de conception
noms d’applets de commande : caractères qui ne peuvent pas être utilisés (RD02)
paramètre de force de support pour les sessions interactives (RD05)
Recommandations en matière de code
Dériver de l’applet de commande ou des classes PSCmdlet (RC01)
ne pas conserver les handles dans les objets de sortie (RC05)
utiliser un module Windows PowerShell pour déployer vos applets de commande (RC07)
Recommandations en matière de conception
Les instructions suivantes doivent être suivies lors de la conception d’applets de commande pour garantir une expérience utilisateur cohérente entre l’utilisation de vos applets de commande et d’autres applets de commande. Lorsque vous trouvez une directive de conception qui s’applique à votre situation, veillez à consulter les instructions de code pour obtenir des instructions similaires.
Utiliser uniquement des verbes approuvés (RD01)
Le verbe spécifié dans l’attribut Cmdlet doit provenir de l’ensemble reconnu de verbes fournis par Windows PowerShell. Il ne doit pas s’agir de l’un des synonymes interdits. Utilisez les chaînes constantes définies par les énumérations suivantes pour spécifier des verbes d’applet de commande :
Pour plus d’informations sur les noms de verbes approuvés, consultez verbes d’applet de commande.
Les utilisateurs ont besoin d’un ensemble de noms d’applets de commande détectables et attendus. Utilisez le verbe approprié afin que l’utilisateur puisse effectuer une évaluation rapide de ce qu’une applet de commande fait et pour découvrir facilement les fonctionnalités du système. Par exemple, la commande de ligne de commande suivante obtient une liste de toutes les commandes du système dont les noms commencent par « Démarrer » : Get-Command Start-*. Utilisez les noms dans vos applets de commande pour différencier vos applets de commande d’autres applets de commande. Le nom indique la ressource sur laquelle l’opération sera effectuée. L’opération elle-même est représentée par le verbe.
Noms d’applet de commande : caractères qui ne peuvent pas être utilisés (RD02)
Lorsque vous nommez des applets de commande, n’utilisez aucun des caractères spéciaux suivants.
| Caractère | Nom |
|---|---|
| # | signe numérique |
| , | virgule |
| () | parenthèses |
| {} | bretelles |
| [] | crochets |
| & | et commercial |
| - | trait d’union Remarque : Le trait d’union peut être utilisé pour séparer le verbe du nom, mais il ne peut pas être utilisé dans le nom ou dans le verbe. |
| / | barre oblique |
| \ | barre oblique inverse |
| $ | signe dollar |
| ^ | caret |
| ; | point-virgule |
| : | côlon |
| "" | guillemets doubles |
| ' | guillemets simples |
| <> | Équerres |
| | | barre verticale |
| ? | point d’interrogation |
| @ | arobase |
| ` | graduation de dos (accent grave) |
| * | astérisque |
| % | Signe de pourcentage |
| + | signe plus |
| = | signe égal |
| ~ | tilde |
Noms de paramètres qui ne peuvent pas être utilisés (RD03)
Windows PowerShell fournit un ensemble commun de paramètres pour toutes les applets de commande, ainsi que d’autres paramètres ajoutés dans des situations spécifiques. Lorsque vous concevez vos propres applets de commande, vous ne pouvez pas utiliser les noms suivants : Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction et Verbose. Pour plus d’informations sur ces paramètres, consultez noms de paramètres communs.
Demandes de confirmation de support (RD04)
Pour les applets de commande qui effectuent une opération qui modifie le système, elles doivent appeler la méthode System.Management.Automation.Cmdlet.ShouldProcess* pour demander la confirmation, et dans des cas spéciaux, appelez la méthode System.Management.Automation.Cmdlet.ShouldContinue*. (La méthode System.Management.Automation.Cmdlet.ShouldContinue* doit être appelée uniquement après l’appel de la méthode System.Management.Automation.Cmdlet.ShouldProcess*.)
Pour effectuer ces appels, l’applet de commande doit spécifier qu’elle prend en charge les demandes de confirmation en définissant le mot clé SupportsShouldProcess de l’attribut Cmdlet. Pour plus d’informations sur la définition de cet attribut, consultez déclaration d’attribut d’applet de commande.
Remarque
Si l’attribut Cmdlet de la classe d’applet de commande indique que l’applet de commande prend en charge les appels à la méthode System.Management.Automation.Cmdlet.ShouldProcess* et que l’applet de commande ne parvient pas à effectuer l’appel à la méthode System.Management.Automation.Cmdlet.ShouldProcess*, l’utilisateur peut modifier le système de manière inattendue.
Utilisez la méthode System.Management.Automation.Cmdlet.ShouldProcess* pour toute modification système. Une préférence utilisateur et le paramètre WhatIf contrôlent la méthode System.Management.Automation.Cmdlet.ShouldProcess*. En revanche, l’appel System.Management.Automation.Cmdlet.ShouldContinue* effectue une vérification supplémentaire des modifications potentiellement dangereuses. Cette méthode n’est contrôlée par aucune préférence utilisateur ni par le paramètre WhatIf. Si votre applet de commande appelle la méthode System.Management.Automation.Cmdlet.ShouldContinue*, elle doit avoir un paramètre Force qui contourne les appels à ces deux méthodes et qui continue avec l’opération. Cela est important, car il permet à votre applet de commande d’être utilisée dans des scripts et des hôtes non interactifs.
Si vos applets de commande prennent en charge ces appels, l’utilisateur peut déterminer si l’action doit réellement être effectuée. Par exemple, l’applet de commande stop-process appelle la méthode System.Management.Automation.Cmdlet.ShouldContinue* avant d’arrêter un ensemble de processus critiques, notamment les processus Système, Winlogon et Spoolsv.
Pour plus d’informations sur la prise en charge de ces méthodes, consultez Demande de confirmation.
Paramètre de force de support pour les sessions interactives (RD05)
Si votre applet de commande est utilisée de manière interactive, fournissez toujours un paramètre Force pour remplacer les actions interactives, telles que les invites ou la lecture de lignes d’entrée. Cela est important, car il permet à votre applet de commande d’être utilisée dans des scripts et des hôtes non interactifs. Les méthodes suivantes peuvent être implémentées par un hôte interactif.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.PSHostUserInterface.PromptForChoice
System.Management.Automation.Host.IHostUISupportsMultipleChoiceSelection.PromptForChoice
System.Management.Automation.Host.PSHostUserInterface.PromptForCredential*
System.Management.Automation.Host.PSHostUserInterface.ReadLine*
System.Management.Automation.Host.PSHostUserInterface.ReadLineAsSecureString*
Objets de sortie de document (RD06)
Windows PowerShell utilise les objets écrits dans le pipeline. Pour que les utilisateurs tirent parti des objets retournés par chaque applet de commande, vous devez documenter les objets retournés et documenter les membres de ces objets retournés.
Recommandations en matière de code
Les instructions suivantes doivent être suivies lors de l’écriture du code d’applet de commande. Lorsque vous trouvez une directive de code qui s’applique à votre situation, veillez à consulter les instructions de conception pour obtenir des instructions similaires.
Dériver de l’applet de commande ou des classes PSCmdlet (RC01)
Une applet de commande doit dériver du System.Management.Automation.Cmdlet ou System.Management.Automation.PSCmdlet classe de base. Les applets de commande qui dérivent de la classe System.Management.Automation.Cmdlet ne dépendent pas du runtime Windows PowerShell. Ils peuvent être appelés directement à partir de n’importe quel langage Microsoft .NET Framework. Les applets de commande qui dérivent de la classe System.Management.Automation.PSCmdlet dépendent du runtime Windows PowerShell. Par conséquent, ils s’exécutent dans un runspace.
Toutes les classes d’applet de commande que vous implémentez doivent être des classes publiques. Pour plus d’informations sur ces classes d’applet de commande, consultez Vue d’ensemble de l’applet de commande.
Spécifier l’attribut d’applet de commande (RC02)
Pour qu’une applet de commande soit reconnue par Windows PowerShell, sa classe .NET Framework doit être décorée avec l’attribut Cmdlet. Cet attribut spécifie les fonctionnalités suivantes de l’applet de commande.
Paire verbe-noun qui identifie l’applet de commande.
Jeu de paramètres par défaut utilisé lorsque plusieurs jeux de paramètres sont spécifiés. Le jeu de paramètres par défaut est utilisé lorsque Windows PowerShell n’a pas suffisamment d’informations pour déterminer le paramètre à utiliser.
Indique si l’applet de commande prend en charge les appels à la méthode System.Management.Automation.Cmdlet.ShouldProcess*. Cette méthode affiche un message de confirmation à l’utilisateur avant que l’applet de commande apporte une modification au système. Pour plus d’informations sur la façon dont les demandes de confirmation sont effectuées, consultez demande de confirmation.
Indiquez le niveau d’impact (ou gravité) de l’action associée au message de confirmation. Dans la plupart des cas, la valeur par défaut de Medium doit être utilisée. Pour plus d’informations sur la façon dont le niveau d’impact affecte les demandes de confirmation affichées à l’utilisateur, consultez demande de confirmation.
Pour plus d’informations sur la déclaration de l’attribut d’applet de commande, consultez CmdletAttribute Declaration.
Remplacer une méthode de traitement d’entrée (RC03)
Pour que l’applet de commande participe à l’environnement Windows PowerShell, elle doit remplacer au moins l’une des méthodes de traitement d’entrée suivantes.
System.Management.Automation.Cmdlet.BeginProcessing Cette méthode est appelée une seule fois et elle est utilisée pour fournir des fonctionnalités de prétraitement.
System.Management.Automation.Cmdlet.ProcessRecord Cette méthode est appelée plusieurs fois et elle est utilisée pour fournir des fonctionnalités d’enregistrement par enregistrement.
System.Management.Automation.Cmdlet.EndProcessing Cette méthode est appelée une fois, et elle est utilisée pour fournir des fonctionnalités de post-traitement.
Spécifier l’attribut OutputType (RC04)
L’attribut OutputType (introduit dans Windows PowerShell 2.0) spécifie le type .NET Framework que votre applet de commande retourne au pipeline. En spécifiant le type de sortie de vos applets de commande, vous rendez les objets retournés par votre applet de commande plus détectables par d’autres applets de commande. Pour plus d’informations sur la décoration de la classe d’applet de commande avec cet attribut, consultez Déclaration d’attribut OutputType.
Ne pas conserver les handles dans les objets de sortie (RC05)
Votre applet de commande ne doit pas conserver de handles aux objets passés à la méthode System.Management.Automation.Cmdlet.WriteObject*. Ces objets sont passés à l’applet de commande suivante dans le pipeline, ou ils sont utilisés par un script. Si vous conservez les handles des objets, deux entités possèdent chaque objet, ce qui provoque des erreurs.
Gérer les erreurs de manière robuste (RC06)
Un environnement d’administration détecte et apporte des modifications importantes au système que vous administrez. Par conséquent, il est essentiel que les applets de commande gèrent correctement les erreurs. Pour plus d’informations sur les enregistrements d’erreurs, consultez rapport d’erreurs Windows PowerShell.
Lorsqu’une erreur empêche une applet de commande de continuer à traiter plus d’enregistrements, il s’agit d’une erreur de fin. L’applet de commande doit appeler la méthode System.Management.Automation.Cmdlet.ThrowTerminatingError* qui fait référence à un objet System.Management.Automation.ErrorRecord. Si une exception n’est pas interceptée par l’applet de commande, le runtime Windows PowerShell lui-même génère une erreur de fin qui contient moins d’informations.
Pour une erreur sans fin qui n’arrête pas l’opération sur l’enregistrement suivant provenant du pipeline (par exemple, un enregistrement produit par un autre processus), l’applet de commande doit appeler la méthode System.Management.Automation.Cmdlet.WriteError* qui fait référence à un objet System.Management.Automation.ErrorRecord. Un exemple d’erreur sans fin est l’erreur qui se produit si un processus particulier ne parvient pas à s’arrêter. L’appel de la méthode System.Management.Automation.Cmdlet.WriteError* permet à l’utilisateur d’effectuer de manière cohérente les actions demandées et de conserver les informations relatives aux actions particulières qui échouent. Votre applet de commande doit gérer chaque enregistrement de manière aussi indépendante que possible.
L’objet System.Management.Automation.ErrorRecord référencé par les méthodes System.Management.Automation.Cmdlet.ThrowTerminatingError* et System.Management.Automation.Cmdlet.WriteError* nécessite une exception à son cœur. Suivez les instructions de conception du .NET Framework lorsque vous déterminez l’exception à utiliser. Si l’erreur est sémantiquement identique à une exception existante, utilisez cette exception ou dérivez de cette exception. Sinon, dérivez une nouvelle hiérarchie d’exceptions ou d’exception directement à partir du type de System.Exception.
Un objet System.Management.Automation.ErrorRecord nécessite également une catégorie d’erreur qui regroupe les erreurs pour l’utilisateur. L’utilisateur peut afficher les erreurs en fonction de la catégorie en définissant la valeur de la variable shell $ErrorView sur CategoryView. Les catégories possibles sont définies par l’énumération System.Management.Automation.ErrorCategory.
Si une applet de commande crée un thread et si le code en cours d’exécution dans ce thread lève une exception non gérée, Windows PowerShell ne intercepte pas l’erreur et met fin au processus.
Si un objet a du code dans son destructeur qui provoque une exception non gérée, Windows PowerShell ne intercepte pas l’erreur et met fin au processus. Cela se produit également si un objet appelle des méthodes Dispose qui provoquent une exception non gérée.
Utiliser un module Windows PowerShell pour déployer vos applets de commande (RC07)
Créez un module Windows PowerShell pour empaqueter et déployer vos applets de commande. La prise en charge des modules est introduite dans Windows PowerShell 2.0. Vous pouvez utiliser les assemblys qui contiennent vos classes d’applet de commande directement en tant que fichiers de module binaire (cela est très utile lors du test de vos applets de commande) ou vous pouvez créer un manifeste de module qui référence les assemblys d’applet de commande. (Vous pouvez également ajouter des assemblys enfichables existants lors de l’utilisation de modules.) Pour plus d’informations sur les modules, consultez Écriture d’un module Windows PowerShell.
Voir aussi
recommandations en matière de développement fortement encouragées
Collaborez avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner des problèmes et des demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
