Partager via

Ajout de rapport d’erreurs sans fin d’exécution à votre applet de commande

Les applets de commande peuvent signaler des erreurs sans fin en appelant la méthode System.Management.Automation.Cmdlet.WriteError et continuer à fonctionner sur l’objet d’entrée actuel ou sur d’autres objets de pipeline entrants. Cette section explique comment créer une applet de commande qui signale des erreurs sans fin à partir de ses méthodes de traitement d’entrée.

Pour les erreurs de non-fin (ainsi que pour les erreurs de fin), l’applet de commande doit passer un System.Management.Automation.ErrorRecord objet identifiant l’erreur. Chaque enregistrement d’erreur est identifié par une chaîne unique appelée « identificateur d’erreur ». En plus de l’identificateur, la catégorie de chaque erreur est spécifiée par des constantes définies par une énumération System.Management.Automation.ErrorCategory. L’utilisateur peut afficher les erreurs en fonction de sa catégorie en définissant la variable $ErrorView sur « CategoryView ».

Pour plus d’informations sur les enregistrements d’erreurs, consultez enregistrements d’erreurs Windows PowerShell.

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. Cette applet de commande récupère les informations de processus. 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éfinition de cette applet de commande Get-Proc. Les détails de cette définition sont indiqués 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éfinition des paramètres

Si nécessaire, votre applet de commande doit définir des paramètres pour le traitement de l’entrée. Cette applet de commande Get-Proc définit un paramètre Name, comme décrit dans Ajout de paramètres qui traitent Command-Lined’entrée.

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

[Parameter(
           Position = 0,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true
)]
[ValidateNotNullOrEmpty]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

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

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

End Property

Substitution des méthodes de traitement d’entrée

Toutes les applets de commande doivent remplacer au moins l’une des méthodes de traitement d’entrée fournies par la classe System.Management.Automation.Cmdlet. Ces méthodes sont décrites dans Création de votre première applet de commande.

Remarque

Votre applet de commande doit gérer chaque enregistrement de manière aussi indépendante que possible.

Cette applet de commande Get-Proc remplace la méthode System.Management.Automation.Cmdlet.ProcessRecord pour gérer le paramètre Name pour l’entrée 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. Les détails de ce remplacement sont indiqués dans Création de votre première applet de commande.

Éléments à mémoriser lors de la création de rapports d’erreurs

L’objet System.Management.Automation.ErrorRecord que l’applet de commande transmet lors de l’écriture d’une erreur nécessite une exception à son cœur. Suivez les instructions .NET lors de la détermination de l’exception à utiliser. En fait, si l’erreur est sémantiquement identique à une exception existante, l’applet de commande doit utiliser ou dériver de cette exception. Sinon, il doit dériver une nouvelle hiérarchie d’exception ou d’exception directement à partir de la classe System.Exception.

Lors de la création d’identificateurs d’erreur (accessible via la propriété FullyQualifiedErrorId de la classe ErrorRecord), gardez à l’esprit ce qui suit.

  • Utilisez des chaînes ciblées à des fins de diagnostic afin que lors de l’inspection de l’identificateur qualifié complet, vous puissiez déterminer l’erreur et l’emplacement de l’erreur.

  • Un identificateur d’erreur complet bien formé peut être le suivant.

    CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

Notez que dans l’exemple précédent, l’identificateur d’erreur (le premier jeton) désigne l’erreur et la partie restante indique l’emplacement de l’erreur.

  • Pour les scénarios plus complexes, l’identificateur d’erreur peut être un jeton séparé par un point qui peut être analysé lors de l’inspection. Cela vous permet également de créer une branche sur les parties de l’identificateur d’erreur, ainsi que l’identificateur d’erreur et la catégorie d’erreur.

L’applet de commande doit affecter des identificateurs d’erreur spécifiques à différents chemins de code. Gardez à l’esprit les informations suivantes pour l’affectation des identificateurs d’erreur :

  • Un identificateur d’erreur doit rester constant tout au long du cycle de vie de l’applet de commande. Ne modifiez pas la sémantique d’un identificateur d’erreur entre les versions de l’applet de commande.
  • Utilisez du texte pour un identificateur d’erreur qui correspond de manière terse à l’erreur signalée. N’utilisez pas d’espace blanc ou de ponctuation.
  • Votre applet de commande génère uniquement des identificateurs d’erreur reproductibles. Par exemple, il ne doit pas générer d’identificateur qui inclut un identificateur de processus. Les identificateurs d’erreur sont utiles à un utilisateur uniquement lorsqu’il correspond à des identificateurs qui sont vus par d’autres utilisateurs qui rencontrent le même problème.

Les exceptions non gérées ne sont pas interceptées par PowerShell dans les conditions suivantes :

  • Si une applet de commande crée un thread et un code en cours d’exécution dans ce thread lève une exception non gérée, PowerShell ne intercepte pas l’erreur et met fin au processus.
  • Si un objet a du code dans son destructeur ou ses méthodes Dispose qui provoquent une exception non gérée, PowerShell n’intercepte pas l’erreur et termine le processus.

Signalement d’erreurs sans fin

Une des méthodes de traitement d’entrée peut signaler une erreur sans fin au flux de sortie à l’aide de la méthode System.Management.Automation.Cmdlet.WriteError.

Voici un exemple de code de cette applet de commande Get-Proc qui illustre l’appel à System.Management.Automation.Cmdlet.WriteError à partir du remplacement de la méthode System.Management.Automation.Cmdlet.ProcessRecord. Dans ce cas, l’appel est effectué si l’applet de commande ne trouve pas de processus pour un identificateur de processus spécifié.

protected override void ProcessRecord()
{
  // If no name parameter passed to cmdlet, get all processes.
  if (processNames == null)
  {
    WriteObject(Process.GetProcesses(), true);
  }
    else
    {
      // If a name parameter is passed to cmdlet, get and write
      // the associated processes.
      // Write a non-terminating error for failure to retrieve
      // a process.
      foreach (string name in processNames)
      {
        Process[] processes;

        try
        {
          processes = Process.GetProcessesByName(name);
        }
        catch (InvalidOperationException ex)
        {
          WriteError(new ErrorRecord(
                     ex,
                     "NameNotFound",
                     ErrorCategory.InvalidOperation,
                     name));
          continue;
        }

        WriteObject(processes, true);
      } // foreach (...
    } // else
  }

Éléments à mémoriser concernant l’écriture d’erreurs sans fin

Pour une erreur sans fin, l’applet de commande doit générer un identificateur d’erreur spécifique pour chaque objet d’entrée spécifique.

Une applet de commande doit fréquemment modifier l’action PowerShell produite par une erreur sans fin. Pour ce faire, définissez les paramètres ErrorAction et ErrorVariable. Si vous définissez le paramètre ErrorAction, l’applet de commande présente les options utilisateur System.Management.Automation.ActionPreference, vous pouvez également influencer directement l’action en définissant la variable $ErrorActionPreference.

L’applet de commande peut enregistrer des erreurs sans fin dans une variable à l’aide du paramètre ErrorVariable, qui n’est pas affecté par le paramètre de ErrorAction. Les échecs peuvent être ajoutés à une variable d’erreur existante en ajoutant un signe plus (+) au début du nom de la variable.

Exemple de code

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

Définir les types d’objets et la mise en forme

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 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 via 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 a été inscrite auprès de PowerShell, vous pouvez la tester en l’exécutant sur la ligne de commande. Testons l’exemple d’applet de commande Get-Proc pour voir s’il signale une erreur :

  • Démarrez PowerShell et utilisez l’applet de commande Get-Proc pour récupérer les processus nommés « TEST ».

    Get-Proc -Name test

    La sortie suivante s’affiche.

    Get-Proc : Operation is not valid due to the current state of the object.
At line:1 char:9
+ Get-Proc  <<<< -Name test

Voir aussi

  • Last updated on