Partager via

Vue d’ensemble des applets de commande

Une applet de commande est une commande légère utilisée dans l’environnement PowerShell. Le runtime PowerShell appelle ces applets de commande dans le contexte des scripts d’automatisation fournis à la ligne de commande. Le runtime PowerShell les appelle également par programmation via les API PowerShell.

Applets de commande

Les applets de commande effectuent une action et retournent généralement un objet Microsoft .NET à la commande suivante dans le pipeline. Une applet de commande est une seule commande qui participe à la sémantique de pipeline de PowerShell. Cela inclut des applets de commande binaires (C#), des fonctions de script avancées, CDXML et des flux de travail.

Cette documentation du Kit de développement logiciel (SDK) explique comment créer des applets de commande binaires écrites en C#. Pour plus d’informations sur les applets de commande basées sur des scripts, consultez :

Pour créer une applet de commande binaire, vous devez implémenter une classe d’applet de commande qui dérive de l’une des deux classes de base d’applets de commande spécialisées. La classe dérivée doit :

  • Déclarez un attribut qui identifie la classe dérivée en tant qu’applet de commande.
  • Définissez les propriétés publiques décorées avec des attributs qui identifient les propriétés publiques en tant que paramètres d’applet de commande.
  • Remplacez une ou plusieurs des méthodes de traitement d’entrée pour traiter les enregistrements.

Vous pouvez charger l’assembly qui contient la classe directement à l’aide de l’applet de commande Import-Module, ou vous pouvez créer une application hôte qui charge l’assembly à l’aide de l’API System.Management.Automation.Runspaces.InitialSessionState. Les deux méthodes fournissent un accès par programmation et en ligne de commande aux fonctionnalités de l’applet de commande.

Termes de l’applet de commande

Les termes suivants sont fréquemment utilisés dans la documentation de l’applet de commande PowerShell :

Attribut d’applet de commande

Attribut .NET utilisé pour déclarer une classe d’applet de commande en tant qu’applet de commande. Bien que PowerShell utilise plusieurs autres attributs facultatifs, l’attribut Cmdlet est requis. Pour plus d’informations sur cet attribut, consultez déclaration d’attribut d’applet de commande.

Paramètre d’applet de commande

Propriétés publiques qui définissent les paramètres disponibles pour l’utilisateur ou l’application qui exécute l’applet de commande. Les applets de commande peuvent avoir des paramètres de commutateur obligatoires, nommés, positionnels et. Les paramètres de commutateur vous permettent de définir des paramètres qui sont évalués uniquement si les paramètres sont spécifiés dans l’appel. Pour plus d’informations sur les différents types de paramètres, consultez Paramètres d’applet de commande.

Jeu de paramètres

Groupe de paramètres qui peuvent être utilisés dans la même commande pour effectuer une action spécifique. Une applet de commande peut avoir plusieurs jeux de paramètres, mais chaque jeu de paramètres doit avoir au moins un paramètre unique. Une bonne conception d’applet de commande suggère fortement que le paramètre unique soit également un paramètre obligatoire. Pour plus d’informations sur les jeux de paramètres, consultez ensembles de paramètres d’applet de commande.

Paramètre dynamique

Paramètre ajouté à l’applet de commande au moment de l’exécution. En règle générale, les paramètres dynamiques sont ajoutés à l’applet de commande lorsqu’un autre paramètre est défini sur une valeur spécifique. Pour plus d’informations sur les paramètres dynamiques, consultez Paramètres dynamiques de l’applet de commande.

Méthodes de traitement d’entrée

La classe System.Management.Automation.Cmdlet fournit les méthodes virtuelles suivantes utilisées pour traiter les enregistrements. Toutes les classes d’applet de commande dérivées doivent remplacer une ou plusieurs des trois premières méthodes :

Pour plus d’informations sur ces méthodes, consultez méthodes de traitement d’entrée d’applet de commande.

Lorsque vous implémentez une applet de commande, vous devez remplacer au moins l’une de ces méthodes de traitement d’entrée. En règle générale, la ProcessRecord() est la méthode que vous remplacez, car elle est appelée pour chaque enregistrement traité par l’applet de commande. En revanche, la méthode BeginProcessing() et la méthode EndProcessing() sont appelées une seule fois pour effectuer le prétraitement ou le post-traitement des enregistrements. Pour plus d’informations sur ces méthodes, consultez méthodes de traitement d’entrée.

Fonctionnalité ShouldProcess

PowerShell vous permet de créer des applets de commande qui invitent l’utilisateur à formuler des commentaires avant que l’applet de commande apporte une modification au système. Pour utiliser cette fonctionnalité, l’applet de commande doit déclarer qu’elle prend en charge la fonctionnalité ShouldProcess lorsque vous déclarez l’attribut Cmdlet, et l’applet de commande doit appeler les méthodes System.Management.Automation.Cmdlet.ShouldProcess et System.Management.Automation.Cmdlet.ShouldContinue à partir d’une méthode de traitement d’entrée. Pour plus d’informations sur la prise en charge des fonctionnalités de ShouldProcess, consultez Demande de confirmation.

Transaction

Groupe logique de commandes qui sont traitées comme une seule tâche. La tâche échoue automatiquement si une commande du groupe échoue et que l’utilisateur a le choix d’accepter ou de rejeter les actions effectuées dans la transaction. Pour participer à une transaction, l’applet de commande doit déclarer qu’elle prend en charge les transactions lorsque l’attribut Cmdlet est déclaré. La prise en charge des transactions a été introduite dans Windows PowerShell 2.0. Pour plus d’informations sur les transactions, consultez Comment prendre en charge les transactions.

Différences entre les applets de commande et les commandes

Les applets de commande diffèrent des commandes dans d’autres environnements d’interpréteur de commandes de la manière suivante :

  • Les applets de commande sont des instances de classes .NET ; ils ne sont pas des exécutables autonomes.
  • Les applets de commande peuvent être créées à partir de quelques dizaines de lignes de code.
  • Les applets de commande ne font généralement pas leur propre analyse, présentation d’erreurs ou mise en forme de sortie. L’analyse, la présentation des erreurs et la mise en forme de sortie sont gérées par le runtime PowerShell.
  • Les applets de commande traitent les objets d’entrée du pipeline plutôt que des flux de texte, et les applets de commande fournissent généralement des objets en tant que sortie au pipeline.
  • Les applets de commande sont orientées enregistrement, car elles traitent un seul objet à la fois.

Classes de base d’applets de commande

Windows PowerShell prend en charge les applets de commande dérivées des deux classes de base suivantes.

  • La plupart des applets de commande sont basées sur des classes .NET qui dérivent de la classe de base System.Management.Automation.Cmdlet. La dérivation de cette classe permet à une applet de commande d’utiliser l’ensemble minimal de dépendances sur le runtime Windows PowerShell. Cela a deux avantages. Le premier avantage est que les objets d’applet de commande sont plus petits et que vous êtes moins susceptible d’être affecté par les modifications apportées au runtime PowerShell. Le deuxième avantage est que, si vous devez le faire, vous pouvez créer directement une instance de l’objet cmdlet, puis l’appeler directement au lieu de l’appeler via le runtime PowerShell.

  • Les applets de commande plus complexes sont basées sur des classes .NET qui dérivent de la classe de base System.Management.Automation.PSCmdlet. La dérivation de cette classe vous donne beaucoup plus d’accès au runtime PowerShell. Cet accès permet à votre applet de commande d’appeler des scripts, d’accéder aux fournisseurs et d’accéder à l’état de session actuel. (Pour accéder à l’état de session actuel, vous obtenez et définissez des variables de session et des préférences.) Toutefois, la dérivation de cette classe augmente la taille de l’objet cmdlet et signifie que votre applet de commande est plus étroitement couplée à la version actuelle du runtime PowerShell.

En général, sauf si vous avez besoin de l’accès étendu au runtime PowerShell, vous devez dériver de la classe System.Management.Automation.Cmdlet. Toutefois, le runtime PowerShell dispose de fonctionnalités de journalisation étendues pour l’exécution des applets de commande. Si votre modèle d’audit dépend de cette journalisation, vous pouvez empêcher l’exécution de votre applet de commande à partir d’une autre applet de commande en dérivant de la classe System.Management.Automation.PSCmdlet.

Attributs des applets de commande

PowerShell définit plusieurs attributs .NET utilisés pour gérer les applets de commande et spécifier des fonctionnalités courantes fournies par PowerShell et qui peuvent être requis par l’applet de commande. Par exemple, les attributs sont utilisés pour désigner une classe en tant qu’applet de commande, pour spécifier les paramètres de l’applet de commande et demander la validation de l’entrée afin que les développeurs d’applets de commande n’aient pas à implémenter cette fonctionnalité dans leur code d’applet de commande. Pour plus d’informations sur les attributs, consultez attributs PowerShell.

Noms d’applets de commande

PowerShell utilise une paire de noms verbe-and-noun pour nommer des applets de commande. Par exemple, l’applet de commande Get-Command incluse dans PowerShell est utilisée pour obtenir toutes les applets de commande inscrites dans l’interpréteur de commandes. Le verbe identifie l’action effectuée par l’applet de commande, et le nom identifie la ressource sur laquelle l’applet de commande effectue son action.

Ces noms sont spécifiés lorsque la classe .NET est déclarée en tant qu’applet de commande. Pour plus d’informations sur la déclaration d’une classe .NET en tant qu’applet de commande, consultez déclaration d’attribut d’applet de commande.

Écriture de code d’applet de commande

Ce document fournit deux façons de découvrir comment le code d’applet de commande est écrit. Si vous préférez voir le code sans explication, consultez Exemples de code d’applet de commande. Si vous préférez plus d’explications sur le code, consultez le didacticiel GetProc, tutoriel StopProcou rubriques SelectStr Tutorial.

Pour plus d’informations sur les instructions relatives à l’écriture d’applets de commande, consultez instructions de développement des applets de commande.

Voir aussi

concepts d’applet de commande PowerShell

écrire une applet de commande PowerShell

sdk PowerShell