Delen via

Windows PowerShell-foutrecords

Cmdlets moeten een System.Management.Automation.ErrorRecord doorgeven object dat de foutvoorwaarde identificeert voor afsluit- en niet-afsluitfouten.

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

  • De uitzondering die de fout beschrijft. Dit is vaak een uitzondering dat de cmdlet is opgevangen en geconverteerd naar een foutrecord. Elke foutrecord moet een uitzondering bevatten.

Als de cmdlet geen uitzondering heeft onderscheppen, moet deze een nieuwe uitzondering maken en de uitzonderingsklasse kiezen die de foutvoorwaarde het beste beschrijft. U hoeft de uitzondering echter niet te genereren omdat deze toegankelijk is via de eigenschap System.Management.Automation.ErrorRecord.Exception van het System.Management.Automation.ErrorRecord-object.

  • Een fout-id die een gerichte ontwerpfunctie 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 ontwerpfunctie 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 Vervangend foutbericht).

  • 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 optrad. Dit kan het invoerobject zijn of een ander object dat door uw cmdlet is verwerkt. Voor de opdracht Remove-Item -Recurse C:\somedirectorykan de fout bijvoorbeeld een exemplaar zijn van een 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 waarmee de foutvoorwaarde in uw cmdlet wordt aangegeven. Windows PowerShell combineert de doel-id met de naam van uw cmdlet om een volledig gekwalificeerde fout-id te maken. De volledig gekwalificeerde fout-id kan worden geopend via de eigenschap System.Management.Automation.ErrorRecord.FullyQualifiedErrorId van het System.Management.Automation.ErrorRecord-object. 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 verwerken met specifieke fouthandlers. Een gebruiker moet de fout-id kunnen gebruiken om de fout en de bron ervan te identificeren. Fout-id's schakelen ook rapportage in voor specifieke foutvoorwaarden van bestaande uitzonderingen, zodat nieuwe uitzonderingssubklassen niet vereist zijn.

  • Wijs in het algemeen 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 in de regel een nieuwe id wanneer u een nieuwe sjabloontekenreeks definieert voor het foutbericht 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 vast met die id 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 verandert, maakt en gebruikt u vervolgens een nieuwe id.

  • Kies tekst voor uw fout-id die beknopt overeenkomt met de fout die u rapporteert. Gebruik standaard .NET Framework-naamgevings- en hoofdletterconventies. Gebruik geen spatie of leestekens. Lokaliseer fout-id's niet.

  • Genereer geen 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 weergegeven 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 opsomming. Windows PowerShell gebruikt de foutcategorie om foutinformatie weer te geven wanneer gebruikers de $ErrorView variabele instellen op "CategoryView".

Vermijd het gebruik van de System.Management.Automation.ErrorCategoryNotSpecified constante. 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 geen perfecte overeenkomst is.

De informatie die door Windows PowerShell wordt weergegeven, wordt de tekenreeks categorieweergave genoemd en is gebaseerd op de eigenschappen van de klasse System.Management.Automation.ErrorCategoryInfo. (Deze klasse wordt geopend via de fout System.Management.Automation.ErrorRecord.CategoryInfo eigenschap.)

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

In de volgende lijst worden de weergegeven gegevens beschreven:

  • Categorie: Een door Windows PowerShell gedefinieerde System.Management.Automation.ErrorCategory constante.

  • TargetName: standaard de naam van het object dat de cmdlet heeft verwerkt toen de fout optrad. Of een andere door cmdlet gedefinieerde tekenreeks.

  • TargetType: Standaard het type 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 is het uitzonderingstype. Of een andere door cmdlet gedefinieerde tekenreeks.

Vervangend foutbericht

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 foutopsporing (volgens de richtlijnen van .NET Framework). 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.

Het vervangende bericht moet voldoen aan de ontwerprichtlijnen van .NET Framework voor het schrijven van uitzonderingsberichten met een klein verschil. De richtlijnen geven aan 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 System.Management.Automation.Cmdlet.WriteError of System.Management.Automation.Cmdlet.ThrowTerminatingError* methoden 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, wordt in Windows PowerShell de eigenschap System.Management.Automation.ErrorDetails.Message* weergegeven in plaats van de standaardberichttekst.

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

Aanroepgegevens

Wanneer een cmdlet gebruikmaakt van System.Management.Automation.Cmdlet.WriteError of System.Management.Automation.Cmdlet.ThrowTerminatingError* om een foutrecord te melden, voegt Windows PowerShell automatisch informatie toe die de opdracht beschrijft die is aangeroepen toen de fout optrad. 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.

Zie ook

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.ErrorCategory-

System.Management.Automation.ErrorCategoryInfo

System.Management.Automation.ErrorRecord

System.Management.Automation.ErrorDetails

System.Management.Automation.InvocationInfo

Windows PowerShell-foutenrapportage

Een Windows PowerShell-cmdlet schrijven

  • Last updated on