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

Cette section décrit les instructions que vous devez prendre en compte pour garantir de bonnes expériences de développement et d’utilisateur. Parfois, ils peuvent s’appliquer, et parfois ils ne le peuvent pas.

Recommandations en matière de conception

Les instructions suivantes doivent être prises en compte lors de la conception d’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.

Prise en charge d’un paramètre InputObject (AD01)

Étant donné que Windows PowerShell fonctionne directement avec les objets Microsoft .NET Framework, un objet .NET Framework est souvent disponible qui correspond exactement au type dont l’utilisateur a besoin pour effectuer une opération particulière. InputObject est le nom standard d’un paramètre qui accepte un objet tel que l’entrée. Par exemple, l’exemple Stop-Proc d’applet de commande dans le tutoriel StopProc définit un InputObject paramètre de type Process qui prend en charge l’entrée à partir du pipeline. L’utilisateur peut obtenir un ensemble d’objets de processus, les manipuler pour sélectionner les objets exacts à arrêter, puis les transmettre directement à l’applet Stop-Proc de commande.

Prendre en charge le paramètre Force (AD02)

Parfois, une applet de commande doit protéger l’utilisateur contre l’exécution d’une opération demandée. Une telle applet de commande doit prendre en charge un paramètre Force pour permettre à l’utilisateur de remplacer cette protection si l’utilisateur dispose des autorisations nécessaires pour effectuer l’opération.

Par exemple, l’applet de commande Remove-Item ne supprime pas normalement un fichier en lecture seule. Toutefois, cette applet de commande prend en charge un paramètre Force afin qu’un utilisateur puisse forcer la suppression d’un fichier en lecture seule. Si l’utilisateur a déjà l’autorisation de modifier l’attribut en lecture seule et que l’utilisateur supprime le fichier, l’utilisation du paramètre Force simplifie l’opération. Toutefois, si l’utilisateur n’a pas l’autorisation de supprimer le fichier, le paramètre Force n’a aucun effet.

Gérer les informations d’identification via Windows PowerShell (AD03)

Une applet de commande doit définir un Credential paramètre pour représenter les informations d’identification. Ce paramètre doit être de type System.Management.Automation.PSCredential et doit être défini à l’aide d’une déclaration d’attribut Credential. Cette prise en charge invite automatiquement l’utilisateur à entrer le nom d’utilisateur, le mot de passe ou les deux lorsqu’aucune information d’identification complète n’est fournie directement. Pour plus d’informations sur l’attribut Credential, consultez Déclaration d’attribut d’informations d’identification.

Prise en charge des paramètres d’encodage (AD04)

Si votre applet de commande lit ou écrit du texte dans ou à partir d’un formulaire binaire, comme l’écriture dans ou la lecture à partir d’un fichier dans un système de fichiers, votre applet de commande doit avoir un paramètre d’encodage qui spécifie la façon dont le texte est encodé dans le formulaire binaire.

Les applets de commande de test doivent retourner une valeur booléenne (AD05)

Les applets de commande qui effectuent des tests sur leurs ressources doivent retourner un type System.Boolean au pipeline afin qu’elles puissent être utilisées dans des expressions conditionnelles.

Recommandations en matière de code

Les instructions suivantes doivent être prises en compte lors de l’écriture de code d’applet de commande. Lorsque vous trouvez une directive qui s’applique à votre situation, veillez à consulter les instructions de conception pour obtenir des recommandations similaires.

Suivre les conventions d’affectation de noms de classes d’applet de commande (AC01)

En suivant les conventions d’affectation de noms standard, vous rendez vos applets de commande plus détectables et vous aidez l’utilisateur à comprendre exactement ce que font les applets de commande. Cette pratique est particulièrement importante pour d’autres développeurs utilisant Windows PowerShell, car les applets de commande sont des types publics.

Définir une applet de commande dans l’espace de noms correct

Vous définissez normalement la classe d’une applet de commande dans un espace de noms .NET Framework qui s’ajoute .Commands à l’espace de noms qui représente le produit dans lequel s’exécute l’applet de commande. Par exemple, les applets de commande incluses dans Windows PowerShell sont définies dans l’espace Microsoft.PowerShell.Commands de noms.

Nommez la classe Cmdlet pour qu’elle corresponde au nom de l’applet de commande

Lorsque vous nommez la classe .NET Framework qui implémente une applet de commande, nommez la classe<Verb><Noun>Command, où vous remplacez les espaces réservés et <Verb> les <Noun> verbes utilisés pour le nom de l’applet de commande. Par exemple, l’applet de commande Get-Process est implémentée par une classe appelée GetProcessCommand.

Si aucune entrée de pipeline ne remplace la méthode BeginProcessing (AC02)

Si votre applet de commande n’accepte pas d’entrée à partir du pipeline, le traitement doit être implémenté dans la méthode System.Management.Automation.Cmdlet.BeginProcessing . L’utilisation de cette méthode permet à Windows PowerShell de maintenir l’ordre entre les applets de commande. La première applet de commande du pipeline retourne toujours ses objets avant que les applets de commande restantes du pipeline obtiennent une chance de démarrer leur traitement.

Pour gérer les demandes d’arrêt, remplacez la méthode StopProcessing (AC03)

Remplacez la méthode System.Management.Automation.Cmdlet.StopProcessing pour que votre applet de commande puisse gérer le signal d’arrêt. Certaines applets de commande prennent beaucoup de temps pour terminer leur opération, et elles laissent un certain temps passer entre les appels au runtime Windows PowerShell, par exemple lorsque l’applet de commande bloque le thread dans les appels RPC de longue durée. Cela inclut les applets de commande qui effectuent des appels à la méthode System.Management.Automation.Cmdlet.WriteObject , à la méthode System.Management.Automation.Cmdlet.WriteError et à d’autres mécanismes de commentaires qui peuvent prendre beaucoup de temps. Dans ce cas, l’utilisateur peut avoir besoin d’envoyer un signal d’arrêt à ces applets de commande.

Implémenter l’interface IDisposable (AC04)

Si votre applet de commande comporte des objets qui ne sont pas supprimés (écrits dans le pipeline) par la méthode System.Management.Automation.Cmdlet.ProcessRecord , votre applet de commande peut nécessiter une suppression d’objet supplémentaire. Par exemple, si votre applet de commande ouvre un handle de fichier dans sa méthode System.Management.Automation.Cmdlet.BeginProcessing et conserve le handle ouvert pour une utilisation par la méthode System.Management.Automation.Cmdlet.ProcessRecord , ce handle doit être fermé à la fin du traitement.

Le runtime Windows PowerShell n’appelle pas toujours la méthode System.Management.Automation.Cmdlet.EndProcessing . Par exemple, la méthode System.Management.Automation.Cmdlet.EndProcessing peut ne pas être appelée si l’applet de commande est annulée au milieu de son opération ou si une erreur de fin se produit dans une partie de l’applet de commande. Par conséquent, la classe .NET Framework pour une applet de commande nécessitant le nettoyage d’objet doit implémenter le modèle d’interface Complet System.IDisposable , y compris le finaliseur, afin que le runtime Windows PowerShell puisse appeler à la fois les méthodes System.Management.Automation.Cmdlet.EndProcessing et System.IDisposable.Dispose* à la fin du traitement.

Utiliser des types de paramètres conviviaux de sérialisation (AC05)

Pour prendre en charge l’exécution de votre applet de commande sur des ordinateurs distants, utilisez des types qui peuvent être sérialisés sur l’ordinateur client, puis réhydratés sur l’ordinateur serveur. Les types suivants sont conviviaux pour la sérialisation.

Types primitifs :

• Octet, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 et UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri et Version.
• Char, String, XmlDocument.

Types réhydratables intégrés :

• PSPrimitiveDictionary
• Paramètre de commutation
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Autres types :

• SecureString
• Conteneurs (listes et dictionnaires du type ci-dessus)

Utiliser SecureString pour les données sensibles (AC06)

Lorsque vous gérez des données sensibles, utilisez toujours le type de données System.Security.SecureString . Cela peut inclure l’entrée de pipeline aux paramètres, ainsi que le retour de données sensibles au pipeline.

Bien que .NET recommande d’utiliser SecureString pour le nouveau développement, PowerShell continue de prendre en charge la classe SecureString pour la compatibilité descendante. L’utilisation d’un SecureString est encore plus sécurisée que l’utilisation d’une chaîne de texte brut. PowerShell s’appuie toujours sur le type SecureString pour éviter d’exposer accidentellement le contenu à la console ou dans les journaux. Utilisez SecureString avec soin, car il peut être facilement converti en chaîne de texte brut. Pour une discussion complète sur l’utilisation de SecureString, consultez la documentation de la classe System.Security.SecureString.

Voir aussi

recommandations de développement requises

recommandations en matière de développement fortement encouragées

écriture d’une applet de commande Windows PowerShell