Ajout d’alias, d’une extension de caractère générique et d’une aide aux paramètres des applets de commande

  • Article

Cette section explique comment ajouter des alias, une extension générique et des messages d’aide aux paramètres de l’applet Stop-Proc de commande (décrit dans Création d’une applet de commande qui modifie le système).

Cette Stop-Proc applet de commande tente d’arrêter les processus récupérés à l’aide de l’applet Get-Proc de commande (décrite dans Création de votre première applet de commande).

Définition de l’applet de commande

La première étape de la création de l’applet de commande consiste toujours à nommer l’applet de commande et à déclarer la classe .NET qui implémente l’applet de commande. Étant donné que vous écrivez une applet de commande pour modifier le système, elle doit être nommée en conséquence. Étant donné que cette applet de commande arrête les processus système, elle utilise le verbe Stop, défini par la classe System.Management.Automation.Verbslifecycle , avec le nom Proc pour indiquer le processus. Pour plus d’informations sur les verbes d’applet de commande approuvés, consultez Noms des verbes d’applet de commande.

Le code suivant est la définition de classe de cette Stop-Proc applet de commande.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

Définition des paramètres pour la modification système

Votre applet de commande doit définir des paramètres qui prennent en charge les modifications système et les commentaires des utilisateurs. L’applet de commande doit définir un paramètre Name ou équivalent afin que l’applet de commande puisse modifier le système par un certain type d’identificateur. En outre, l’applet de commande doit définir les paramètres Force et PassThru . Pour plus d’informations sur ces paramètres, consultez Création d’une applet de commande qui modifie le système.

Définition d’un alias de paramètre

Un alias de paramètre peut être un autre nom ou un nom court de 1 lettre ou 2 lettres bien défini pour un paramètre d’applet de commande. Dans les deux cas, l’objectif d’utiliser des alias consiste à simplifier l’entrée utilisateur à partir de la ligne de commande. Windows PowerShell prend en charge les alias de paramètres via l’attribut System.Management.Automation.Aliasattribute, qui utilise la syntaxe [Alias()]de déclaration .

Le code suivant montre comment un alias est ajouté au paramètre Name .

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

Outre l’utilisation de l’attribut System.Management.Automation.Aliasattribute, le runtime Windows PowerShell effectue une correspondance de nom partiel, même si aucun alias n’est spécifié. Par exemple, si votre applet de commande a un paramètre FileName et qu’il s’agit du seul paramètre qui commence par F, l’utilisateur peut entrer Filename, Filenam``File, , ou Fi``F encore reconnaître l’entrée en tant que paramètre FileName.

Création d’aide pour les paramètres

Windows PowerShell vous permet de créer de l’aide pour les paramètres d’applet de commande. Pour tout paramètre utilisé pour la modification système et les commentaires des utilisateurs, procédez ainsi. Pour chaque paramètre qui prend en charge l’aide, vous pouvez définir le mot clé d’attribut HelpMessage dans la déclaration d’attribut System.Management.Automation.Parameterattribute . Ce mot clé définit le texte à afficher à l’utilisateur pour obtenir de l’aide à l’aide du paramètre. Vous pouvez également définir le mot clé HelpMessageBaseName pour identifier le nom de base d’une ressource à utiliser pour le message. Si vous définissez ce mot clé, vous devez également définir le mot clé HelpMessageResourceId pour spécifier l’identificateur de ressource.

Le code suivant de cette Stop-Proc applet de commande définit le mot clé d’attribut HelpMessage pour le paramètre Name .

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

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

Votre applet de commande doit remplacer une méthode de traitement d’entrée, la plupart du temps, il s’agit de System.Management.Automation.Cmdlet.ProcessRecord. Lors de la modification du système, l’applet de commande doit appeler les méthodes System.Management.Automation.Cmdlet.ShouldProcess et System.Management.Automation.Cmdlet.ShouldContinue pour permettre à l’utilisateur de fournir des commentaires avant qu’une modification ne soit apportée. Pour plus d’informations sur ces méthodes, consultez Création d’une applet de commande qui modifie le système.

Prise en charge de l’extension générique

Pour autoriser la sélection de plusieurs objets, votre applet de commande peut utiliser les classes System.Management.Automation.WildcardPattern et System.Management.Automation.WildcardOptions pour fournir une prise en charge de l’extension générique pour l’entrée de paramètre. Les exemples de modèles génériques sont lsa*, *.txtet [a-c]*. Utilisez le caractère de guillemet précédent (`) comme caractère d’échappement lorsque le modèle contient un caractère qui doit être utilisé littéralement.

Les extensions génériques des noms de fichiers et de chemins sont des exemples de scénarios courants dans lesquels l’applet de commande peut autoriser la prise en charge des entrées de chemin lorsque la sélection de plusieurs objets est requise. Un cas courant se trouve dans le système de fichiers, où un utilisateur souhaite voir tous les fichiers résidant dans le dossier actuel.

Vous devez avoir besoin d’une implémentation de mise en correspondance générique personnalisée uniquement rarement. Dans ce cas, votre applet de commande doit prendre en charge la spécification POSIX 1003.2 complète, 3.13 pour l’expansion générique ou le sous-ensemble simplifié suivant :

  • Point d’interrogation (?). Correspond à n’importe quel caractère à l’emplacement spécifié.
  • Astérisque (*). Correspond à zéro ou plusieurs caractères commençant à l’emplacement spécifié.
  • Crochet ouvert ([). Introduit une expression de crochet de modèle qui peut contenir des caractères ou une plage de caractères. Si une plage est requise, un trait d’union (-) est utilisé pour indiquer la plage.
  • Crochet fermé (]). Termine une expression de crochet de modèle.
  • Caractère d’échappement de guillemets précédents (`). Indique que le caractère suivant doit être pris littéralement. N’oubliez pas que lorsque vous spécifiez le caractère de guillemet précédent à partir de la ligne de commande (par opposition à la spécification par programmation), le caractère d’échappement back-quote doit être spécifié deux fois.

Notes

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

Le code suivant montre comment définir des options génériques et définir le modèle générique utilisé pour résoudre le paramètre Name de cette applet de commande.

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

Le code suivant montre comment tester si le nom du processus correspond au modèle générique défini. Notez que, dans ce cas, si le nom du processus ne correspond pas au modèle, l’applet de commande continue d’obtenir le nom du processus suivant.

if (!wildcard.IsMatch(processName))
{
  continue;
}

Exemple de code

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

Définir des types d’objets et une mise en forme

Windows PowerShell transmet des informations entre les applets de commande à l’aide d’objets .Net. Par conséquent, une applet de commande peut avoir besoin de définir son propre type, ou l’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 mise en forme.

Génération de l’applet de commande

Après avoir implémenté une applet de commande, elle doit être inscrite auprès de Windows PowerShell via un composant logiciel enfichable Windows PowerShell. Pour plus d’informations sur l’inscription des 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 a été inscrite auprès de Windows PowerShell, vous pouvez la tester en l’exécutant sur la ligne de commande. Testons l’exemple d’applet de commande Stop-Proc. Pour plus d’informations sur l’utilisation d’applets de commande à partir de la ligne de commande, consultez le Prise en main avec Windows PowerShell.

  • Démarrez Windows PowerShell et utilisez Stop-Proc pour arrêter un processus à l’aide de l’alias ProcessName pour le paramètre Name.

    PS> Stop-Proc -ProcessName notepad

    La sortie suivante apparaît.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (3496)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

  • Effectuez l’entrée suivante sur la ligne de commande. Étant donné que le paramètre Name est obligatoire, vous y êtes invité. La saisie !? affiche le texte d’aide associé au paramètre.

    PS> Stop-Proc

    La sortie suivante apparaît.

    Cmdlet Stop-Proc at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
Name[0]: !?
The name of one or more processes to stop. Wildcards are permitted.
Name[0]: notepad

  • Maintenant, effectuez l’entrée suivante pour arrêter tous les processus qui correspondent au modèle *note*générique. Vous êtes invité avant d’arrêter chaque processus qui correspond au modèle.

    PS> Stop-Proc -Name *note*

    La sortie suivante apparaît.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (1112)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

    La sortie suivante apparaît.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTEM (3712)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

    La sortie suivante apparaît.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTE (3592)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

Voir aussi