Share via

Instructions dont le suivi est impératif pour le développement

  • Article

Les instructions suivantes doivent être suivies lors de l’écriture de vos applets de commande. Elles sont réparties en instructions pour concevoir des applets de commande et des instructions pour l’écriture de 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 expérience médiocre lorsqu’ils utilisent vos applets de commande.

Dans cette rubrique

Recommandations en matière de conception

Instructions de code

Recommandations en matière de conception

Les instructions suivantes doivent être suivies lors de la conception des 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 instruction de conception qui s’applique à votre situation, veillez à consulter les instructions de code pour obtenir des instructions similaires.

Utiliser uniquement les verbes approuvés (RD01)

Le verbe spécifié dans l’attribut d’applet de commande doit provenir du jeu de verbes reconnu fourni 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 verbe approuvés, consultez verbes d’appletde commande.

Les utilisateurs ont besoin d’un ensemble de noms d’applets de commande détectables et attendus. Utilisez le verbe approprié pour permettre à l’utilisateur d’effectuer une évaluation rapide de ce que fait une applet de commande et de 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 « Start » : get-command start-* . Utilisez les noms de vos applets de commande pour différencier vos applets de commande des 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 des applets de commande : caractères qui ne peuvent pas être utilisés (RD02)

Lorsque vous nommez des applets de commande, n’utilisez pas les caractères spéciaux suivants.

Caractère Nom
# signe dièse
, virgule
() parenthèses
{} accolades
[] crochets
& reprises
- Note de trait d’Union : 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
^ accent circonflexe
; point-virgule
: signe
" guillemet double
' guillemet simple
<> chevrons
| barre verticale
? point d'interrogation
@ arobase
` cycle d’arrière-plan (accent grave)
* astérisque
% signe de pourcentage
+ signe plus
= signe égal
~ surmonté

Noms de paramètres qui ne peuvent pas être utilisés (RD03)

Windows PowerShell fournit un ensemble commun de paramètres à toutes les applets de commande, ainsi que des paramètres supplémentaires qui sont ajoutés dans des situations spécifiques. Lors de la conception de vos propres applets de commande, vous ne pouvez pas utiliser les noms suivants : Confirm, Debug, ErrorAction, ErrorVariable, unbuffer, unvariable, 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, ils doivent appeler la méthode System. Management. Automation. cmdlet. ShouldProcess * pour demander la confirmation. dans certains cas, appelez la méthode System. Management. Automation. cmdlet. ShouldContinue * . (La méthode System. Management. Automation. applet de commande. 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 SupportsShouldProcess mot clé de l’attribut d’applet de commande. Pour plus d’informations sur la définition de cet attribut, consultez déclaration d’attribut d’appletde commande.

Notes

Si l’attribut d’applet de commande 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 à appeler 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 du système. Une préférence de l’utilisateur et le WhatIf paramètre contrôlent la méthode System. Management. Automation. cmdlet. ShouldProcess * . En revanche, l’appel System. Management. Automation. applet de commande. ShouldContinue * effectue une vérification supplémentaire pour les modifications potentiellement dangereuses. Cette méthode n’est pas contrôlée par une préférence utilisateur ni par le WhatIf paramètre. Si votre applet de commande appelle la méthode System. Management. Automation. applet de commande. ShouldContinue * , elle doit avoir un Force paramètre qui ignore les appels à ces deux méthodes et qui poursuit l’opération. C’est important, car cela permet d’utiliser votre applet de commande dans des hôtes et des scripts 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. applet de commande. ShouldContinue * avant d’arrêter un ensemble de processus critiques, y compris les processus System, Winlogon et spoolsv.

Pour plus d’informations sur la prise en charge de ces méthodes, consultez demande de confirmation.

Paramètre 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 des lignes d’entrée. C’est important, car cela permet d’utiliser votre applet de commande dans des hôtes et des scripts non interactifs. Les méthodes suivantes peuvent être implémentées par un hôte interactif.

Objets de sortie de document (RD06)

Windows PowerShell utilise les objets écrits dans le pipeline. Pour que les utilisateurs puissent tirer parti des objets retournés par chaque applet de commande, vous devez documenter les objets qui sont retournés, et vous devez documenter les membres desquels les objets retournés sont utilisés.

Instructions de code

Les instructions suivantes doivent être suivies lors de l’écriture du code de l’applet de commande. Lorsque vous trouvez une indication de code qui s’applique à votre situation, veillez à consulter les instructions de conception pour obtenir des instructions similaires.

Dérivation à partir de l’applet de commande ou des classes PSCmdlet (RC01)

Une applet de commande doit dériver de la classe de base System. Management. Automation. applet de commande ou System. Management. Automation. PSCmdlet . les applets de commande qui dérivent de la classe System. Management. Automation. applet de commande ne dépendent pas du runtime Windows PowerShell. elles peuvent être appelées directement à partir de n’importe quel langage de .NET Framework Microsoft. les applets de commande qui dérivent de la classe System. Management. Automation. PSCmdlet dépendent du runtime Windows PowerShell. Par conséquent, elles s’exécutent dans une instance d’exécution.

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 des appletsde 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 applet de commande. Cet attribut spécifie les fonctionnalités suivantes de l’applet de commande.

  • Paire verbe-and-substantif 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 ne dispose pas de suffisamment d’informations pour déterminer le jeu de paramètres à 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 (gravité) de l’action associée au message de confirmation. Dans la plupart des cas, la valeur par défaut moyenne doit être utilisée. Pour plus d’informations sur la façon dont le niveau d’impact affecte les demandes de confirmation qui sont affichées à l’utilisateur, consultez demande de confirmation.

Pour plus d’informations sur la façon de déclarer l’attribut d’applet de commande, consultez déclaration CmdletAttribute.

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. applet de commande. BeginProcessing cette méthode est appelée une fois et elle est utilisée pour fournir des fonctionnalités de pré-traitement.

System. Management. Automation. applet de commande. 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. applet de commande. EndProcessing cette méthode est appelée une fois, et elle est utilisée pour fournir la fonctionnalité de publication.

Spécifier l’attribut OutputType (RC04)

l’attribut OutputType (introduit dans Windows PowerShell 2,0) spécifie le type de .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 cmdlet avec cet attribut, consultez la déclaration d’attribut OutputType.

Ne pas conserver les descripteurs des objets de sortie (RC05)

Votre applet de commande ne doit pas conserver les descripteurs des 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 descripteurs aux objets, deux entités posséderont chaque objet, ce qui génère des erreurs.

Gérer les erreurs de façon robuste (RC06)

Un environnement d’administration détecte par nature et apporte des modifications importantes au système que vous gérez. Par conséquent, il est vital que les applets de commande gèrent correctement les erreurs. pour plus d’informations sur les enregistrements d’erreurs, consultez Windows PowerShell le rapport d’erreurs.

Un objet System. Management. Automation. ErrorRecord nécessite également une catégorie d’erreur qui regroupe les erreurs de l’utilisateur. L’utilisateur peut afficher les erreurs en fonction de la catégorie en définissant la valeur de la $ErrorView variable d’interpréteur de commandes 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 nouveau thread et si le code qui s’exécute dans ce thread lève une exception non gérée, Windows PowerShell n’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 n’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 comme fichiers de module binaire (cette fonctionnalité 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 de composant logiciel enfichable existants lors de l’utilisation de modules.) pour plus d’informations sur les modules, consultez écriture d’un Module Windows PowerShell.

Voir aussi

Instructions dont le suivi est fortement recommandé pour le développement

Instructions dont le suivi est conseillé pour le développement

Écriture d’une applet de commande Windows PowerShell