Partage via

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

Cette section décrit les instructions que vous devez suivre 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. 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 mauvaise expérience lorsqu’ils utilisent vos applets de commande.

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

Les noms utilisés dans le nommage des applets de commande doivent être très spécifiques afin que l’utilisateur puisse découvrir vos applets de commande. Préfixes génériques tels que « serveur » avec une version abrégée du nom du produit. Par exemple, si un nom fait référence à un serveur exécutant une instance de Microsoft SQL Server, utilisez un nom tel que « SQLServer ». La combinaison de noms spécifiques et de la courte liste de verbes approuvés permet à l’utilisateur de découvrir et d’anticiper rapidement les fonctionnalités tout en évitant la duplication entre 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’applets de commande, même lorsqu’une applet de commande est susceptible d’agir sur plusieurs éléments.

Utiliser la casse Pascal pour les noms des cmdlets (SD02)

Utilisez la casse Pascal pour les noms de paramètres. En d’autres termes, mettre 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 il doit fonctionner et les 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 d’effectuer 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 afin que l’utilisateur puisse rapidement déterminer ce qu’un paramètre particulier signifie. 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’applet Get-Service 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 Cmdlet Parameter Name and Functionality Guidelines.

Utiliser des noms de paramètres singuliers

Évitez d’utiliser des noms pluriels pour les paramètres dont la valeur est un élément unique. Cela inclut les paramètres qui prennent 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 plural 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, mettre 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 ErrorAction du paramètre utilise la mise en majuscule correcte. Les noms de paramètres suivants utilisent une mise en majuscule incorrecte :

  • errorAction
  • erroraction

Paramètres qui prennent 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. Ensuite, utilisez 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 ValidateSet Attribute Declaration.

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 le plus souvent possible. Pour plus d’informations sur les types qui doivent être utilisés pour différents paramètres, consultez Noms et types de paramètres d’applet de commande standard. Cette rubrique fournit des liens vers plusieurs rubriques qui décrivent les noms et les types d’infrastructure .NET pour les groupes de paramètres standard, tels que les « paramètres d’activité ».

Utiliser des types fortement typés du Framework .NET

Les paramètres doivent être définis en tant que types .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 comme un type d’énumération. Pour prendre en charge une valeur URI (Uniform Resource Identifier), définissez le paramètre en tant que type System.Uri . Évitez les paramètres de chaîne simples sauf pour 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 paramètre Process est de type System.Int16 pour une applet de commande, ne faites pas du paramètre Process d'une autre applet de commande un type System.Uint16.

Paramètres qui prennent la valeur Vrai et Faux

Si votre paramètre prend uniquement true et falsedéfinit le paramètre comme type System.Management.Automation.SwitchParameter. Un [switch] paramètre 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 « non spécifié », définissez un paramètre de type bool< Nullable>. La nécessité d’une 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 ne pas modifier la valeur actuelle de la propriété.

Tableaux de prise en charge pour les paramètres

Fréquemment, 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 variable PowerShell Windows. Par exemple, l’applet de commande Get-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 comme des « 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 Calc (CalculatorApp.exe) et transmet le processus résultant au pipeline.

Stop-Process -Name CalculatorApp -PassThru

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

Ensembles de paramètres de support

Une applet de commande est destinée à accomplir un seul objectif. 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 satisfait à cette exigence en spécifiant des ensembles de paramètres (appelés ensembles 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 Ensembles de paramètres d’applet de 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 déclaration de l’attribut Parameter , consultez La déclaration ParameterAttribute.

Lorsque des jeux de paramètres sont utilisés, le jeu de paramètres par défaut est défini par l’attribut Cmdlet . Le jeu de paramètres par défaut doit inclure les paramètres les plus susceptibles d’être utilisés dans une session Interactive Windows PowerShell. Pour plus d’informations sur la déclaration de l’attribut Cmdlet , consultez CmdletAttribute Declaration.

Fournir des commentaires à l’utilisateur (SD04)

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

Le runtime PowerShell Windows permet à un utilisateur de spécifier comment gérer la sortie de chaque appel à la méthode Write en définissant une variable de préférence. L’utilisateur peut définir plusieurs variables de préférence, notamment 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’entreprendre d’autres actions.

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

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

Une applet de commande doit appeler la méthode System.Management.Automation.Cmdlet.WriteVerbose lorsque l’utilisateur nécessite des 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 estime qu’il existe des scénarios qui peuvent nécessiter plus d’informations 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 d’applet de commande. Il n’est pas nécessaire que l’applet de commande appelle la méthode System.Management.Automation.Cmdlet.WriteDebug dans le même code que celle qui appelle la méthode System.Management.Automation.Cmdlet.WriteVerbose , car le Debug paramètre présente les deux ensembles d’informations.

Prendre en charge 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 hôtes

Parfois, une applet de commande doit communiquer directement avec l’utilisateur au lieu d’utiliser les différentes méthodes Write ou Should prises en charge par la classe System.Management.Automation.Cmdlet . 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, notamment 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.

Sauf si une applet de commande est spécifiquement conçue pour générer une interface utilisateur graphique (GUI), elle ne doit pas contourner l’hôte à l’aide de la propriété System.Management.Automation.PSCmdlet.Host* . Un exemple de cmdlet conçue pour générer une interface utilisateur est la cmdlet Out-GridView.

Note

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

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

Pour chaque assembly d’applet de commande, créez un fichier 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 d’utilisation de l’applet de commande, etc.

Recommandations en matière 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 directive 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 d’applet de commande décorée avec l’attribut Parameter . Les paramètres n’ont pas besoin d’être des membres statiques de la classe .NET Framework dérivée pour l’applet de commande. Pour plus d’informations sur la déclaration de l’attribut Paramètre , consultez Déclaration d’attribut de paramètre.

Prise en charge des chemins PowerShell dans Windows

Le chemin d’accès PowerShell Windows est le mécanisme permettant de normaliser l’accès aux espaces de noms. Lorsque vous affectez un chemin d’accès PowerShell Windows à un paramètre dans l’applet de commande, l’utilisateur peut définir un « lecteur » personnalisé qui agit comme un raccourci vers un chemin spécifique. Lorsqu’un utilisateur désigne un tel lecteur, des données stockées, telles que des données dans le 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 de 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 les chemins d'accès Windows PowerShell, et l’applet de commande doit utiliser la propriété System.Management.Automation.SessionState.Path pour traduire les chemins d’accès Windows PowerShell en chemins que le système de fichiers reconnaît. 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 endroits dans une applet de commande (en particulier lorsqu’un paramètre prend une chaîne pour identifier un objet à partir d’un ensemble d’objets). Par exemple, l’exemple Stop-Proc d’applet de commande du tutoriel StopProc définit un Name paramètre pour gérer les chaînes qui représentent les noms de processus. Ce paramètre prend en charge les caractères génériques afin que l’utilisateur puisse facilement spécifier 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 peut utiliser 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 impose une résolution vers 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 de l’applet de commande.

Définition d’objets

Cette section contient des instructions pour définir des objets pour les applets de commande et pour étendre des objets existants.

Définir des membres standard

Définissez des membres standard pour étendre un type d’objet dans un fichier Types.ps1xml personnalisé (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 permettent à d’autres applets de commande et au runtime PowerShell Windows d’utiliser 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 sont mappés directement aux paramètres des applets de commande qui l’utiliseront. Ce mappage permet à l’objet d’être facilement envoyé au pipeline et d’être transmis d’une applet de commande à une autre.

Les objets .NET Framework préexistants retournés par les applets de commande manquent fréquemment certains membres importants ou pratiques nécessaires au développeur ou à l’utilisateur du script. Ces membres manquants peuvent être particulièrement importants pour l’affichage et pour créer les noms de membres corrects afin que l’objet puisse être correctement transmis au pipeline. Créez un fichier Types.ps1xml personnalisé pour documenter ces membres requis. Lorsque vous créez ce fichier, nous vous recommandons 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 autoriser 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 différentes 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 fichier .Format.ps1xml personnalisé pour cet objet VotreNomDeProduit<>.

Soutien d'une entrée de pipeline bien définie (SC02)

Mise en œuvre pour la partie centrale 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 produisent son entrée ou consomment sa sortie). Par exemple, vous pouvez supposer que l’applet Get-Process 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 permet aux applets de commande ou aux données précédentes dans le pipeline de spécifier les processus à récupérer.

Prise en charge de l’entrée à partir du pipeline

Dans chaque ensemble de paramètres pour une applet de commande, incluez au moins un paramètre qui supporte l'entrée depuis le 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 acheminer vers le jeu de paramètres approprié et de transmettre les résultats directement à un cmdlet.

Un paramètre accepte l’entrée du pipeline si l’attribut Paramètre inclut le ValueFromPipeline mot clé, l’attribut ValueFromPipelineByPropertyName 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 mots clés ValueFromPipeline ou ValueFromPipelineByPropertyName, l’applet de commande ne peut pas être placée de manière significative à la suite d'une autre applet de commande, car elle ignore toute entrée de pipeline.

Support de 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.Cmdlet.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 contenir pour les mettre en mémoire tampon dans un tableau combiné. Les applets de commande qui reçoivent les objets en tant qu’entrée pourront ensuite traiter, afficher ou traiter et afficher les objets de sortie sans délai. Une applet de commande qui génère des objets de sortie un à la fois 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, car une API sous-jacente retourne un tableau d’objets de sortie) doit appeler la méthode System.Management.Automation.Cmdlet.WriteObject avec son deuxième paramètre défini truesur .

Créer des cmdlets Case-Insensitive et Case-Preserving (SC04)

Par défaut, Windows PowerShell est insensible à la casse. Toutefois, étant donné qu’il traite de nombreux systèmes préexistants, Windows PowerShell conserve le cas pour faciliter l’opération 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 de manière insensible à 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 de développement requises

Recommandations en matière de développement

Écriture d’un cmdlet Windows PowerShell

  • Last updated on