Windows PowerShell-foutrecords

Artikel
09/24/2021

Cmdlets moeten een System.Management.Automation.ErrorRecord-object doorgeven dat de foutvoorwaarde identificeert voor het beëindigen en niet-beëindigen van fouten.

Het object System.Management.Automation.ErrorRecord bevat de volgende informatie:

De uitzondering die de fout beschrijft. Dit is vaak een uitzondering die de cmdlet heeft opgeslagen en geconverteerd naar een foutrecord. Elke foutrecord moet een uitzondering bevatten.

Als de cmdlet geen uitzondering heeft ondervangen, moet er een nieuwe uitzondering worden gemaakt en moet de uitzonderingsklasse worden gekozen die de foutvoorwaarde het beste beschrijft. U hoeft de uitzondering echter niet te verwijderen omdat deze toegankelijk is via de eigenschap System.Management.Automation.ErrorRecord.Exception van het object System.Management.Automation.ErrorRecord.

Een fout-id die een gerichte ontwerpator biedt die kan worden gebruikt voor diagnostische doeleinden en door Windows PowerShell-scripts voor het afhandelen van specifieke foutvoorwaarden met specifieke fouthandlers. Elke foutrecord moet een fout-id bevatten (zie Fout-id).
Een foutcategorie die een algemene ontwerpator biedt die kan worden gebruikt voor diagnostische doeleinden. Elke foutrecord moet een foutcategorie opgeven (zie Foutcategorie).
Een optioneel vervangend foutbericht en een aanbevolen actie (zie Vervangingsfoutbericht).
Optionele aanroepinformatie over de cmdlet die de fout heeft veroorzaakt. Deze informatie wordt opgegeven door Windows PowerShell (zie Aanroepbericht).
Het doelobject dat werd verwerkt toen de fout zich voordeed. Dit kan het invoerobject zijn of een ander object dat door uw cmdlet is verwerkt. Voor de opdracht kan de fout bijvoorbeeld een exemplaar zijn van een remove-item -recurse c:\somedirectory FileInfo-object voor 'c:\somedirectory\lockedfile'. De informatie over het doelobject is optioneel.

Fout-id

Wanneer u een foutrecord maakt, geeft u een id op die de foutvoorwaarde in uw cmdlet aanwijzen. Windows PowerShell doel-id combineert met de naam van uw cmdlet om een volledig gekwalificeerde fout-id te maken. De volledig gekwalificeerde fout-id is toegankelijk via de eigenschap System.Management.Automation.ErrorRecord.FullyQualifiedErrorId van het object System.Management.Automation.ErrorRecord. De fout-id is zelf niet beschikbaar. Deze is alleen beschikbaar als onderdeel van de volledig gekwalificeerde fout-id.

Gebruik de volgende richtlijnen om fout-id's te genereren wanneer u foutrecords maakt:

Maak fout-id's specifiek voor een foutvoorwaarde. Richt u op de fout-id's voor diagnostische doeleinden en voor scripts die specifieke foutvoorwaarden met specifieke fout-handlers verwerken. Een gebruiker moet de fout-id kunnen gebruiken om de fout en de bron te identificeren. Fout-id's maken ook rapportage mogelijk voor specifieke foutvoorwaarden van bestaande uitzonderingen, zodat er geen nieuwe uitzonderingssubklassen nodig zijn.
In het algemeen wijst u verschillende fout-id's toe aan verschillende codepaden. De eindgebruiker profiteert van specifieke id's. Vaak heeft elk codepad dat System.Management.Automation.Cmdlet.WriteError of System.Management.Automation.Cmdlet.Throwterminatingerror* aanroept, een eigen id. Definieer als regel een nieuwe id wanneer u een nieuwe sjabloonreeks voor het foutbericht definieert en vice versa. Gebruik het foutbericht niet als id.
Wanneer u code publiceert met behulp van een bepaalde fout-id, stelt u de semantiek van fouten met die id in voor de volledige levenscyclus van productondersteuning. Gebruik deze niet opnieuw in een context die semantisch verschilt van de oorspronkelijke context. Als de semantiek van deze fout verandert, maakt u een nieuwe id en gebruikt u deze.
Over het algemeen moet u een bepaalde fout-id alleen gebruiken voor uitzonderingen van een bepaald CLR-type. Als het type uitzondering of het type van het doelobject wordt gewijzigd, maakt en gebruikt u vervolgens een nieuwe id.
Kies tekst voor uw fout-id die beknopt overeenkomt met de fout die u rapporteert. Gebruik standaardconvent .NET Framework naamgeving en hoofdlettergebruik. Gebruik geen witruimte of leestekens. Lokaliseer geen fout-id's.
Genereer niet dynamisch fout-id's op een niet-reproduceerbare manier. Neem bijvoorbeeld geen foutgegevens op, zoals een proces-id. Fout-id's zijn alleen nuttig als ze overeenkomen met de fout-id's die worden gezien door andere gebruikers die dezelfde foutvoorwaarde ondervinden.

Foutcategorie

Wanneer u een foutrecord maakt, geeft u de categorie van de fout op met behulp van een van de constanten die zijn gedefinieerd door de system.Management.Automation.ErrorCategory-definitie. Windows PowerShell gebruikt de foutcategorie om foutgegevens weer te geven wanneer gebruikers de variabele $ErrorView instellen op "CategoryView" .

Vermijd het gebruik van de constante System.Management.Automation.ErrorCategory NotSpecified. Als u informatie hebt over de fout of over de bewerking die de fout heeft veroorzaakt, kiest u de categorie die de fout of de bewerking het beste beschrijft, zelfs als de categorie niet perfect overeenkomen.

De informatie die door Windows PowerShell wordt aangeduid als de categorieweergavereeks en is opgebouwd uit de eigenschappen van de klasse System.Management.Automation.Errorcategoryinfo. (Deze klasse is toegankelijk via de fout de eigenschap System.Management.Automation.ErrorRecord.CategoryInfo.)

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

In de volgende lijst wordt de weergegeven informatie beschreven:

Categorie: Een door Windows PowerShell gedefinieerde constante System.Management.Automation.ErrorCategory.
TargetName: de naam van het object dat door de cmdlet werd verwerkt toen de fout zich voordeed. Of een andere door cmdlet gedefinieerde tekenreeks.
TargetType: standaard het type van het doelobject. Of een andere door cmdlet gedefinieerde tekenreeks.
Activiteit: standaard de naam van de cmdlet die de foutrecord heeft gemaakt. Of een andere door cmdlet gedefinieerde tekenreeks.
Reden: standaard het uitzonderingstype. Of een andere door cmdlet gedefinieerde tekenreeks.

Vervangingsfoutbericht

Wanneer u een foutrecord voor een cmdlet ontwikkelt, is het standaardfoutbericht voor de fout afkomstig van de standaardberichttekst in de eigenschap System.Exception.Message. Dit is een alleen-lezen eigenschap waarvan de berichttekst alleen is bedoeld voor het debuggen (volgens de .NET Framework richtlijnen). U wordt aangeraden een foutbericht te maken dat de standaardberichttekst vervangt of vergroot. Maak het bericht gebruiksvriendelijker en specifieker voor de cmdlet.

Het vervangende bericht wordt geleverd door een System.Management.Automation.ErrorDetails-object. Gebruik een van de volgende constructors van dit object, omdat ze aanvullende lokalisatiegegevens bieden die kunnen worden gebruikt door Windows PowerShell.

ErrorDetails(Cmdlet, String, String, Object[]): gebruik deze constructor als uw sjabloontekenreeks een resourcetekenreeks is in dezelfde assembly waarin de cmdlet is geïmplementeerd of als u de sjabloontekenreeks wilt laden via een overschrijvingen van de System.Management.Automation.Cmdlet.GetResourceString-methode.
ErrorDetails(Assembly, String, String, Object[]): gebruik deze constructor als de sjabloontekenreeks zich in een andere assembly en u deze niet laadt via een overschrijvingen van System.Management.Automation.Cmdlet.GetResourceString.

Het vervangende bericht moet voldoen aan .NET Framework ontwerprichtlijnen voor het schrijven van uitzonderingsberichten met een klein verschil. In de richtlijnen staat dat uitzonderingsberichten moeten worden geschreven voor ontwikkelaars. Deze vervangende berichten moeten worden geschreven voor de cmdlet-gebruiker.

Het vervangende foutbericht moet worden toegevoegd voordat de methoden System.Management.Automation.Cmdlet.WriteError of System.Management.Automation.Cmdlet.Throwterminatingerror* worden aangeroepen. Als u een vervangend bericht wilt toevoegen, stelt u de eigenschap System.Management.Automation.ErrorRecord.ErrorDetails van de foutrecord in. Wanneer deze eigenschap is ingesteld, Windows PowerShell de eigenschap System.Management.Automation.ErrorDetails.Message* weergegeven in plaats van de standaardberichttekst.

Aanbevolen actie-informatie

Het object System.Management.Automation.ErrorDetails kan ook informatie bieden over welke acties worden aanbevolen wanneer de fout optreedt.

Informatie over aanroepen

Wanneer een cmdlet System.Management.Automation.Cmdlet.WriteError of System.Management.Automation.Cmdlet.Throwterminatingerror* gebruikt om een foutrecord te rapporteren, voegt Windows PowerShell automatisch informatie toe die de opdracht beschrijft die is aangeroepen toen de fout zich voordeed. Deze informatie wordt verstrekt door een System.Management.Automation.Invocationinfo-object dat de naam bevat van de cmdlet die is aangeroepen door de opdracht, de opdracht zelf en informatie over de pijplijn of het script. Deze eigenschap is alleen-lezen.