Rekordy błędów programu Windows PowerShell

Artykuł
09/24/2021

Polecenia cmdlet muszą przekazać obiekt System.Management.Automation.ErrorRecord, który identyfikuje warunek błędu dla błędów kończących i niepowiązywujących z tym błędami.

Obiekt System.Management.Automation.ErrorRecord zawiera następujące informacje:

Wyjątek opisujący błąd. Często jest to wyjątek, który przechwycił i przekonwertował polecenie cmdlet na rekord błędu. Każdy rekord błędu musi zawierać wyjątek.

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. Nie trzeba jednak zgłaszać wyjątku, ponieważ jest on dostępny za pośrednictwem właściwości System.Management.Automation.ErrorRecord.Exception obiektu System.Management.Automation.ErrorRecord.

Identyfikator błędu, który udostępnia docelowy program do projektowania, który może być używany do celów diagnostycznych i przez skrypty Windows PowerShell do obsługi określonych warunków błędu z określonymi procedurami obsługi błędów. Każdy rekord błędu musi zawierać identyfikator błędu (zobacz Identyfikator błędu).
Kategoria błędów, która zawiera ogólny element projektowy, który może być używany do celów diagnostycznych. Każdy rekord błędu musi określać kategorię błędów (zobacz Kategoria błędu).
Opcjonalny komunikat o błędzie zastępczy i zalecana akcja (zobacz Komunikat o błędzie zastępczym).
Opcjonalne informacje dotyczące wywołania polecenia cmdlet, które zrzuciło błąd. Te informacje są określane przez Windows PowerShell (zobacz Komunikat wywołania).
Obiekt docelowy, który był przetwarzany w momencie wystąpienia błędu. Może to być obiekt wejściowy lub inny obiekt przetwarzany przez polecenie cmdlet. Na przykład w przypadku polecenia błąd może być wystąpieniem obiektu remove-item -recurse c:\somedirectory FileInfo dla "c:\somedirectory\lockedfile". Informacje o obiekcie docelowym są opcjonalne.

Identyfikator błędu

Podczas tworzenia rekordu błędu określ identyfikator, który wyznacza warunek błędu w ramach polecenia cmdlet. Windows PowerShell łączy docelowy identyfikator z nazwą polecenia cmdlet w celu utworzenia w pełni kwalifikowanego identyfikatora błędu. Dostęp do w pełni kwalifikowanego identyfikatora błędu można uzyskać za pośrednictwem właściwości System.Management.Automation.ErrorRecord.FullyQualifiedErrorId obiektu System.Management.Automation.ErrorRecord. Identyfikator błędu nie jest dostępny samodzielnie. Jest on dostępny tylko jako część w pełni kwalifikowanego identyfikatora błędu.

Poniższe wskazówki dotyczą generowania identyfikatorów błędów podczas tworzenia rekordów błędów:

Nadaj identyfikatorom błędów specyficzne dla warunku błędu. Identyfikatory błędów należy kierować do celów diagnostycznych i skryptów, które obsługują określone warunki błędów przy użyciu określonych procedur obsługi błędów. Użytkownik powinien mieć możliwość użycia identyfikatora błędu do zidentyfikowania błędu i jego źródła. Identyfikatory błędów umożliwiają również raportowanie określonych warunków błędów z istniejących wyjątków, dzięki czemu nowe podklasy wyjątków nie są wymagane.
Ogólnie rzecz biorąc, przypisz różne identyfikatory błędów do różnych ścieżek kodu. Użytkownik końcowy korzysta z określonych identyfikatorów. Często każda ścieżka kodu, która wywołuje system.Management.Automation.Cmdlet.WriteError lub System.Management.Automation.Cmdlet.Throwterminatingerror*, ma własny identyfikator. Zgodnie z regułą zdefiniuj nowy identyfikator podczas definiowania nowego ciągu szablonu dla komunikatu o błędzie i na odwrót. Nie używaj komunikatu o błędzie jako identyfikatora.
Podczas publikowania kodu przy użyciu określonego identyfikatora błędu określasz semantykę błędów z tym identyfikatorem dla całego cyklu wsparcia technicznego produktu. Nie używaj jej ponownie w kontekście, który semantycznie różni się od oryginalnego kontekstu. Jeśli semantyka tego błędu zmieni się, utwórz, a następnie użyj nowego identyfikatora.
Zazwyczaj należy używać określonego identyfikatora błędu tylko w przypadku wyjątków określonego typu CLR. Jeśli typ wyjątku lub typ obiektu docelowego zmieni się, utwórz, a następnie użyj nowego identyfikatora.
Wybierz tekst dla identyfikatora błędu, który zwięzło odpowiada raportowi o błędzie. Użyj standardowych .NET Framework nazewnictwa i liter. Nie używaj białych znaków ani znaków interpunkcji. Nie należy lokalizacji identyfikatorów błędów.
Nie generuj dynamicznie identyfikatorów błędów w sposób nieodświątany. Na przykład nie uwzględniaj informacji o błędach, takich jak identyfikator procesu. Identyfikatory błędów są przydatne tylko wtedy, gdy odpowiadają identyfikatorom błędów widocznym dla innych użytkowników, którzy mają ten sam warunek błędu.

Kategoria błędu

Podczas tworzenia rekordu błędu określ kategorię błędu przy użyciu jednej ze stałych zdefiniowanych przez wyliczenie System.Management.Automation.ErrorCategory. Windows PowerShell używa kategorii błędów do wyświetlania informacji o błędzie, gdy użytkownicy $ErrorView ustawiają zmienną na "CategoryView" wartość .

Unikaj używania stałej System.Management.Automation.ErrorCategory NotSpecified. Jeśli masz jakiekolwiek informacje o błędzie lub 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.

Informacje wyświetlane przez Windows PowerShell są określane jako ciąg widoku kategorii i są zbudowana z właściwości klasy System.Management.Automation.Errorcategoryinfo. (Dostęp do tej klasy można uzyskać za pośrednictwem błędu System.Management.Automation.ErrorRecord.CategoryInfo).

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

Na poniższej liście opisano wyświetlane informacje:

Kategoria: zdefiniowana Windows PowerShell System.Management.Automation.ErrorCategory.
TargetName: domyślnie nazwa obiektu, który przetwarzał polecenie cmdlet w momencie wystąpienia błędu. Lub inny ciąg zdefiniowany przez polecenie cmdlet.
TargetType: domyślnie typ obiektu docelowego. Lub inny ciąg zdefiniowany przez polecenie cmdlet.
Działanie: domyślnie nazwa polecenia cmdlet, które utworzyło rekord błędu. Lub inny ciąg zdefiniowany przez polecenie cmdlet.
Przyczyna: domyślnie typ wyjątku. Lub inny ciąg zdefiniowany przez polecenie cmdlet.

Komunikat o błędzie zastępczym

Podczas opracowywania rekordu błędu dla polecenia cmdlet domyślny komunikat o błędzie pochodzi z domyślnego tekstu komunikatu we właściwości System.Exception.Message. Jest to właściwość tylko do odczytu, której tekst komunikatu jest przeznaczony tylko do celów debugowania (zgodnie z .NET Framework wytycznymi). Zalecamy utworzenie komunikatu o błędzie, który zastąpi lub rozszerzy domyślny tekst komunikatu. Upewnij się, że komunikat jest bardziej przyjazny dla użytkownika i bardziej specyficzny dla polecenia cmdlet .

Komunikat zastępczy jest dostarczany przez obiekt System.Management.Automation.ErrorDetails. Użyj jednego z następujących konstruktorów tego obiektu, ponieważ zapewniają dodatkowe informacje o lokalizacji, które mogą być używane przez Windows PowerShell.

ErrorDetails(Cmdlet, String, String, Object[]): użyj tego konstruktora, jeśli ciąg szablonu jest ciągiem zasobu w tym samym zestawie, w którym zaimplementowano polecenie cmdlet, lub jeśli chcesz załadować ciąg szablonu za pośrednictwem zastąpienia metody System.Management.Automation.Cmdlet.GetResourceString.
ErrorDetails(Assembly, String, String, Object[]): użyj tego konstruktora, jeśli ciąg szablonu znajduje się w innym zestawie i nie ładujesz go za pomocą przesłonięcia właściwości System.Management.Automation.Cmdlet.GetResourceString.

Komunikat zastępczy powinien być zgodny z wytycznymi .NET Framework projektowania dotyczącymi pisania komunikatów o wyjątkach z niewielką różnicą. Wytyczne stanowią, że komunikaty o wyjątkach powinny być pisane dla deweloperów. Te komunikaty zastępcze powinny być zapisywane dla użytkownika polecenia cmdlet.

Komunikat o błędzie zastępczy należy dodać przed wywoływaniem metod System.Management.Automation.Cmdlet.WriteError lub System.Management.Automation.Cmdlet.Throwterminatingerror*. Aby dodać komunikat zastępczy, ustaw właściwość System.Management.Automation.ErrorRecord.ErrorDetails rekordu błędu. Gdy ta właściwość jest ustawiona, Windows PowerShell wyświetla właściwość System.Management.Automation.ErrorDetails.Message* zamiast domyślnego tekstu komunikatu.

Zalecane informacje o akcjach

Obiekt System.Management.Automation.ErrorDetails może również dostarczyć informacji o akcjach zalecanych w przypadku wystąpienia błędu.

Informacje o wywołaniach

Gdy polecenie cmdlet używa funkcji 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 w momencie wystąpienia błędu. Te informacje są dostarczane przez obiekt System.Management.Automation.Invocationinfo zawierający nazwę polecenia cmdlet, które zostało wywołane przez polecenie, samo polecenie oraz informacje o potoku lub skrypcie. Ta właściwość jest tylko do odczytu.