Windows PowerShell-felposterWindows PowerShell Error Records

-Cmdletar måste klara ett system. Management. Automation. ErrorRecord -objekt som identifierar fel tillståndet för avslutande och icke-avslutande fel.Cmdlets must pass an System.Management.Automation.ErrorRecord object that identifies the error condition for terminating and non-terminating errors.

Objektet system. Management. Automation. ErrorRecord innehåller följande information:The System.Management.Automation.ErrorRecord object contains the following information:

  • Det undantag som beskriver felet.The exception that describes the error. Detta är ofta ett undantag som cmdleten fångas in och konverteras till en felpost.Often, this is an exception that the cmdlet caught and converted into an error record. Varje fel post måste innehålla ett undantag.Every error record must contain an exception.

Om cmdleten inte fångade ett undantag måste den skapa ett nytt undantag och välja den undantags klass som bäst beskriver fel tillståndet.If the cmdlet did not catch an exception, it must create a new exception and choose the exception class that best describes the error condition. Du behöver dock inte utlösa undantaget eftersom det kan nås via egenskapen system. Management. Automation. ErrorRecord. Exception i objektet system. Management. Automation. ErrorRecord .However, you do not need to throw the exception because it can be accessed through the System.Management.Automation.ErrorRecord.Exception property of the System.Management.Automation.ErrorRecord object.

  • En fel-ID som ger en riktad beteckning som kan användas för diagnos syfte och Windows PowerShell-skript för att hantera specifika fel villkor med specifika fel hanterare.An error identifier that provides a targeted designator that can be used for diagnostic purposes and by Windows PowerShell scripts to handle specific error conditions with specific error handlers. Varje fel post måste innehålla en fel identifierare (se fel identifierare).Every error record must contain an error identifier (see Error Identifier).

  • En fel kategori som tillhandahåller en allmän beteckning som kan användas i diagnostiska syfte.An error category that provides a general designator that can be used for diagnostic purposes. Varje fel post måste ange en fel kategori (se fel kategori).Every error record must specify an error category (see Error Category).

  • Ett valfritt ersättnings fel meddelande och en Rekommenderad åtgärd (se ersättnings fel meddelande).An optional replacement error message and a recommended action (see Replacement Error Message).

  • Valfri anrops information om den cmdlet som utlöste felet.Optional invocation information about the cmdlet that threw the error. Den här informationen anges av Windows PowerShell (se anrops meddelandet).This information is specified by Windows PowerShell (see Invocation Message).

  • Det mål objekt som bearbetades när felet inträffade.The target object that was being processed when the error occurred. Detta kan vara ett annat objekt, eller så kan det vara ett annat objekt som din cmdlet bearbetar.This might be the input object, or it might be another object that your cmdlet was processing. Till exempel remove-item -recurse c:\somedirectory kan felet vara en instans av ett fileinfo-objekt för "c:\somedirectory\lockedfile" för kommandot.For example, for the command remove-item -recurse c:\somedirectory, the error might be an instance of a FileInfo object for "c:\somedirectory\lockedfile". Informationen om mål objekt är valfri.The target object information is optional.

Fel-IDError Identifier

När du skapar en fel post anger du en identifierare som anger fel villkoret i din cmdlet.When you create an error record, specify an identifier that designates the error condition within your cmdlet. Windows PowerShell kombinerar mål identifieraren med namnet på din cmdlet för att skapa en fullständigt kvalificerad fel identifierare.Windows PowerShell combines the targeted identifier with the name of your cmdlet to create a fully qualified error identifier. Den fullständigt kvalificerade fel identifieraren kan nås via egenskapen system. Management. Automation. ErrorRecord. FullyQualifiedErrorId för objektet system. Management. Automation. ErrorRecord .The fully qualified error identifier can be accessed through the System.Management.Automation.ErrorRecord.FullyQualifiedErrorId property of the System.Management.Automation.ErrorRecord object. Fel identifieraren är inte tillgänglig för sig själv.The error identifier is not available by itself. Den är endast tillgänglig som en del av den fullständigt kvalificerade fel identifieraren.It is available only as part of the fully qualified error identifier.

Använd följande rikt linjer för att generera fel identifierare när du skapar fel poster:Use the following guidelines to generate error identifiers when you create error records:

  • Gör fel identifierare som är speciella för ett fel tillstånd.Make error identifiers specific to an error condition. Rikta in sig på fel-ID: n för diagnos syfte och för skript som hanterar specifika fel villkor med specifika fel hanterare.Target the error identifiers for diagnostic purposes and for scripts that handle specific error conditions with specific error handlers. En användare ska kunna använda fel identifieraren för att identifiera felet och dess källa.A user should be able to use the error identifier to identify the error and its source. Fel identifierare möjliggör även rapportering av vissa fel villkor från befintliga undantag så att nya undantags underklasser inte krävs.Error identifiers also enable reporting for specific error conditions from existing exceptions so that new exception subclasses are not required.

  • I allmänhet tilldelar du olika fel identifierare till olika kod Sök vägar.In general, assign different error identifiers to different code paths. Slutanvändarens förmåner från särskilda identifierare.The end-user benefits from specific identifiers. Ofta har varje kod Sök väg som anropar system. Management. Automation. cmdlet. WriteError eller system. Management. Automation. cmdlet. Throwterminatingerror * en egen identifierare.Often, each code path that calls System.Management.Automation.Cmdlet.WriteError or System.Management.Automation.Cmdlet.Throwterminatingerror* has its own identifier. Som regel definierar du en ny identifierare när du definierar en ny mall sträng för fel meddelandet och vice versa.As a rule, define a new identifier when you define a new template string for the error message, and vice-versa. Använd inte fel meddelandet som en identifierare.Do not use the error message as an identifier.

  • När du publicerar kod med en viss fel identifierare upprättar du semantiken för fel med den identifieraren för din fullständiga produkt support livs cykel.When you publish code using a particular error identifier, you establish the semantics of errors with that identifier for your complete product support lifecycle. Återanvänd den inte i en kontext som är semantiskt annorlunda från den ursprungliga kontexten.Do not reuse it in a context that is semantically different from the original context. Om semantiken för det här felet ändras skapar du och använder sedan en ny identifierare.If the semantics of this error change, create and then use a new identifier.

  • Du bör vanligt vis bara använda en viss fel identifierare för undantag för en viss CLR-typ.You should generally use a particular error identifier only for exceptions of a particular CLR type. Om typen av undantag eller typen av mål objekt ändras, skapar du och använder sedan en ny identifierare.If the type of the exception or the type of the target object changes, create and then use a new identifier.

  • Välj text för din fel identifierare som är kortfattad för det fel som du rapporterar.Choose text for your error identifier that concisely corresponds to the error that you are reporting. Använd standard-.NET Framework namngivnings-och Skift läges konventioner.Use standard .NET Framework naming and capitalization conventions. Använd inte blank steg eller skiljetecken.Do not use white space or punctuation. Lokalisera inte fel identifierare.Do not localize error identifiers.

  • Generera inte fel identifierare dynamiskt på ett icke-reproducerbart sätt.Do not dynamically generate error identifiers in a non-reproducible way. Inkludera till exempel inte fel information, till exempel ett process-ID.For example, do not incorporate error information such as a process ID. Fel identifierare är bara användbara om de motsvarar de fel identifierare som visas av andra användare som har samma fel tillstånd.Error identifiers are useful only if they correspond to the error identifiers seen by other users who are experiencing the same error condition.

Fel kategoriError Category

När du skapar en felpost anger du kategori för felet med hjälp av en av konstanterna som definieras av uppräkningen system. Management. Automation. ErrorCategory .When you create an error record, specify the category of the error using one of the constants defined by the System.Management.Automation.ErrorCategory enumeration. I Windows PowerShell används fel kategorin för att visa fel information när användarna anger $ErrorView variabeln "CategoryView" .Windows PowerShell uses the error category to display error information when users set the $ErrorView variable to "CategoryView".

Undvik att använda konstanten system. Management. Automation. ErrorCategory NotSpecified .Avoid using the System.Management.Automation.ErrorCategory NotSpecified constant. 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.If you have any information about the error or about the operation that caused the error, choose the category that best describes the error or the operation, even if the category is not a perfect match.

Den information som visas i Windows PowerShell kallas för kategori-och-visnings sträng och bygger på egenskaperna för klassen system. Management. Automation. Errorcategoryinfo .The information displayed by Windows PowerShell is referred to as the category-view string and is built from the properties of the System.Management.Automation.Errorcategoryinfo class. (Den här klassen nås via egenskapen Error system. Management. Automation. ErrorRecord. CategoryInfo .)(This class is accessed through the error System.Management.Automation.ErrorRecord.CategoryInfo property.)

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

I följande lista beskrivs den information som visas:The following list describes the information displayed:

  • Kategori: en Windows PowerShell-definierad system. Management. Automation. ErrorCategory -konstant.Category: A Windows PowerShell-defined System.Management.Automation.ErrorCategory constant.

  • Målnamn: som standard är namnet på objektet som cmdleten bearbetades när felet inträffade.TargetName: By default, the name of the object the cmdlet was processing when the error occurred. Eller en annan cmdlet-definierad sträng.Or, another cmdlet-defined string.

  • TargetType: som standard är typen av mål objekt.TargetType: By default, the type of the target object. Eller en annan cmdlet-definierad sträng.Or, another cmdlet-defined string.

  • Aktivitet: som standard är namnet på den cmdlet som skapade fel posten.Activity: By default, the name of the cmdlet that created the error record. Eller en annan cmdlet-definierad sträng.Or, some other cmdlet-defined string.

  • Orsak: som standard är undantags typen.Reason: By default, the exception type. Eller en annan cmdlet-definierad sträng.Or, another cmdlet-defined string.

Ersättnings fel meddelandeReplacement Error Message

När du utvecklar en felpost för en cmdlet kommer standard fel meddelandet för felet att hämtas från standard meddelande texten i egenskapen system. Exception. Message .When you develop an error record for a cmdlet, the default error message for the error comes from the default message text in the System.Exception.Message property. Detta är en skrivskyddad egenskap vars meddelande text endast är avsedd för fel söknings ändamål (enligt rikt linjerna för .NET Framework).This is a read-only property whose message text is intended only for debugging purposes (according to the .NET Framework guidelines). Vi rekommenderar att du skapar ett fel meddelande som ersätter eller förstärker standard meddelande texten.We recommend that you create an error message that replaces or augments the default message text. Gör meddelandet mer användarvänligt och mer unikt för cmdleten.Make the message more user-friendly and more specific to the cmdlet.

Ersättnings meddelandet tillhandahålls av ett system. Management. Automation. ErrorDetails -objekt.The replacement message is provided by an System.Management.Automation.ErrorDetails object. Använd någon av följande konstruktorer för det här objektet eftersom de ger ytterligare lokaliserings information som kan användas av Windows PowerShell.Use one of the following constructors of this object because they provide additional localization information that can be used by Windows PowerShell.

Ersättnings meddelandet bör följa rikt linjerna för .NET Framework design för att skriva undantags meddelanden med liten skillnad.The replacement message should conform to the .NET Framework design guidelines for writing exception messages with a small difference. Rikt linjerna är ett tillstånd för att undantags meddelanden ska skrivas för utvecklare.The guidelines state that exception messages should be written for developers. De här ersättnings meddelandena ska vara skrivna för cmdlet-användaren.These replacement messages should be written for the cmdlet user.

Ersättnings fel meddelandet måste läggas till innan system. Management. Automation. cmdlet. WriteError eller system. Management. Automation. cmdlet. Throwterminatingerror * metoder anropas.The replacement error message must be added before the System.Management.Automation.Cmdlet.WriteError or System.Management.Automation.Cmdlet.Throwterminatingerror* methods are called. Om du vill lägga till ett ersättnings meddelande ställer du in egenskapen system. Management. Automation. ErrorRecord. ErrorDetails i fel posten.To add a replacement message, set the System.Management.Automation.ErrorRecord.ErrorDetails property of the error record. När den här egenskapen har angetts visas egenskapen system. Management. Automation. ErrorDetails. Message * i Windows PowerShell i stället för standard meddelande texten.When this property is set, Windows PowerShell displays the System.Management.Automation.ErrorDetails.Message* property instead of the default message text.

Objektet system. Management. Automation. ErrorDetails kan också ge information om vilka åtgärder som rekommenderas när felet uppstår.The System.Management.Automation.ErrorDetails object can also provide information about what actions are recommended when the error occurs.

Information om anropInvocation information

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 uppstod.When a cmdlet uses System.Management.Automation.Cmdlet.WriteError or System.Management.Automation.Cmdlet.Throwterminatingerror* to report an error record, Windows PowerShell automatically adds information that describes the command that was invoked when the error occurred. Den här informationen tillhandahålls av ett system. Management. Automation. Invocationinfo -objekt som innehåller namnet på den cmdlet som anropades av kommandot, själva kommandot och information om pipelinen eller skriptet.This information is provided by a System.Management.Automation.Invocationinfo object that contains the name of the cmdlet that was invoked by the command, the command itself, and information about the pipeline or script. Den här egenskapen är skrivskyddad.This property is read-only.

Se ävenSee Also

System. Management. Automation. cmdlet. WriteErrorSystem.Management.Automation.Cmdlet.WriteError

System. Management. Automation. cmdlet. Throwterminatingerror *System.Management.Automation.Cmdlet.Throwterminatingerror*

System. Management. Automation. ErrorCategorySystem.Management.Automation.ErrorCategory

System. Management. Automation. ErrorcategoryinfoSystem.Management.Automation.Errorcategoryinfo

System. Management. Automation. ErrorRecordSystem.Management.Automation.ErrorRecord

System. Management. Automation. ErrorDetailsSystem.Management.Automation.ErrorDetails

System. Management. Automation. InvocationinfoSystem.Management.Automation.Invocationinfo

Windows PowerShell-felrapporteringWindows PowerShell Error Reporting

Skriva en Windows PowerShell-cmdletWriting a Windows PowerShell Cmdlet