Dela via

Windows PowerShell-felposter

Cmdletar 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ångade och konverterade till en felpost. Varje felpost måste innehålla ett undantag.

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

  • En felidentifierare som tillhandahåller en riktad designator som kan användas för diagnostiska ändamål och av Windows PowerShell-skript för att hantera specifika feltillstånd 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 för diagnostikändamål. 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 utlöste felet. Den här informationen anges av Windows PowerShell (se Meddelande om anrop).

  • Målobjektet som bearbetades när felet inträffade. Det kan vara indataobjektet eller ett annat objekt som cmdleten bearbetade. För kommandot Remove-Item -Recurse C:\somedirectorykan felet till exempel vara en instans av ett FileInfo-objekt för "C:\somedirectory\lockedfile". Målobjektinformationen är valfri.

Felidentifierare

När du skapar en felpost anger du en identifierare som anger felvillkoret i din cmdlet. 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 egenskapen System.Management.Automation.ErrorRecord-objektet. 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 felvillkor. Rikta in dig på felidentifierarna för diagnostiska ändamål och för skript som hanterar specifika felvillkor med specifika felhanterare. En användare bör kunna använda felidentifieraren för att identifiera felet och dess källa. Felidentifierare aktiverar också rapportering för specifika felvillkor från befintliga undantag så att nya undantagsunderklasser inte krävs.

  • I allmänhet tilldelar du olika felidentifierare till olika kodsökvägar. Slutanvändaren drar nytta av specifika identifierare. Ofta har varje kodsökväg som anropar System.Management.Automation.Cmdlet.WriteError eller System.Management.Automation.Cmdlet.ThrowTerminatingError* sin egen identifierare. Som regel definierar du 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 hjälp av en viss felidentifierare upprättar du semantiken för fel med 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 av målobjekt ändras skapar du och använder sedan en ny identifierare.

  • Välj text för din felidentifierare som kortfattat motsvarar det fel som du rapporterar. Använd standardkonventionerna för namngivning och versaler för .NET Framework. Använd inte blanksteg eller skiljetecken. Lokalisera inte felidentifierare.

  • Generera inte felidentifierare dynamiskt på ett icke-reproducerbart sätt. Inkludera till exempel inte felinformation, till exempel ett process-ID. Felidentifierare är endast användbara om de motsvarar de felidentifierare som visas av andra användare som har samma feltillstånd.

Felkategori

När du skapar en felpost anger du kategorin för felet med hjälp av en av konstanterna som definierats av System.Management.Automation.ErrorCategory uppräkning. Windows PowerShell använder felkategorin för att visa felinformation när användarna anger $ErrorView variabeln till "CategoryView".

Undvik att använda System.Management.Automation.ErrorCategoryNotSpecified konstant. Om du har någon information om felet eller om den åtgärd 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 av Windows PowerShell kallas för kategorivysträngen och skapas utifrån 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-definierad System.Management.Automation.ErrorCategory konstant.

  • TargetName: Som standard bearbetades namnet på objektet som cmdleten bearbetade när felet inträffade. Eller en annan cmdlet-definierad sträng.

  • TargetType: Som standard typen av målobjekt. 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.

Felmeddelande om ersättning

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 skrivskyddad egenskap vars meddelandetext endast är avsedd för felsökning (enligt .NET Framework-riktlinjerna). 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.

Ersättningsmeddelandet bör följa designriktlinjerna för .NET Framework för att skriva undantagsmeddelanden med liten skillnad. Riktlinjerna anger 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 System.Management.Automation.Cmdlet.WriteError eller System.Management.Automation.Cmdlet.ThrowTerminatingError* metoder anropas. Om du vill lägga till ett ersättningsmeddelande anger du System.Management.Automation.ErrorRecord.ErrorDetails egenskap för felposten. När den här egenskapen har angetts visar Windows PowerShell egenskapen System.Management.Automation.ErrorDetails.Message* i stället för standardmeddelandetexten.

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

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 skrivskyddad.

Se även

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-felrapportering

Skriva en Windows PowerShell-cmdlet

  • Last updated on