Windows PowerShell-felposter

Artikel
09/24/2021
4 minuter för att läsa

Cmdlets måste skicka ett System.Management.Automation.ErrorRecord-objekt som identifierar felvillkoret för avslutande och icke-avslutande fel.

Objektet System.Management.Automation.ErrorRecord innehåller följande information:

Undantaget som beskriver felet. Det här är ofta ett undantag som cmdleten fångat och konverterat till en felpost. Varje felpost måste innehålla ett undantag.

Om cmdleten inte fångar upp ett undantag måste den skapa ett nytt undantag och välja den undantagsklass som bäst beskriver feltillståndet. Du behöver dock inte skapa undantaget eftersom det kan nås via egenskapen System.Management.Automation.ErrorRecord.Exception för objektet System.Management.Automation.ErrorRecord.

En felidentifierare som tillhandahåller en riktad designator som kan användas för diagnostikändamål och Windows PowerShell skript för att hantera specifika felvillkor med specifika felhanterare. Varje felpost måste innehålla en felidentifierare (se Felidentifierare).
En felkategori som tillhandahåller en allmän designator som kan användas i diagnostiskt syfte. Varje felpost måste ange en felkategori (se Felkategori).
Ett valfritt ersättningsfelmeddelande och en rekommenderad åtgärd (se Ersättningsfelmeddelande).
Valfri anropsinformation om cmdleten som utbar felet. Den här informationen anges av Windows PowerShell (se Anropsmeddelande).
Målobjektet som bearbetades när felet inträffade. Det kan vara indataobjektet eller ett annat objekt som cmdleten bearbetar. För kommandot kan felet till exempel vara en instans av ett remove-item -recurse c:\somedirectory FileInfo-objekt för "c:\somedirectory\lockedfile". Målobjektinformationen är valfri.

Felidentifierare

När du skapar en felpost anger du en identifierare som anger feltillståndet i cmdleten. Windows PowerShell kombinerar målidentifieraren med namnet på din cmdlet för att skapa en fullständigt kvalificerad felidentifierare. Den fullständigt kvalificerade felidentifieraren kan nås via egenskapen System.Management.Automation.ErrorRecord.FullyQualifiedErrorId för objektet System.Management.Automation.ErrorRecord. Felidentifieraren är inte tillgänglig på egen hand. Den är endast tillgänglig som en del av den fullständigt kvalificerade felidentifieraren.

Använd följande riktlinjer för att generera felidentifierare när du skapar felposter:

Gör felidentifierare specifika för ett feltillstånd. Rikta felidentifierarna i diagnostiskt syfte och för skript som hanterar specifika felvillkor med specifika felhanterare. En användare ska kunna använda felidentifieraren för att identifiera felet och dess källa. Felidentifierare aktiverar även rapportering för specifika felvillkor från befintliga undantag så att nya undantagsunderklasser inte krävs.
Tilldela i allmänhet olika felidentifierare till olika kodsökvägar. Slutanvändaren drar nytta av specifika identifierare. Varje kodsökväg som anropar System.Management.Automation.Cmdlet.WriteError eller System.Management.Automation.Cmdlet.Throwterminatingerror* har ofta en egen identifierare. Definiera som regel en ny identifierare när du definierar en ny mallsträng för felmeddelandet och vice versa. Använd inte felmeddelandet som identifierare.
När du publicerar kod med en viss felidentifierare upprättar du semantiken för fel med den identifieraren för hela produktens supportlivscykel. Återanvänd den inte i en kontext som skiljer sig semantiskt från den ursprungliga kontexten. Om semantiken för det här felet ändras skapar du och använder sedan en ny identifierare.
Du bör vanligtvis endast använda en viss felidentifierare för undantag av en viss CLR-typ. Om typen av undantag eller typen för målobjektet ändras skapar du och använder sedan en ny identifierare.
Välj text för felidentifieraren som kort och koncist motsvarar det fel som du rapporterar. Använd standardkonventioner .NET Framework och versaler. Använd inte blanksteg eller skiljetecken. Lokalisera inte felidentifierare.
Generera inte felidentifierare dynamiskt på ett icke-reproducerbart sätt. Ta till exempel inte med felinformation, till exempel ett process-ID. Felidentifierare är bara användbara om de motsvarar felidentifierarna som visas av andra användare som har samma feltillstånd.

Felkategori

När du skapar en felpost anger du felkategorin med någon av de konstanter som definieras av uppräkningen System.Management.Automation.ErrorCategory. Windows PowerShell använder felkategorin för att visa felinformation när användare anger $ErrorView variabeln till "CategoryView" .

Undvik att använda konstanten System.Management.Automation.ErrorCategory NotSpecified. Om du har information om felet eller om åtgärden som orsakade felet väljer du den kategori som bäst beskriver felet eller åtgärden, även om kategorin inte är en perfekt matchning.

Informationen som visas Windows PowerShell kallas kategorivysträngen och bygger på egenskaperna för klassen System.Management.Automation.Errorcategoryinfo. (Den här klassen nås via felet Egenskapen System.Management.Automation.ErrorRecord.CategoryInfo.)

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

I följande lista beskrivs den information som visas:

Kategori: En Windows PowerShell system.Management.Automation.ErrorCategory-konstant.
TargetName: Som standard bearbetas namnet på objektet som cmdleten bearbetar när felet inträffade. Eller en annan cmdlet-definierad sträng.
TargetType: Målobjektets typ som standard. Eller en annan cmdlet-definierad sträng.
Aktivitet: Som standard namnet på cmdleten som skapade felposten. Eller någon annan cmdlet-definierad sträng.
Orsak: Som standard undantagstypen. Eller en annan cmdlet-definierad sträng.

Ersättningsfelmeddelande

När du utvecklar en felpost för en cmdlet kommer standardfelmeddelandet för felet från standardmeddelandetexten i egenskapen System.Exception.Message. Det här är en skrivskyddat egenskap vars meddelandetext endast är avsedd för felsökning (enligt riktlinjerna .NET Framework). Vi rekommenderar att du skapar ett felmeddelande som ersätter eller utökar standardmeddelandetexten. Gör meddelandet mer användarvänligt och mer specifikt för cmdleten.

Ersättningsmeddelandet tillhandahålls av ett System.Management.Automation.ErrorDetails-objekt. Använd någon av följande konstruktorer för det här objektet eftersom de tillhandahåller ytterligare lokaliseringsinformation som kan användas av Windows PowerShell.

ErrorDetails(Cmdlet, String, String, Object[]): Använd den här konstruktorn om din mallsträng är en resurssträng i samma sammansättning där cmdleten implementeras eller om du vill läsa in mallsträngen via en åsidosättning av metoden System.Management.Automation.Cmdlet.GetResourceString.
ErrorDetails(Assembly, String, String, Object[]): Använd den här konstruktorn om mallsträngen finns i en annan sammansättning och du inte läser in den via en åsidosättning av System.Management.Automation.Cmdlet.GetResourceString.

Ersättningsmeddelandet bör följa riktlinjerna för .NET Framework för att skriva undantagsmeddelanden med liten skillnad. Riktlinjerna säger att undantagsmeddelanden ska skrivas för utvecklare. Dessa ersättningsmeddelanden ska skrivas för cmdlet-användaren.

Ersättningsfelmeddelandet måste läggas till innan metoderna System.Management.Automation.Cmdlet.WriteError eller System.Management.Automation.Cmdlet.Throwterminatingerror* anropas. Om du vill lägga till ett ersättningsmeddelande anger du egenskapen System.Management.Automation.ErrorRecord.ErrorDetails för felposten. När den här egenskapen har angetts Windows PowerShell egenskapen System.Management.Automation.ErrorDetails.Message* i stället för standardmeddelandetexten.

Rekommenderad åtgärdsinformation

Objektet System.Management.Automation.ErrorDetails kan också ge information om vilka åtgärder som rekommenderas när felet inträffar.

Anropsinformation

När en cmdlet använder System.Management.Automation.Cmdlet.WriteError eller System.Management.Automation.Cmdlet.Throwterminatingerror* för att rapportera en felpost, lägger Windows PowerShell automatiskt till information som beskriver kommandot som anropades när felet inträffade. Den här informationen tillhandahålls av ett System.Management.Automation.Invocationinfo-objekt som innehåller namnet på cmdleten som anropades av kommandot, själva kommandot och information om pipelinen eller skriptet. Den här egenskapen är skrivskyddade.