Windows PowerShell-Fehlerdatensätze

Artikel
03/25/2025

Cmdlets müssen ein System.Management.Automation.ErrorRecord-Objekt übergeben, das die Fehlerbedingung für das Beenden und nicht beendende Fehler identifiziert.

Das System.Management.Automation.ErrorRecord-Objekt enthält die folgenden Informationen:

Die Ausnahme, die den Fehler beschreibt. Dies ist häufig eine Ausnahme, die das Cmdlet abgefangen und in einen Fehlerdatensatz konvertiert hat. Jeder Fehlerdatensatz muss eine Ausnahme enthalten.

Wenn das Cmdlet keine Ausnahme abfangen konnte, muss sie eine neue Ausnahme erstellen und die Ausnahmeklasse auswählen, die die Fehlerbedingung am besten beschreibt. Sie müssen die Ausnahme jedoch nicht auslösen, da über das System.Management.Automation.ErrorRecord.Exception-Eigenschaft des System.Management.Automation.ErrorRecord-Objekts zugegriffen werden kann.

Ein Fehlerbezeichner, der einen gezielten Kennzeichner bereitstellt, der für Diagnosezwecke und von Windows PowerShell-Skripts zur Behandlung bestimmter Fehlerbedingungen mit bestimmten Fehlerhandlern verwendet werden kann. Jeder Fehlerdatensatz muss einen Fehlerbezeichner enthalten (siehe Fehlerbezeichner).
Eine Fehlerkategorie, die einen allgemeinen Kennzeichner bereitstellt, der für Diagnosezwecke verwendet werden kann. Jeder Fehlerdatensatz muss eine Fehlerkategorie angeben (siehe Fehlerkategorie).
Eine optionale Ersetzungsfehlermeldung und eine empfohlene Aktion (siehe Ersetzungsfehlermeldung).
Optionale Aufrufinformationen zum Cmdlet, das den Fehler ausgelöst hat. Diese Informationen werden von Windows PowerShell angegeben (siehe Aufrufnachricht).
Das Zielobjekt, das beim Auftreten des Fehlers verarbeitet wurde. Dies kann das Eingabeobjekt oder ein anderes Objekt sein, das vom Cmdlet verarbeitet wurde. For example, for the command Remove-Item -Recurse C:\somedirectory, the error might be an instance of a FileInfo object for "C:\somedirectory\lockedfile". Die Zielobjektinformationen sind optional.

Fehlerbezeichner

Wenn Sie einen Fehlerdatensatz erstellen, geben Sie einen Bezeichner an, der die Fehlerbedingung innerhalb Des Cmdlets angibt. Windows PowerShell kombiniert den zielbezogenen Bezeichner mit dem Namen Des Cmdlets, um einen vollqualifizierten Fehlerbezeichner zu erstellen. Auf den vollqualifizierten Fehlerbezeichner kann über die System.Management.Automation.ErrorRecord.FullyQualifiedErrorId Eigenschaft des System.Management.Automation.ErrorRecord-Objekts zugegriffen werden. Der Fehlerbezeichner ist selbst nicht verfügbar. Sie ist nur als Teil des vollqualifizierten Fehlerbezeichners verfügbar.

Verwenden Sie die folgenden Richtlinien, um Fehlerbezeichner zu generieren, wenn Sie Fehlerdatensätze erstellen:

Machen Sie Fehlerbezeichner, die für eine Fehlerbedingung spezifisch sind. Richten Sie die Fehlerbezeichner für Diagnosezwecke und skripts aus, die bestimmte Fehlerbedingungen mit bestimmten Fehlerhandlern behandeln. Ein Benutzer sollte in der Lage sein, den Fehlerbezeichner zu verwenden, um den Fehler und seine Quelle zu identifizieren. Fehlerbezeichner ermöglichen auch die Berichterstellung für bestimmte Fehlerbedingungen aus vorhandenen Ausnahmen, sodass keine neuen Ausnahmeunterklassen erforderlich sind.
Weisen Sie im Allgemeinen verschiedenen Codepfaden unterschiedliche Fehlerbezeichner zu. Der Endbenutzer profitiert von bestimmten Bezeichnern. Häufig verfügt jeder Codepfad, der System.Management.Automation.Cmdlet.WriteError oder System.Management.Automation.Cmdlet.ThrowTerminatingError* aufruft, über einen eigenen Bezeichner. Definieren Sie in der Regel einen neuen Bezeichner, wenn Sie eine neue Vorlagenzeichenfolge für die Fehlermeldung definieren und umgekehrt. Verwenden Sie die Fehlermeldung nicht als Bezeichner.
Wenn Sie Code mit einem bestimmten Fehlerbezeichner veröffentlichen, richten Sie die Semantik von Fehlern mit diesem Bezeichner für den gesamten Produktsupportlebenszyklus ein. Verwenden Sie sie nicht in einem Kontext, der semantisch vom ursprünglichen Kontext abweicht. Wenn sich die Semantik dieses Fehlers ändert, erstellen Und verwenden Sie dann einen neuen Bezeichner.
In der Regel sollten Sie einen bestimmten Fehlerbezeichner nur für Ausnahmen eines bestimmten CLR-Typs verwenden. Wenn sich der Typ der Ausnahme oder der Typ des Zielobjekts ändert, erstellen Und verwenden Sie dann einen neuen Bezeichner.
Wählen Sie Text für ihren Fehlerbezeichner aus, der dem fehler entspricht, den Sie melden. Verwenden Sie standardmäßige .NET Framework-Benennungs- und Großschreibungskonventionen. Verwenden Sie keinen Leerraum oder Interpunktion. Fehlerbezeichner nicht lokalisieren.
Generieren Sie Fehlerbezeichner nicht dynamisch auf nicht reproduzierbare Weise. Integrieren Sie z. B. keine Fehlerinformationen wie eine Prozess-ID. Fehlerbezeichner sind nur hilfreich, wenn sie den Fehlerbezeichnern entsprechen, die von anderen Benutzern angezeigt werden, die dieselbe Fehlerbedingung aufweisen.

Fehlerkategorie

Wenn Sie einen Fehlerdatensatz erstellen, geben Sie die Kategorie des Fehlers mithilfe einer der durch die System.Management.Automation.ErrorCategory Enumeration definierten Konstanten an. Windows PowerShell verwendet die Fehlerkategorie, um Fehlerinformationen anzuzeigen, wenn Benutzer die variable $ErrorView auf "CategoryView"festlegen.

Vermeiden Sie die Verwendung der System.Management.Automation.ErrorCategoryNotSpecified Konstante. Wenn Sie Informationen zum Fehler oder zu dem Vorgang haben, der den Fehler verursacht hat, wählen Sie die Kategorie aus, die den Fehler oder den Vorgang am besten beschreibt, auch wenn die Kategorie keine perfekte Übereinstimmung ist.

Die von Windows PowerShell angezeigten Informationen werden als Kategorieansichtszeichenfolge bezeichnet und aus den Eigenschaften der System.Management.Automation.ErrorCategoryInfo Klasse erstellt. (Auf diese Klasse wird über den Fehler System.Management.Automation.ErrorRecord.CategoryInfo-Eigenschaft zugegriffen.)

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

In der folgenden Liste werden die angezeigten Informationen beschrieben:

Kategorie: Eine windows PowerShell-definierte System.Management.Automation.ErrorCategory Konstante.
TargetName: Standardmäßig wurde der Name des Objekts, das das Cmdlet verarbeitet hat, als der Fehler aufgetreten ist. Oder eine andere cmdletdefinierte Zeichenfolge.
TargetType: Standardmäßig der Typ des Zielobjekts. Oder eine andere cmdletdefinierte Zeichenfolge.
Aktivität: Standardmäßig der Name des Cmdlets, das den Fehlerdatensatz erstellt hat. Oder eine andere cmdletdefinierte Zeichenfolge.
Grund: Standardmäßig ist der Ausnahmetyp. Oder eine andere cmdletdefinierte Zeichenfolge.

Ersetzungsfehlermeldung

Wenn Sie einen Fehlerdatensatz für ein Cmdlet entwickeln, stammt die Standardfehlermeldung für den Fehler aus dem Standardmeldungstext in der System.Exception.Message-Eigenschaft. Dies ist eine schreibgeschützte Eigenschaft, deren Nachrichtentext nur für Debuggingzwecke (gemäß den .NET Framework-Richtlinien) vorgesehen ist. Es wird empfohlen, eine Fehlermeldung zu erstellen, die den Standardnachrichtentext ersetzt oder erweitert. Machen Sie die Nachricht benutzerfreundlicher und spezifischer für das Cmdlet.

Die Ersetzungsnachricht wird von einem System.Management.Automation.ErrorDetails-Objekt bereitgestellt. Verwenden Sie einen der folgenden Konstruktoren dieses Objekts, da sie zusätzliche Lokalisierungsinformationen bereitstellen, die von Windows PowerShell verwendet werden können.

ErrorDetails(Cmdlet, String, String, Object[]): Verwenden Sie diesen Konstruktor, wenn die Vorlagenzeichenfolge eine Ressourcenzeichenfolge in derselben Assembly ist, in der das Cmdlet implementiert wird, oder wenn Sie die Vorlagenzeichenfolge über eine Außerkraftsetzung der System.Management.Automation.Cmdlet.GetResourceString-Methode laden möchten.
ErrorDetails(Assembly, String, String, Object[]): Verwenden Sie diesen Konstruktor, wenn sich die Vorlagenzeichenfolge in einer anderen Assembly befindet und Sie sie nicht über eine Außerkraftsetzung von System.Management.Automation.Cmdlet.GetResourceStringladen.

Die Ersetzungsnachricht sollte den .NET Framework-Entwurfsrichtlinien für das Schreiben von Ausnahmemeldungen mit einem kleinen Unterschied entsprechen. Die Richtlinien geben an, dass Ausnahmemeldungen für Entwickler geschrieben werden sollen. Diese Ersetzungsmeldungen sollten für den Cmdlet-Benutzer geschrieben werden.

Die Ersetzungsfehlermeldung muss hinzugefügt werden, bevor die System.Management.Automation.Cmdlet.WriteError oder System.Management.Automation.Cmdlet.ThrowTerminatingError* Methoden aufgerufen werden. Um eine Ersatznachricht hinzuzufügen, legen Sie die System.Management.Automation.ErrorRecord.ErrorDetails Eigenschaft des Fehlerdatensatzes fest. Wenn diese Eigenschaft festgelegt ist, zeigt Windows PowerShell die System.Management.Automation.ErrorDetails.Message* Eigenschaft anstelle des Standardnachrichtentexts an.

Empfohlene Aktionsinformationen

Das System.Management.Automation.ErrorDetails Objekt kann auch Informationen darüber bereitstellen, welche Aktionen empfohlen werden, wenn der Fehler auftritt.

Aufrufinformationen

Wenn ein Cmdlet System.Management.Automation.Cmdlet.WriteError oder System.Management.Automation.Cmdlet.ThrowTerminatingError* verwendet, um einen Fehlerdatensatz zu melden, fügt Windows PowerShell automatisch Informationen hinzu, die den Befehl beschreiben, der beim Auftreten des Fehlers aufgerufen wurde. Diese Informationen werden von einem System.Management.Automation.InvocationInfo-Objekt bereitgestellt, das den Namen des Cmdlets enthält, das vom Befehl, dem Befehl selbst und Informationen über die Pipeline oder das Skript aufgerufen wurde. Diese Eigenschaft ist schreibgeschützt.