Ajout de paramètres qui traitent l’entrée de la ligne de commande

Article
03/25/2025

Une source d’entrée pour une applet de commande est la ligne de commande. Cette rubrique explique comment ajouter un paramètre à l’applet de commande Get-Proc (décrite dans Création de votre première applet de commande) afin que l’applet de commande puisse traiter l’entrée à partir de l’ordinateur local en fonction d’objets explicites transmis à l’applet de commande. L’applet de commande Get-Proc décrite ici récupère les processus en fonction de leurs noms, puis affiche des informations sur les processus à l’invite de commandes.

Définition de la classe Cmdlet

La première étape de la création d’applets de commande est l’affectation de noms aux applets de commande et la déclaration de la classe .NET Framework qui implémente l’applet de commande. Cette applet de commande récupère les informations de processus, de sorte que le nom du verbe choisi ici est « Get ». (Presque n’importe quelle sorte d’applet de commande capable de récupérer des informations peut traiter l’entrée de ligne de commande.) Pour plus d’informations sur les verbes d’applet de commande approuvés, consultez noms de verbes d’applet de commande.

Voici la déclaration de classe de l’applet de commande Get-Proc. Des détails sur cette définition sont fournis dans Création de votre première applet de commande.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Déclaration de paramètres

Un paramètre d’applet de commande permet à l’utilisateur de fournir une entrée à l’applet de commande. Dans l’exemple suivant, Get-Proc et Get-Member sont les noms des applets de commande pipeline et MemberType est un paramètre pour l’applet de commande Get-Member. Le paramètre a l’argument « property ».

> Get-Proc PS ; Get-Member -MemberType, propriété

Pour déclarer des paramètres pour une applet de commande, vous devez d’abord définir les propriétés qui représentent les paramètres. Dans l’applet de commande Get-Proc, le seul paramètre est Name, ce qui représente dans ce cas le nom de l’objet de processus .NET Framework à récupérer. Par conséquent, la classe d’applet de commande définit une propriété de chaîne de type pour accepter un tableau de noms.

Voici la déclaration de paramètre pour le paramètre Name de l’applet de commande Get-Proc.

/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
  [Parameter(Position = 0)]
  [ValidateNotNullOrEmpty]
  public string[] Name
  {
    get { return processNames; }
    set { processNames = value; }
  }
  private string[] processNames;

  #endregion Parameters

<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Pour informer le runtime Windows PowerShell que cette propriété est le paramètre Name, un attribut System.Management.Automation.ParameterAttribute est ajouté à la définition de propriété. La syntaxe de base pour déclarer cet attribut est [Parameter()].

Remarque

Un paramètre doit être explicitement marqué comme public. Les paramètres qui ne sont pas marqués comme étant publics par défaut internes et qui ne sont pas trouvés par le runtime Windows PowerShell.

Cette applet de commande utilise un tableau de chaînes pour le paramètre Name. Si possible, votre applet de commande doit également définir un paramètre en tant que tableau, car cela permet à l’applet de commande d’accepter plusieurs éléments.

Éléments à mémoriser sur les définitions de paramètres

Les noms de paramètres Windows PowerShell prédéfinis et les types de données doivent être réutilisés autant que possible pour vous assurer que votre applet de commande est compatible avec les applets de commande Windows PowerShell. Par exemple, si toutes les applets de commande utilisent le nom de paramètre de Id prédéfini pour identifier une ressource, l’utilisateur comprend facilement la signification du paramètre, quelle que soit l’applet de commande utilisée. En fait, les noms de paramètres suivent les mêmes règles que celles utilisées pour les noms de variables dans le Common Language Runtime (CLR). Pour plus d’informations sur l’affectation de noms de paramètres, consultez des noms de paramètres d’applet de commande.
Windows PowerShell réserve quelques noms de paramètres pour fournir une expérience utilisateur cohérente. N’utilisez pas ces noms de paramètres : WhatIf, Confirm, Verbose, Debug, Warn, ErrorAction, ErrorVariable, OutVariableet OutBuffer. En outre, les alias suivants pour ces noms de paramètres sont réservés : vb, db, ea, ev, ovet ob.
Name est un nom de paramètre simple et commun, recommandé pour une utilisation dans vos applets de commande. Il est préférable de choisir un nom de paramètre comme celui-ci qu’un nom complexe unique à une applet de commande spécifique et difficile à mémoriser.
Les paramètres ne respectent pas la casse dans Windows PowerShell, bien que par défaut, l’interpréteur de commandes conserve la casse. La sensibilité à la casse des arguments dépend de l’opération de l’applet de commande. Les arguments sont passés à un paramètre tel que spécifié à la ligne de commande.
Pour obtenir des exemples d’autres déclarations de paramètres, consultez Paramètres d’applet de commande.

Déclaration de paramètres en tant que positionnelle ou nommée

Une applet de commande doit définir chaque paramètre comme paramètre positionnel ou nommé. Les deux types de paramètres acceptent des arguments uniques, plusieurs arguments séparés par des virgules et des paramètres booléens. Un paramètre booléen, également appelé commutateur, gère uniquement les paramètres booléens. Le commutateur est utilisé pour déterminer la présence du paramètre. La valeur par défaut recommandée est false.

L’exemple d’applet de commande Get-Proc définit le paramètre Name comme paramètre positionnel avec la position 0. Cela signifie que le premier argument entré par l’utilisateur sur la ligne de commande est automatiquement inséré pour ce paramètre. Si vous souhaitez définir un paramètre nommé, pour lequel l’utilisateur doit spécifier le nom du paramètre à partir de la ligne de commande, laissez le mot clé Position hors de la déclaration d’attribut.

Remarque

Sauf si les paramètres doivent être nommés, nous vous recommandons de définir la position des paramètres les plus utilisés afin que les utilisateurs n’aient pas à taper le nom du paramètre.

Déclaration de paramètres comme obligatoires ou facultatifs

Une applet de commande doit définir chaque paramètre comme paramètre facultatif ou obligatoire. Dans l’exemple d’applet de commande Get-Proc, le paramètre Name est défini comme facultatif, car le mot clé Mandatory n’est pas défini dans la déclaration d’attribut.

Prise en charge de la validation des paramètres

L’exemple d’applet de commande Get-Proc ajoute un attribut de validation d’entrée, System.Management.Automation.ValidateNotNullOrEmptyAttribute, au paramètre Name pour activer la validation que l’entrée n’est ni null ni vide. Cet attribut est l’un des plusieurs attributs de validation fournis par Windows PowerShell. Pour obtenir des exemples d’autres attributs de validation, consultez Validateing Parameter Input.

[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name

Substitution d’une méthode de traitement d’entrée

Si votre applet de commande doit gérer l’entrée de ligne de commande, elle doit remplacer les méthodes de traitement d’entrée appropriées. Les méthodes de traitement d’entrée de base sont introduites dans Création de votre première applet de commande.

L’applet de commande Get-Proc remplace la méthode System.Management.Automation.Cmdlet.ProcessRecord pour gérer l’entrée de paramètre Name fournie par l’utilisateur ou un script. Cette méthode obtient les processus pour chaque nom de processus demandé, ou tous les processus si aucun nom n’est fourni. Notez que dans System.Management.Automation.Cmdlet.ProcessRecord, l’appel à System.Management.Automation.Cmdlet.WriteObject est le mécanisme de sortie permettant d’envoyer des objets de sortie au pipeline. Le deuxième paramètre de cet appel, enumerateCollection, est défini sur true pour informer le runtime Windows PowerShell pour énumérer le tableau de sortie d’objets de processus et écrire un processus à la fois dans la ligne de commande.

protected override void ProcessRecord()
{
  // If no process names are passed to the cmdlet, get all processes.
  if (processNames == null)
  {
    // Write the processes to the pipeline making them available
    // to the next cmdlet. The second argument of this call tells
    // PowerShell to enumerate the array, and send one process at a
    // time to the pipeline.
    WriteObject(Process.GetProcesses(), true);
  }
  else
  {
    // If process names are passed to the cmdlet, get and write
    // the associated processes.
    foreach (string name in processNames)
    {
      WriteObject(Process.GetProcessesByName(name), true);
    }
  }
}

Protected Overrides Sub ProcessRecord()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        Dim processes As Process()
        processes = Process.GetProcesses()
    End If

    '/ If process names are specified, write the processes to the
    '/ pipeline to display them or make them available to the next cmdlet.

    For Each name As String In processNames
        '/ The second parameter of this call tells PowerShell to enumerate the
        '/ array, and send one process at a time to the pipeline.
        WriteObject(Process.GetProcessesByName(name), True)
    Next

End Sub 'ProcessRecord

Exemple de code

Pour obtenir l’exemple de code C# complet, consultez Exemple getProcessSample02.

Définition des types d’objets et de la mise en forme

Windows PowerShell transmet des informations entre les applets de commande à l’aide d’objets .NET Framework. Par conséquent, une applet de commande peut avoir besoin de définir son propre type, ou une applet de commande peut avoir besoin d’étendre un type existant fourni par une autre applet de commande. Pour plus d’informations sur la définition de nouveaux types ou l’extension de types existants, consultez Extension des types d’objets et de la mise en forme.

Génération de l’applet de commande

Après avoir implémenté une applet de commande, vous devez l’inscrire auprès de Windows PowerShell à l’aide d’un composant logiciel enfichable Windows PowerShell. Pour plus d’informations sur l’inscription d’applets de commande, consultez Guide pratique pour inscrire des applets de commande, des fournisseurs et des applications hôtes.

Test de l’applet de commande

Lorsque votre applet de commande est inscrite auprès de Windows PowerShell, vous pouvez la tester en l’exécutant sur la ligne de commande. Voici deux façons de tester le code de l’exemple d’applet de commande. Pour plus d’informations sur l’utilisation d’applets de commande à partir de la ligne de commande, consultez Prise en main de Windows PowerShell.

À l’invite Windows PowerShell, utilisez la commande suivante pour répertorier le processus Internet Explorer, nommé « IEXPLORE ».

Get-Proc -Name iexplore

La sortie suivante s’affiche.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----   ------ --   -----------
    354      11  10036   18992    85   0.67   3284   iexplore

Pour répertorier les processus Internet Explorer, Outlook et Bloc-notes nommés « IEXPLORE », « OUTLOOK » et « NOTEPAD », utilisez la commande suivante. S’il existe plusieurs processus, tous sont affichés.

Get-Proc -Name iexplore, outlook, notepad

La sortie suivante s’affiche.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----  ------   --   -----------
    732      21  24696    5000    138   2.25  2288   iexplore
    715      19  20556   14116    136   1.78  3860   iexplore
   3917      62  74096   58112    468 191.56  1848   OUTLOOK
     39       2   1024    3280     30   0.09  1444   notepad
     39       2   1024     356     30   0.08  3396   notepad