Freigeben über

Hinzufügen von Berichten für Fehler ohne Abbruch zu Cmdlet

Cmdlets können nicht beendete Fehler melden, indem sie die System.Management.Automation.Cmdlet.WriteError-Methode aufrufen und weiterhin auf dem aktuellen Eingabeobjekt oder an weiteren eingehenden Pipelineobjekten arbeiten. In diesem Abschnitt wird erläutert, wie Sie ein Cmdlet erstellen, das nicht beendete Fehler aus den Eingabeverarbeitungsmethoden meldet.

Bei nicht beendeten Fehlern (sowie Abbruchfehlern) muss das Cmdlet ein System.Management.Automation.ErrorRecord Objekt übergeben, das den Fehler identifiziert. Jeder Fehlerdatensatz wird durch eine eindeutige Zeichenfolge namens "Fehlerbezeichner" identifiziert. Zusätzlich zum Bezeichner wird die Kategorie der einzelnen Fehler durch Konstanten angegeben, die durch eine System.Management.Automation.ErrorCategory Enumeration definiert werden. Der Benutzer kann Fehler basierend auf seiner Kategorie anzeigen, indem er die $ErrorView Variable auf "CategoryView" festlegt.

Weitere Informationen zu Fehlerdatensätzen finden Sie unter Windows PowerShell-Fehlerdatensätze.

Definieren des Cmdlets

Der erste Schritt beim Erstellen von Cmdlets ist immer das Benennen des Cmdlets und das Deklarieren der .NET-Klasse, die das Cmdlet implementiert. Dieses Cmdlet ruft Prozessinformationen ab, sodass der hier ausgewählte Verbname "Get" lautet. (Fast jede Art von Cmdlet, das Informationen abrufen kann, kann Befehlszeileneingaben verarbeiten.) Weitere Informationen zu genehmigten Cmdlet-Verben finden Sie unter Cmdlet Verb Names.

Es folgt die Definition für dieses Get-Proc-Cmdlet. Details zu dieser Definition werden in Creating Your First Cmdletangegeben.

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

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

Definieren von Parametern

Bei Bedarf muss das Cmdlet Parameter für die Verarbeitung von Eingaben definieren. Dieses Get-Proc-Cmdlet definiert einen parameter Name wie in Hinzufügen von Parametern beschrieben, die Command-Line Eingabeverarbeitet werden.

Dies ist die Parameterdeklaration für den parameter Name Parameter dieses Get-Proc Cmdlets.

[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

Überschreiben von Eingabeverarbeitungsmethoden

Alle Cmdlets müssen mindestens eine der Eingabeverarbeitungsmethoden außer Kraft setzen, die von der System.Management.Automation.Cmdlet Klasse bereitgestellt werden. Diese Methoden werden in Creating Your First Cmdleterläutert.

Hinweis

Ihr Cmdlet sollte jeden Datensatz so unabhängig wie möglich behandeln.

Mit diesem Get-Proc Cmdlet wird die System.Management.Automation.Cmdlet.ProcessRecord Methode außer Kraft gesetzt, um den parameter Name für eingaben durch den Benutzer oder ein Skript zu verarbeiten. Diese Methode ruft die Prozesse für jeden angeforderten Prozessnamen oder alle Prozesse ab, wenn kein Name angegeben wird. Details zu dieser Außerkraftsetzung werden in Creating Your First Cmdletangegeben.

Dinge, die beim Melden von Fehlern zu beachten sind

Das System.Management.Automation.ErrorRecord Objekt, das das Cmdlet beim Schreiben eines Fehlers übergibt, erfordert eine Ausnahme im Kern. Befolgen Sie die .NET-Richtlinien, wenn Sie die zu verwendende Ausnahme bestimmen. Wenn der Fehler semantisch mit einer vorhandenen Ausnahme identisch ist, sollte das Cmdlet diese Ausnahme verwenden oder ableiten. Andernfalls sollte eine neue Ausnahme- oder Ausnahmehierarchie direkt von der System.Exception Klasse abgeleitet werden.

Beachten Sie beim Erstellen von Fehlerbezeichnern (zugriff auf die FullyQualifiedErrorId-Eigenschaft der ErrorRecord-Klasse) Folgendes.

  • Verwenden Sie Zeichenfolgen, die für Diagnosezwecke vorgesehen sind, damit Sie bei der Überprüfung des vollqualifizierten Bezeichners bestimmen können, was der Fehler ist und wo der Fehler stammt.

  • Ein wohlgeformte vollqualifizierter Fehlerbezeichner kann wie folgt aussehen.

    CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

Beachten Sie, dass im vorherigen Beispiel der Fehlerbezeichner (das erste Token) angibt, was der Fehler ist, und der verbleibende Teil gibt an, wo der Fehler stammt.

  • Bei komplexeren Szenarien kann der Fehlerbezeichner ein punkttrenntes Token sein, das bei der Überprüfung analysiert werden kann. Auf diese Weise können Sie zu den Teilen des Fehlerbezeichners sowie der Fehler-ID und der Fehlerkategorie verzweigen.

Das Cmdlet sollte bestimmten Fehlerbezeichnern unterschiedliche Codepfade zuweisen. Beachten Sie die folgenden Informationen für die Zuweisung von Fehlerbezeichnern:

  • Ein Fehlerbezeichner sollte während des gesamten Lebenszyklus des Cmdlets konstant bleiben. Ändern Sie die Semantik eines Fehlerbezeichners nicht zwischen Cmdlet-Versionen.
  • Verwenden Sie Text für einen Fehlerbezeichner, der dem gemeldeten Fehler entspricht. Verwenden Sie keinen Leerraum oder Interpunktion.
  • Lassen Sie ihr Cmdlet nur Fehlerbezeichner generieren, die reproduzierbar sind. Beispielsweise sollte kein Bezeichner generiert werden, der einen Prozessbezeichner enthält. Fehlerbezeichner sind nur dann nützlich, wenn sie Bezeichnern entsprechen, die von anderen Benutzern angezeigt werden, die dasselbe Problem haben.

Nicht behandelte Ausnahmen werden in den folgenden Bedingungen von PowerShell nicht abgefangen:

  • Wenn ein Cmdlet einen neuen Thread erstellt und code, der in diesem Thread ausgeführt wird, eine unbehandelte Ausnahme auslöst, fängt PowerShell den Fehler nicht ab und beendet den Prozess.
  • Wenn ein Objekt Code in seinen Destruktor- oder Dispose-Methoden enthält, die eine unbehandelte Ausnahme verursachen, fängt PowerShell den Fehler nicht ab und beendet den Prozess.

Melden von nicht beendeten Fehlern

Eine der Eingabeverarbeitungsmethoden kann mithilfe der System.Management.Automation.Cmdlet.WriteError Methode einen nicht beendenden Fehler an den Ausgabedatenstrom melden.

Hier ist ein Codebeispiel aus diesem Get-Proc-Cmdlet, das den Aufruf von System.Management.Automation.Cmdlet.WriteError innerhalb der Außerkraftsetzung der System.Management.Automation.Cmdlet.ProcessRecord-Methode veranschaulicht. In diesem Fall wird der Aufruf ausgeführt, wenn das Cmdlet keinen Prozess für einen angegebenen Prozessbezeichner finden kann.

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
  }

Dinge, die sie beim Schreiben von Nichtbeendungsfehlern beachten sollten

Für einen nicht beendeten Fehler muss das Cmdlet einen bestimmten Fehlerbezeichner für jedes bestimmte Eingabeobjekt generieren.

Ein Cmdlet muss häufig die PowerShell-Aktion ändern, die durch einen nicht beendeten Fehler erzeugt wird. Dazu definieren Sie die Parameter ErrorAction und ErrorVariable. Wenn Sie den ErrorAction-Parameter definieren, stellt das Cmdlet die Benutzeroptionen System.Management.Automation.ActionPreferencedar, können Sie die Aktion auch direkt beeinflussen, indem Sie die $ErrorActionPreference Variable festlegen.

Das Cmdlet kann nicht beendete Fehler mithilfe des parameters ErrorVariable, die von der Einstellung von ErrorActionnicht betroffen ist, in einer Variablen speichern. Fehler können an eine vorhandene Fehlervariable angefügt werden, indem sie am Anfang des Variablennamens ein Pluszeichen (+) hinzufügen.

Codebeispiel

Den vollständigen C#-Beispielcode finden Sie unter GetProcessSample04-Beispiel-.

Definieren von Objekttypen und Formatierungen

PowerShell übergibt Informationen zwischen Cmdlets mithilfe von .NET-Objekten. Daher muss ein Cmdlet möglicherweise einen eigenen Typ definieren, oder das Cmdlet muss einen vorhandenen Typ erweitern, der von einem anderen Cmdlet bereitgestellt wird. Weitere Informationen zum Definieren neuer Typen oder zum Erweitern vorhandener Typen finden Sie unter Erweitern von Objekttypen und Formatierungen.

Erstellen des Cmdlets

Nach der Implementierung eines Cmdlets müssen Sie es über ein Windows PowerShell-Snap-In bei Windows PowerShell registrieren. Weitere Informationen zum Registrieren von Cmdlets finden Sie unter Registrieren von Cmdlets, Anbietern und Hostanwendungen.

Testen des Cmdlets

Wenn Ihr Cmdlet bei PowerShell registriert wurde, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Testen wir das Beispiel-Get-Proc-Cmdlet, um zu sehen, ob ein Fehler gemeldet wird:

  • Starten Sie PowerShell, und verwenden Sie das cmdlet Get-Proc, um die Prozesse mit dem Namen "TEST" abzurufen.

    Get-Proc -Name test

    Die folgende Ausgabe wird angezeigt.

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

Siehe auch

  • Last updated on