Rekordy błędów programu Windows PowerShellWindows PowerShell Error Records

Polecenia cmdlet muszą przekazać obiekt System. Management. Automation. ErrorRecord , który identyfikuje warunek błędu dla błędów zakończenia i niekończącego.Cmdlets must pass an System.Management.Automation.ErrorRecord object that identifies the error condition for terminating and non-terminating errors.

Obiekt System. Management. Automation. ErrorRecord zawiera następujące informacje:The System.Management.Automation.ErrorRecord object contains the following information:

  • Wyjątek, który opisuje błąd.The exception that describes the error. Często jest to wyjątek, który został przechwycony przez polecenie cmdlet i przekonwertowane do rekordu błędu.Often, this is an exception that the cmdlet caught and converted into an error record. Każdy rekord błędu musi zawierać wyjątek.Every error record must contain an exception.

Jeśli polecenie cmdlet nie przechwytuje wyjątku, musi utworzyć nowy wyjątek i wybrać klasę wyjątku, która najlepiej opisuje warunek błędu.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. Nie trzeba jednak zgłaszać wyjątku, ponieważ dostęp do niego można uzyskać za pomocą właściwości System. Management. Automation. ErrorRecord. Exception obiektu 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.

  • Identyfikator błędu, który zapewnia wskazanie do celów diagnostycznych i skryptów programu Windows PowerShell do obsługi określonych warunków błędów z określonymi programami obsługi błędów.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. Każdy rekord błędu musi zawierać Identyfikator błędu (zobacz Identyfikator błędu).Every error record must contain an error identifier (see Error Identifier).

  • Kategoria błędu, która dostarcza ogólny wskaźnik, który może być używany do celów diagnostycznych.An error category that provides a general designator that can be used for diagnostic purposes. Każdy rekord błędu musi określać kategorię błędów (patrz Kategoria błędu).Every error record must specify an error category (see Error Category).

  • Opcjonalny, zastępczy komunikat o błędzie i zalecana akcja (zobacz temat zastępowanie komunikatu o błędzie).An optional replacement error message and a recommended action (see Replacement Error Message).

  • Opcjonalne informacje dotyczące wywołania polecenia cmdlet, które wywołały błąd.Optional invocation information about the cmdlet that threw the error. Te informacje są określone przez program Windows PowerShell (Zobacz komunikat wywoływania).This information is specified by Windows PowerShell (see Invocation Message).

  • Obiekt docelowy, który był przetwarzany po wystąpieniu błędu.The target object that was being processed when the error occurred. Może to być obiekt wejściowy lub inny obiekt, który został przetworzony przez polecenie cmdlet.This might be the input object, or it might be another object that your cmdlet was processing. Na przykład w przypadku polecenia remove-item -recurse c:\somedirectory błąd może być wystąpieniem obiektu FileInfo dla elementu "c:\somedirectory\lockedfile".For example, for the command remove-item -recurse c:\somedirectory, the error might be an instance of a FileInfo object for "c:\somedirectory\lockedfile". Informacje o obiekcie docelowym są opcjonalne.The target object information is optional.

Identyfikator błęduError Identifier

Podczas tworzenia rekordu błędu należy określić identyfikator, który wyznacza warunek błędu w poleceniu cmdlet.When you create an error record, specify an identifier that designates the error condition within your cmdlet. Program Windows PowerShell łączy identyfikator wskazywany z nazwą polecenia cmdlet, aby utworzyć w pełni kwalifikowany Identyfikator błędu.Windows PowerShell combines the targeted identifier with the name of your cmdlet to create a fully qualified error identifier. W pełni kwalifikowany Identyfikator błędu można uzyskać za pomocą właściwości System. Management. Automation. ErrorRecord. FullyQualifiedErrorId obiektu 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. Identyfikator błędu nie jest dostępny dla samego siebie.The error identifier is not available by itself. Jest on dostępny tylko w ramach w pełni kwalifikowanego identyfikatora błędu.It is available only as part of the fully qualified error identifier.

Poniższe wskazówki służą do generowania identyfikatorów błędów podczas tworzenia rekordów błędów:Use the following guidelines to generate error identifiers when you create error records:

  • Wprowadź identyfikatory błędów charakterystyczne dla warunku błędu.Make error identifiers specific to an error condition. Określanie identyfikatorów błędów dla celów diagnostycznych i skryptów, które obsługują określone warunki błędów z określonymi programami obsługi błędów.Target the error identifiers for diagnostic purposes and for scripts that handle specific error conditions with specific error handlers. Użytkownik powinien mieć możliwość użycia identyfikatora błędu, aby zidentyfikować błąd i jego źródło.A user should be able to use the error identifier to identify the error and its source. Identyfikatory błędów umożliwiają również raportowanie dla określonych warunków błędów z istniejących wyjątków, aby nie były wymagane nowe podklasy wyjątków.Error identifiers also enable reporting for specific error conditions from existing exceptions so that new exception subclasses are not required.

  • Ogólnie rzecz biorąc, przypisz różne identyfikatory błędów do różnych ścieżek kodu.In general, assign different error identifiers to different code paths. Użytkownicy końcowi korzystający z określonych identyfikatorów.The end-user benefits from specific identifiers. Często każda ścieżka kodu wywołująca System. Management. Automation. cmdlet. WriteError lub System. Management. Automation. cmdlet. Throwterminatingerror * ma swój własny identyfikator.Often, each code path that calls System.Management.Automation.Cmdlet.WriteError or System.Management.Automation.Cmdlet.Throwterminatingerror* has its own identifier. Jako regułę Zdefiniuj nowy identyfikator podczas definiowania ciągu nowego szablonu dla komunikatu o błędzie i na odwrót.As a rule, define a new identifier when you define a new template string for the error message, and vice-versa. Nie należy używać komunikatu o błędzie jako identyfikatora.Do not use the error message as an identifier.

  • Gdy publikujesz kod przy użyciu określonego identyfikatora błędu, określisz semantykę błędów z tym identyfikatorem dla całego cyklu pomocy technicznej produktu.When you publish code using a particular error identifier, you establish the semantics of errors with that identifier for your complete product support lifecycle. Nie należy używać go ponownie w kontekście, który jest semantycznie inny od oryginalnego kontekstu.Do not reuse it in a context that is semantically different from the original context. Jeśli semantyka tego błędu zostanie zmieniona, Utwórz, a następnie użyj nowego identyfikatora.If the semantics of this error change, create and then use a new identifier.

  • Zazwyczaj należy używać określonego identyfikatora błędu tylko dla wyjątków określonego typu CLR.You should generally use a particular error identifier only for exceptions of a particular CLR type. Jeśli typ wyjątku lub typ obiektu docelowego ulegnie zmianie, Utwórz, a następnie użyj nowego identyfikatora.If the type of the exception or the type of the target object changes, create and then use a new identifier.

  • Wybierz tekst identyfikatora błędu, który zwięzłie odpowiada raportowanemu błędowi.Choose text for your error identifier that concisely corresponds to the error that you are reporting. Użyj standardowych nazw .NET Framework i Konwencji kapitalizacji.Use standard .NET Framework naming and capitalization conventions. Nie używaj odstępów ani znaków interpunkcyjnych.Do not use white space or punctuation. Nie należy lokalizować identyfikatorów błędów.Do not localize error identifiers.

  • Nie Generuj dynamicznie identyfikatorów błędów w sposób niepowtarzalny.Do not dynamically generate error identifiers in a non-reproducible way. Na przykład nie należy uwzględniać informacji o błędach, takich jak identyfikator procesu.For example, do not incorporate error information such as a process ID. Identyfikatory błędów są przydatne tylko wtedy, gdy odpowiadają identyfikatorom błędów, które są widoczne dla innych użytkowników, którzy mają ten sam warunek błędu.Error identifiers are useful only if they correspond to the error identifiers seen by other users who are experiencing the same error condition.

Kategoria błęduError Category

Podczas tworzenia rekordu błędu należy określić kategorię błędu przy użyciu jednej ze stałych zdefiniowanych przez Wyliczenie 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. Program Windows PowerShell używa kategorii błędów do wyświetlania informacji o błędach, gdy użytkownicy ustawiają $ErrorView zmienną na "CategoryView" .Windows PowerShell uses the error category to display error information when users set the $ErrorView variable to "CategoryView".

Należy unikać używania stałej System. Management. Automation. ErrorCategory NotSpecified .Avoid using the System.Management.Automation.ErrorCategory NotSpecified constant. Jeśli masz jakieś informacje o błędzie lub o operacji, która spowodowała błąd, wybierz kategorię, która najlepiej opisuje błąd lub operację, nawet jeśli Kategoria nie jest idealnym dopasowaniem.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.

Informacje wyświetlane przez program Windows PowerShell są określane jako ciąg widoku kategorii i są tworzone na podstawie właściwości klasy 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. (Do tej klasy dostęp uzyskuje się za pomocą właściwości System. Management. Automation. ErrorRecord. CategoryInfo ).(This class is accessed through the error System.Management.Automation.ErrorRecord.CategoryInfo property.)

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

Poniższa lista zawiera opis wyświetlanych informacji:The following list describes the information displayed:

  • Kategoria: stała System. Management. Automation. ErrorCategory zdefiniowana w programie Windows PowerShell.Category: A Windows PowerShell-defined System.Management.Automation.ErrorCategory constant.

  • TargetName: Domyślnie nazwa obiektu, który przetworzył polecenie cmdlet po wystąpieniu błędu.TargetName: By default, the name of the object the cmdlet was processing when the error occurred. Lub inny ciąg zdefiniowany przez polecenie cmdlet.Or, another cmdlet-defined string.

  • TargetType: Domyślnie typ obiektu docelowego.TargetType: By default, the type of the target object. Lub inny ciąg zdefiniowany przez polecenie cmdlet.Or, another cmdlet-defined string.

  • Działanie: Domyślnie nazwa polecenia cmdlet, które spowodowało utworzenie rekordu błędu.Activity: By default, the name of the cmdlet that created the error record. Lub inny ciąg zdefiniowany przez polecenie cmdlet.Or, some other cmdlet-defined string.

  • Przyczyna: Domyślnie typ wyjątku.Reason: By default, the exception type. Lub inny ciąg zdefiniowany przez polecenie cmdlet.Or, another cmdlet-defined string.

Zastępczy komunikat o błędzieReplacement Error Message

Podczas tworzenia rekordu błędu dla polecenia cmdlet, domyślny komunikat o błędzie dla błędu pochodzi z domyślnego tekstu komunikatu w właściwości 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. Jest to właściwość tylko do odczytu, której tekst komunikatu jest przeznaczony tylko do celów debugowania (zgodnie z wytycznymi .NET Frameworkymi).This is a read-only property whose message text is intended only for debugging purposes (according to the .NET Framework guidelines). Zalecamy utworzenie komunikatu o błędzie, który zastępuje lub rozszerza domyślny tekst komunikatu.We recommend that you create an error message that replaces or augments the default message text. Udostępnij komunikat bardziej przyjazny dla użytkownika i bardziej szczegółowy dla tego polecenia cmdlet.Make the message more user-friendly and more specific to the cmdlet.

Komunikat zastępczy jest dostarczany przez obiekt System. Management. Automation. ErrorDetails .The replacement message is provided by an System.Management.Automation.ErrorDetails object. Użyj jednego z następujących konstruktorów tego obiektu, ponieważ udostępniają one dodatkowe informacje o lokalizacji, które mogą być używane przez program Windows PowerShell.Use one of the following constructors of this object because they provide additional localization information that can be used by Windows PowerShell.

Komunikat zastępczy powinien być zgodny z .NET Framework wytycznych dotyczących projektowania podczas pisania komunikatów o wyjątkach z małą różnicą.The replacement message should conform to the .NET Framework design guidelines for writing exception messages with a small difference. Wytyczne dotyczące komunikatów o wyjątkach, które należy napisać dla deweloperów.The guidelines state that exception messages should be written for developers. Te komunikaty zastępcze powinny być zapisywane dla użytkownika polecenia cmdlet.These replacement messages should be written for the cmdlet user.

Zastępujący komunikat o błędzie musi zostać dodany przed wywołaniem metody System. Management. Automation. cmdlet. WriteError lub System. Management. Automation. cmdlet. Throwterminatingerror * .The replacement error message must be added before the System.Management.Automation.Cmdlet.WriteError or System.Management.Automation.Cmdlet.Throwterminatingerror* methods are called. Aby dodać komunikat zastępczy, ustaw właściwość System. Management. Automation. ErrorRecord. ErrorDetails rekordu błędu.To add a replacement message, set the System.Management.Automation.ErrorRecord.ErrorDetails property of the error record. Gdy ta właściwość jest ustawiona, program Windows PowerShell wyświetla Właściwość System. Management. Automation. ErrorDetails. Message * zamiast domyślnego tekstu komunikatu.When this property is set, Windows PowerShell displays the System.Management.Automation.ErrorDetails.Message* property instead of the default message text.

Obiekt System. Management. Automation. ErrorDetails może również dostarczyć informacje o akcjach, które są zalecane w przypadku wystąpienia błędu.The System.Management.Automation.ErrorDetails object can also provide information about what actions are recommended when the error occurs.

Informacje o wywołaniuInvocation information

Gdy polecenie cmdlet używa elementu System. Management. Automation. cmdlet. WriteError lub System. Management. Automation. cmdlet. Throwterminatingerror * do raportowania rekordu błędu, program Windows PowerShell automatycznie dodaje informacje opisujące polecenie, które zostało wywołane po wystąpieniu błędu.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. Te informacje są dostarczane przez obiekt System. Management. Automation. Invocationinfo , który zawiera nazwę polecenia cmdlet, które zostało wywołane przez polecenie, samo polecenie i informacje o potoku lub skrypcie.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. Ta właściwość jest tylko do odczytu.This property is read-only.

Zobacz teżSee 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

Raportowanie błędów programu Windows PowerShellWindows PowerShell Error Reporting

Pisanie polecenia cmdlet programu Windows PowerShellWriting a Windows PowerShell Cmdlet