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

Article
10/07/2021

Cette section décrit les instructions que vous devez suivre lorsque vous écrivez 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. Vous pouvez constater que ces instructions ne s’appliquent pas à chaque scénario. Toutefois, s’ils s’appliquent et que vous ne suivez pas ces instructions, vos utilisateurs peuvent avoir une expérience médiocre lorsqu’ils utilisent vos applets de commande.

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 un nom spécifique pour un nom d’applet de commande (SD01)

Les noms utilisés dans les applets de commande doivent être très spécifiques afin que l’utilisateur puisse découvrir vos applets de commande. Préfixez les noms génériques tels que « Server » avec une version abrégée du nom du produit. par exemple, si un nom fait référence à un serveur qui exécute une instance de Microsoft SQL Server, utilisez un nom tel que « SQLServer ». La combinaison de noms spécifiques et la liste réduite de verbes approuvés permettent à l’utilisateur de découvrir et d’anticiper rapidement les fonctionnalités tout en évitant la duplication parmi les noms d’applets de commande.

Pour améliorer l’expérience utilisateur, le nom que vous choisissez pour un nom d’applet de commande doit être singulier. Par exemple, utilisez le nom Get-Process au lieu de Get-Processes . Il est préférable de suivre cette règle pour tous les noms d’applet de commande, même lorsqu’une applet de commande est susceptible d’agir sur plus d’un élément.

Utiliser la casse Pascal pour les noms d’applets de commande (SD02)

Utilisez la casse Pascal pour les noms de paramètres. En d’autres termes, mettez en majuscule la première lettre du verbe et tous les termes utilisés dans le nom. par exemple, « Clear-ItemProperty ».

Recommandations en matière de conception de paramètres (SD03)

Une applet de commande a besoin de paramètres qui reçoivent les données sur lesquelles elle doit s’exécuter, ainsi que des paramètres qui indiquent les informations utilisées pour déterminer les caractéristiques de l’opération. Par exemple, une applet de commande peut avoir un Name paramètre qui reçoit des données du pipeline, et l’applet de commande peut avoir un Force paramètre pour indiquer que l’applet de commande peut être forcée à exécuter son opération. Il n’existe aucune limite au nombre de paramètres qu’une applet de commande peut définir.

Utiliser des noms de paramètres standard

Votre applet de commande doit utiliser des noms de paramètres standard pour permettre à l’utilisateur de déterminer rapidement ce que signifie un paramètre particulier. Si un nom plus spécifique est requis, utilisez un nom de paramètre standard, puis spécifiez un nom plus spécifique en tant qu’alias. Par exemple, l' Get-Service applet de commande a un paramètre qui a un nom générique ( Name ) et un alias plus spécifique ( ServiceName ). Les deux termes peuvent être utilisés pour spécifier le paramètre.

Pour plus d’informations sur les noms de paramètres et leurs types de données, consultez instructions relatives au nom du paramètre d’applet de commande et aux fonctionnalités.

Utiliser des noms de paramètres singuliers

Évitez d’utiliser des noms au pluriel pour les paramètres dont la valeur est un élément unique. Cela comprend les paramètres qui acceptent des tableaux ou des listes, car l’utilisateur peut fournir un tableau ou une liste avec un seul élément.

Les noms de paramètres au pluriel doivent être utilisés uniquement dans les cas où la valeur du paramètre est toujours une valeur à plusieurs éléments. Dans ces cas, l’applet de commande doit vérifier que plusieurs éléments sont fournis, et l’applet de commande doit afficher un avertissement à l’utilisateur si plusieurs éléments ne sont pas fournis.

Utiliser la casse Pascal pour les noms de paramètres

Utilisez la casse Pascal pour les noms de paramètres. En d’autres termes, mettez en majuscule la première lettre de chaque mot dans le nom du paramètre, y compris la première lettre du nom. Par exemple, le nom du paramètre ErrorAction utilise la casse correcte. Les noms de paramètres suivants utilisent une casse incorrecte :

errorAction
erroraction

Paramètres qui acceptent une liste d’options

Il existe deux façons de créer un paramètre dont la valeur peut être sélectionnée à partir d’un ensemble d’options.

Définissez un type d’énumération (ou utilisez un type d’énumération existant) qui spécifie les valeurs valides. Utilisez ensuite le type d’énumération pour créer un paramètre de ce type.
Ajoutez l’attribut ValidateSet à la déclaration de paramètre. Pour plus d’informations sur cet attribut, consultez déclaration d’attribut ValidateSet.

Utiliser des types standard pour les paramètres

Pour garantir la cohérence avec d’autres applets de commande, utilisez des types standard pour les paramètres dans la mesure du possible. Pour plus d’informations sur les types qui doivent être utilisés pour des paramètres différents, consultez noms et types de paramètres d’appletde commande standard. cette rubrique fournit des liens vers plusieurs rubriques qui décrivent les noms et les types de .NET Framework pour les groupes de paramètres standard, tels que les « paramètres d’activité ».

utiliser les Types de .NET Framework Strongly-Typed

les paramètres doivent être définis en tant que types de .NET Framework pour fournir une meilleure validation des paramètres. Par exemple, les paramètres qui sont limités à une valeur d’un ensemble de valeurs doivent être définis en tant que type énumération. Pour prendre en charge une valeur Uniform Resource Identifier (URI), définissez le paramètre en tant que type System. Uri . Évitez les paramètres de chaîne de base pour toutes les propriétés de texte de forme libre.

Utiliser des types de paramètres cohérents

Lorsque le même paramètre est utilisé par plusieurs applets de commande, utilisez toujours le même type de paramètre. Par exemple, si le Process paramètre est un type System. Int16 pour une applet de commande, ne définissez pas le Process paramètre d’une autre applet de commande sur un type System. Uint16 .

Paramètres qui prennent la valeur true et false

Si votre paramètre prend uniquement true et false , définissez le paramètre en tant que type System. Management. Automation. Paramètre_Booléen. Un paramètre de commutateur est traité comme true lorsqu’il est spécifié dans une commande. si le paramètre n’est pas inclus dans une commande, Windows PowerShell considère que la valeur du paramètre est false . Ne définissez pas de paramètres booléens.

Si votre paramètre doit faire la distinction entre 3 valeurs : $true, $false et "Unspecified", définissez un paramètre de type Nullable <bool> . La nécessité d’une troisième valeur « non spécifiée » se produit généralement lorsque l’applet de commande peut modifier une propriété booléenne d’un objet. Dans ce cas, « non spécifié » signifie que vous ne pouvez pas modifier la valeur actuelle de la propriété.

Tableaux de prise en charge pour les paramètres

Souvent, les utilisateurs doivent effectuer la même opération sur plusieurs arguments. pour ces utilisateurs, une applet de commande doit accepter un tableau comme entrée de paramètre afin qu’un utilisateur puisse passer les arguments dans le paramètre en tant que Windows PowerShell variable. Par exemple, l’applet de commande « obtenir-process » utilise un tableau pour les chaînes qui identifient les noms des processus à récupérer.

Prendre en charge le paramètre PassThru

Par défaut, de nombreuses applets de commande qui modifient le système, telles que l’applet de commande Stop-Process , agissent en tant que « récepteurs » pour les objets et ne retournent pas de résultat. Ces applets de commande doivent implémenter le PassThru paramètre pour forcer l’applet de commande à retourner un objet. Lorsque le PassThru paramètre est spécifié, l’applet de commande retourne un objet à l’aide d’un appel à la méthode System. Management. Automation. cmdlet. WriteObject . Par exemple, la commande suivante arrête le processus Calc et passe le processus résultant au pipeline.

Stop-Process calc -passthru

Dans la plupart des cas, les applets de commande Add, Set et New doivent prendre en charge un PassThru paramètre.

Jeux de paramètres de prise en charge

Une applet de commande est destinée à atteindre un objectif unique. Toutefois, il existe souvent plusieurs façons de décrire l’opération ou la cible de l’opération. Par exemple, un processus peut être identifié par son nom, par son identificateur ou par un objet de processus. L’applet de commande doit prendre en charge toutes les représentations raisonnables de ses cibles. Normalement, l’applet de commande répond à cette exigence en spécifiant des jeux de paramètres (appelés jeux de paramètres) qui fonctionnent ensemble. Un paramètre unique peut appartenir à n’importe quel nombre de jeux de paramètres. Pour plus d’informations sur les jeux de paramètres, consultez jeux de paramètres d’appletde commande.

Lorsque vous spécifiez des jeux de paramètres, définissez un seul paramètre dans la valeur ValueFromPipeline. Pour plus d’informations sur la façon de déclarer l’attribut de paramètre , consultez déclaration ParameterAttribute.

Lorsque vous utilisez des jeux de paramètres, le jeu de paramètres par défaut est défini par l’attribut d' applet de commande. le jeu de paramètres par défaut doit inclure les paramètres les plus susceptibles d’être utilisés dans une session de Windows PowerShell interactive. Pour plus d’informations sur la façon de déclarer l’attribut d' applet de commande, consultez déclaration CmdletAttribute.

Fournir des commentaires à l’utilisateur (SD04)

Utilisez les instructions de cette section pour fournir des commentaires à l’utilisateur. Ces commentaires permettent à l’utilisateur d’être conscient de ce qui se produit dans le système et de prendre de meilleures décisions administratives.

le runtime Windows PowerShell permet à un utilisateur de spécifier comment gérer la sortie de chaque appel à la Write méthode en définissant une variable de préférence. L’utilisateur peut définir plusieurs variables de préférence, y compris une variable qui détermine si le système doit afficher des informations et une variable qui détermine si le système doit interroger l’utilisateur avant d’effectuer une action supplémentaire.

Prendre en charge les méthodes WriteWarning, WriteVerbose et WriteDebug

Une applet de commande doit appeler la méthode System. Management. Automation. cmdlet. WriteWarning quand l’applet de commande est sur le lieu d’effectuer une opération qui peut avoir un résultat inattendu. Par exemple, une applet de commande doit appeler cette méthode si l’applet de commande est sur le lieu de remplacer un fichier en lecture seule.

Une applet de commande doit appeler la méthode System. Management. Automation. applet de commande. WriteVerbose quand l’utilisateur a besoin de détails sur ce que fait l’applet de commande. Par exemple, une applet de commande doit appeler ces informations si l’auteur de l’applet de commande pense que des scénarios peuvent nécessiter des informations supplémentaires sur ce que fait l’applet de commande.

L’applet de commande doit appeler la méthode System. Management. Automation. cmdlet. WriteDebug lorsqu’un développeur ou un ingénieur du support technique doit comprendre ce qui a endommagé l’opération de l’applet de commande. Il n’est pas nécessaire que l’applet de commande appelle la méthode System. Management. Automation. applet de commande. WriteDebug dans le même code qui appelle la méthode System. Management. Automation. cmdlet. WriteVerbose , car le Debug paramètre présente les deux ensembles d’informations.

Prise en charge de WriteProgress pour les opérations qui prennent beaucoup de temps

Les opérations d’applet de commande qui prennent beaucoup de temps et qui ne peuvent pas s’exécuter en arrière-plan doivent prendre en charge la création de rapports de progression via des appels périodiques à la méthode System. Management. Automation. cmdlet. WriteProgress .

Utiliser les interfaces d’hôte

Parfois, une applet de commande doit communiquer directement avec l’utilisateur au lieu d’utiliser les différentes méthodes d’écriture ou de gestion prises en charge par la classe System. Management. Automation. applet de commande. Dans ce cas, l’applet de commande doit dériver de la classe System. Management. Automation. PSCmdlet et utiliser la propriété System. Management. Automation. PSCmdlet. Host * . Cette propriété prend en charge différents niveaux de type de communication, y compris les types PromptForChoice, prompt et WriteLine/ReadLine. Au niveau le plus spécifique, il fournit également des moyens de lire et d’écrire des clés individuelles et de gérer les mémoires tampons.

À moins qu’une applet de commande ne soit spécifiquement conçue pour générer une interface utilisateur graphique (GUI), elle ne doit pas ignorer l’hôte à l’aide de la propriété System. Management. Automation. PSCmdlet. Host * . L’applet de commande Out-GridView est un exemple d’applet de commande conçue pour générer une interface graphique utilisateur.

Notes

Les applets de commande ne doivent pas utiliser l’API System. console .

Créer un fichier d’aide d’applet de commande (SD05)

Pour chaque assembly d’applet de commande, créez un fichier de Help.xml qui contient des informations sur l’applet de commande. Ces informations incluent une description de l’applet de commande, des descriptions des paramètres de l’applet de commande, des exemples de l’utilisation de l’applet de commande, etc.

Instructions de code

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

Paramètres de codage (SC01)

Définissez un paramètre en déclarant une propriété publique de la classe cmdlet qui est décorée avec l’attribut Parameter . les paramètres ne doivent pas nécessairement être des membres statiques de la classe de .NET Framework dérivée pour l’applet de commande. Pour plus d’informations sur la façon de déclarer l’attribut de paramètre , consultez déclaration d’attribut de paramètre.

prise en charge Windows PowerShell chemins

le chemin d’accès Windows PowerShell est le mécanisme permettant de normaliser l’accès aux espaces de noms. lorsque vous assignez un chemin d’accès Windows PowerShell à un paramètre dans l’applet de commande, l’utilisateur peut définir un « lecteur » personnalisé qui agit comme raccourci vers un chemin d’accès spécifique. Lorsqu’un utilisateur désigne un tel lecteur, les données stockées, telles que les données du Registre, peuvent être utilisées de manière cohérente.

Si votre applet de commande permet à l’utilisateur de spécifier un fichier ou une source de données, il doit définir un paramètre de type System. String. Si plusieurs lecteurs sont pris en charge, le type doit être un tableau. Le nom du paramètre doit être Path , avec un alias PSPath . En outre, le Path paramètre doit prendre en charge les caractères génériques. Si la prise en charge des caractères génériques n’est pas nécessaire, définissez un LiteralPath paramètre.

si les données que l’applet de commande lit ou écrit doivent être un fichier, l’applet de commande doit accepter Windows PowerShell entrée de chemin d’accès, et l’applet de commande doit utiliser la propriété System. Management. Automation. Sessionstate. path pour convertir les chemins d’accès de Windows PowerShell en chemins d’accès reconnus par le système de fichiers. Les mécanismes spécifiques incluent les méthodes suivantes :

Si les données que l’applet de commande lit ou écrit ne sont qu’un ensemble de chaînes au lieu d’un fichier, l’applet de commande doit utiliser les informations de contenu du fournisseur ( Content membre) pour lire et écrire. Ces informations sont obtenues à partir de la propriété System. Management. Automation. Provider. CmdletProvider. InvokeProvider . Ces mécanismes permettent à d’autres magasins de données de participer à la lecture et à l’écriture de données.

Prendre en charge les caractères génériques

Une applet de commande doit prendre en charge les caractères génériques si possible. La prise en charge des caractères génériques se produit à de nombreux emplacements dans une applet de commande (surtout lorsqu’un paramètre prend une chaîne pour identifier un objet d’un ensemble d’objets). Par exemple, l’exemple Stop-Proc d’applet de commande du didacticiel StopProc définit un Name paramètre pour gérer les chaînes qui représentent des noms de processus. Ce paramètre prend en charge les caractères génériques afin que l’utilisateur puisse spécifier facilement les processus à arrêter.

Lorsque la prise en charge des caractères génériques est disponible, une opération d’applet de commande produit généralement un tableau. Parfois, il n’est pas judicieux de prendre en charge un tableau, car l’utilisateur ne peut utiliser qu’un seul élément à la fois. Par exemple, l’applet de commande set-location n’a pas besoin de prendre en charge un tableau, car l’utilisateur ne définit qu’un seul emplacement. Dans ce cas, l’applet de commande prend toujours en charge les caractères génériques, mais elle force la résolution sur un emplacement unique.

Pour plus d’informations sur les modèles de caractères génériques, consultez prise en charge des caractères génériques dans les paramètres d’applet decommande.

Définir des objets

Cette section contient des instructions pour la définition d’objets pour les applets de commande et pour l’extension d’objets existants.

Définir des membres standard

définir des membres standard pour étendre un type d’objet dans un fichier. ps1xml de types personnalisés (utilisez le fichier Windows PowerShell Types. ps1xml en tant que modèle). Les membres standard sont définis par un nœud portant le nom PSStandardMembers. ces définitions autorisent d’autres applets de commande et le runtime Windows PowerShell à travailler avec votre objet de manière cohérente.

Définir ObjectMembers à utiliser comme paramètres

Si vous concevez un objet pour une applet de commande, assurez-vous que ses membres mappent directement aux paramètres des applets de commande qui l’utiliseront. Ce mappage permet d’envoyer facilement l’objet au pipeline et de le passer d’une applet de commande à l’autre.

les objets .NET Framework préexistants retournés par les applets de commande sont souvent absents de certains membres importants ou pratiques qui sont requis par le développeur ou l’utilisateur de script. Ces membres manquants peuvent être particulièrement importants pour l’affichage et pour la création des noms de membres corrects afin que l’objet puisse être correctement transmis au pipeline. Créez un fichier Custom types. ps1xml pour documenter ces membres requis. Lorsque vous créez ce fichier, nous vous recommandons d’utiliser la Convention d’affectation de noms suivante : <Your_Product_Name>. Types. ps1xml.

Par exemple, vous pouvez ajouter une Mode propriété de script au type System. IO. FileInfo pour afficher plus clairement les attributs d’un fichier. En outre, vous pouvez ajouter une Count propriété d’alias au type System. Array pour permettre l’utilisation cohérente de ce nom de propriété (au lieu de Length ).

Implémenter l’interface IComparable

Implémentez une interface System. IComparable sur tous les objets de sortie. Cela permet aux objets de sortie d’être facilement redirigés vers diverses applets de commande de tri et d’analyse.

Mettre à jour les informations d’affichage

Si l’affichage d’un objet ne fournit pas les résultats attendus, créez un personnalisé <YourProductName> . Fichier format. ps1xml pour cet objet.

Prendre en charge l’entrée de pipeline bien définie (SC02)

Implémentez pour le milieu d’un pipeline

Implémentez une applet de commande en supposant qu’elle sera appelée à partir du milieu d’un pipeline (autrement dit, d’autres applets de commande produiront son entrée ou consomment sa sortie). Par exemple, vous pouvez supposer que l' Get-Process applet de commande, car elle génère des données, est utilisée uniquement comme première applet de commande dans un pipeline. Toutefois, étant donné que cette applet de commande est conçue pour le milieu d’un pipeline, cette applet de commande autorise les applets de commande ou les données précédentes dans le pipeline à spécifier les processus à récupérer.

Prendre en charge l’entrée à partir du pipeline

Dans chaque jeu de paramètres pour une applet de commande, incluez au moins un paramètre qui prend en charge l’entrée du pipeline. La prise en charge de l’entrée de pipeline permet à l’utilisateur de récupérer des données ou des objets, de les envoyer au jeu de paramètres correct et de transmettre les résultats directement à une applet de commande.

Un paramètre accepte l’entrée du pipeline si l’attribut du paramètre comprend le ValueFromPipeline mot clé, l' ValueFromPipelineByPropertyName attribut de mot clé ou les deux mots clés dans sa déclaration. Si aucun des paramètres d’un jeu de paramètres ne prend en charge les ValueFromPipeline ValueFromPipelineByPropertyName Mots clés ou, l’applet de commande ne peut pas être placée de manière significative après une autre applet de commande, car elle ignore toute entrée de pipeline.

Prendre en charge la méthode ProcessRecord

Pour accepter tous les enregistrements de l’applet de commande précédente dans le pipeline, votre applet de commande doit implémenter la méthode System. Management. Automation. applet de commande. ProcessRecord . Windows PowerShell appelle cette méthode plusieurs fois, une fois pour chaque enregistrement envoyé à votre applet de commande.

Écrire des enregistrements uniques dans le pipeline (SC03)

Lorsqu’une applet de commande retourne des objets, l’applet de commande doit écrire les objets immédiatement à mesure qu’ils sont générés. L’applet de commande ne doit pas les conserver pour les mettre en mémoire tampon dans un tableau combiné. Les applets de commande qui reçoivent les objets en entrée sont ensuite en mesure de traiter, d’afficher ou de traiter et d’afficher les objets de sortie sans délai. Une applet de commande qui génère des objets de sortie l’un après l’autre doit appeler la méthode System. Management. Automation. cmdlet. WriteObject . Une applet de commande qui génère des objets de sortie par lots (par exemple, parce qu’une API sous-jacente retourne un tableau d’objets de sortie) doit appeler la méthode System. Management. Automation. cmdlet. WriteObject avec le deuxième paramètre défini sur true .

Créer des applets de commande Case-Insensitive et Case-Preserving (SC04)

par défaut, Windows PowerShell lui-même ne respecte pas la casse. toutefois, étant donné qu’il traite de nombreux systèmes préexistants, Windows PowerShell conserve la casse pour faciliter l’exploitation et la compatibilité. en d’autres termes, si un caractère est fourni en majuscules, Windows PowerShell le conserve en majuscules. Pour que les systèmes fonctionnent correctement, une applet de commande doit suivre cette Convention. Si possible, elle doit fonctionner sans respect de la casse. Toutefois, il doit conserver le cas d’origine des applets de commande qui se produisent ultérieurement dans une commande ou dans le pipeline.

Voir aussi

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

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

Écriture d’une applet de commande Windows PowerShell

Share via