Cmdlet-foutrapportage
Cmdlets moeten fouten verschillend rapporteren, afhankelijk van of de fouten fouten of niet-beëindigingsfouten zijn. Beëindigingsfouten zijn fouten die ervoor zorgen dat de pijplijn onmiddellijk wordt beëindigd of fouten die optreden wanneer er geen reden is om door te gaan met verwerken. Niet-beëindigingsfouten zijn fouten die een huidige foutvoorwaarde rapporteren, maar de cmdlet kan invoerobjecten blijven verwerken. Bij niet-beëindigingsfouten wordt de gebruiker doorgaans op de hoogte gesteld van het probleem, maar de cmdlet blijft het volgende invoerobject verwerken.
Beëindigings- en niet-beëindigingsfouten
De volgende richtlijnen kunnen worden gebruikt om te bepalen of een foutvoorwaarde een beëindigingsfout of een niet-beëindigingsfout is.
Voorkomt de foutvoorwaarde dat de cmdlet verdere invoerobjecten kan verwerken? Als dat het zo is, is dit een eindfout.
Is de foutvoorwaarde gerelateerd aan een specifiek invoerobject of een subset van invoerobjecten? Als dat het zo is, is dit een niet-beëindigingsfout.
Accepteert de cmdlet meerdere invoerobjecten, zodat de verwerking kan slagen voor een ander invoerobject? Als dat het zo is, is dit een niet-beëindigingsfout.
Cmdlets die meerdere invoerobjecten kunnen accepteren, moeten bepalen wat beëindigings- en niet-beëindigingsfouten zijn, zelfs wanneer een bepaalde situatie alleen van toepassing is op één invoerobject.
Cmdlets kunnen elk aantal invoerobjecten ontvangen en een groot aantal succes- of foutobjecten verzenden voordat een beëindigings-uitzondering wordt veroorzaakt. Er is geen relatie tussen het aantal ontvangen invoerobjecten en het aantal verzonden succes- en foutobjecten.
Cmdlets die slechts 0-1 invoerobjecten kunnen accepteren en alleen 0-1 uitvoerobjecten genereren, moeten fouten behandelen als beëindigingsfouten en beëindigingsuitzonderingen genereren.
Niet-beëindigingsfouten rapporteren
De rapportage van een niet-beëindigingsfout moet altijd worden uitgevoerd binnen de implementatie van de cmdlet van de methode System.Management.Automation.Cmdlet.BeginProcessing, de methode System.Management.Automation.Cmdlet.ProcessRecord of de methode System.Management.Automation.Cmdlet.EndProcessing. Deze typen fouten worden gerapporteerd door de methode System.Management.Automation.Cmdlet.WriteError aan te roepen die op zijn beurt een foutrecord naar de foutstroom verzendt.
Rapporteren van beëindigingsfouten
Beëindigingsfouten worden gerapporteerd door uitzonderingen te veroorzaken of door de methode System.Management.Automation.Cmdlet.ThrowTerminatingError aan te roepen. Let op: cmdlets kunnen ook uitzonderingen als OutOfMemory ondervangen en opnieuw rijgen, maar ze zijn niet vereist voor het opnieuw rijgen van uitzonderingen, aangezien ze ook door de PowerShell-runtime worden ondervangen.
U kunt ook uw eigen uitzonderingen definiëren voor problemen die specifiek zijn voor uw situatie of aanvullende informatie toevoegen aan een bestaande uitzondering met behulp van de foutrecord.
Foutrecords
PowerShell beschrijft een niet-beëindigende foutvoorwaarde met System.Management.Automation.ErrorRecord-objecten. Elk object biedt informatie over de foutcategorie, een optioneel doelobject en details over de foutvoorwaarde.
Fout-id's
De fout-id is een eenvoudige tekenreeks die de foutvoorwaarde in de cmdlet identificeert. PowerShell combineert deze id met een cmdlet-id om een volledig gekwalificeerde fout-id te maken die later kan worden gebruikt bij het filteren van foutstromen of logboekregistratiefouten, bij het reageren op specifieke fouten of bij andere gebruikersspecifieke activiteiten.
De volgende richtlijnen moeten worden gevolgd bij het opgeven van fout-id's:
Wijs verschillende, zeer specifieke fout-id's toe aan verschillende codepaden. Elk codepad dat System.Management.Automation.Cmdlet.WriteError of System.Management.Automation.Cmdlet.ThrowTerminatingError aanroept, moet een eigen fout-id hebben.
Fout-id's moeten uniek zijn voor CLR-uitzonderingstypen (Common Language Runtime) voor zowel beëindigings- als niet-beëindigingsfouten.
Wijzig de semantiek van een fout-id niet tussen versies van uw cmdlet of PowerShell-provider. Nadat de semantiek van een fout-id tot stand is gebracht, moet deze gedurende de levenscyclus van uw cmdlet constant blijven.
Gebruik voor het beëindigen van fouten een unieke fout-id voor een bepaald CLR-uitzonderingstype. Als het uitzonderingstype wordt gewijzigd, gebruikt u een nieuwe fout-id.
Gebruik voor niet-beëindigingsfouten een specifieke fout-id voor een specifiek invoerobject.
Kies tekst voor de id die overeenkomt met de fout die wordt gerapporteerd. Gebruik geen witruimte of leestekens.
Genereer geen fout-id's die niet reproduceerbaar zijn. Genereer bijvoorbeeld geen id's die een proces-id bevatten. Fout-id's zijn alleen nuttig wanneer ze overeenkomen met id's die worden gezien door andere gebruikers die hetzelfde probleem ondervinden.
Foutcategorieën
Foutcategorieën worden gebruikt om fouten voor de gebruiker te groeperen. PowerShell definieert deze categorieën en cmdlets en PowerShell-providers moeten kiezen tussen deze categorieën bij het genereren van de foutrecord.
Zie de system.Management.Automation.ErrorCategory-enumeratie voor een beschrijving van de beschikbare foutcategorieën. Over het algemeen moet u het gebruik van NoError, UndefinedError en GenericError zoveel mogelijk vermijden.
Gebruikers kunnen fouten bekijken op basis van categorie wanneer ze zijn $ErrorView ingesteld op CategoryView.
Zie ook
Feedback
Feedback verzenden en weergeven voor