Udostępnij za pomocą

Rekordy błędów programu Windows PowerShell

Polecenia cmdlet muszą przekazać obiekt System.Management.Automation.ErrorRecord, który identyfikuje warunek błędu dotyczący błędów zakończenia i niepowodzeń zakończenia.

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

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

Jeśli polecenie cmdlet nie przechwyciło wyjątku, musi utworzyć nowy wyjątek i wybrać klasę wyjątków, która najlepiej opisuje warunek błędu. Nie trzeba jednak zgłaszać wyjątku, ponieważ można uzyskać do niego dostęp za pośrednictwem właściwości System.Management.Automation.ErrorRecord.Exception właściwości System.Management.Automation.ErrorRecord.

  • Identyfikator błędu, który udostępnia docelowy projektant, który może być używany do celów diagnostycznych i przez skrypty programu Windows PowerShell do obsługi określonych warunków błędów 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 udostępnia ogólny projektant, 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ąpienia i zalecana akcja (zobacz Komunikat o błędzie zamiany).

  • Opcjonalne informacje o wywołaniu polecenia cmdlet, które zgłosiły błąd. Te informacje są określane przez program Windows PowerShell (zobacz Komunikat wywołania).

  • Obiekt docelowy, który był przetwarzany podczas wystąpienia błędu. Może to być obiekt wejściowy lub inny obiekt, który przetwarzał polecenie cmdlet. Na przykład w przypadku polecenia Remove-Item -Recurse C:\somedirectorybłąd może być wystąpieniem obiektu 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 poleceniu cmdlet. Program Windows PowerShell łączy identyfikator docelowy z nazwą polecenia cmdlet, aby utworzyć w pełni kwalifikowany identyfikator 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.Automation.ErrorRecord.FullyQualifiedErrorId właściwości System.Management.Automation.ErrorRecord. Identyfikator błędu jest niedostępny samodzielnie. Jest ona dostępna tylko w ramach w pełni kwalifikowanego identyfikatora błędu.

Użyj poniższych wskazówek, aby wygenerować identyfikatory błędów podczas tworzenia rekordów błędów:

  • Wprowadź identyfikatory błędów specyficzne dla warunku błędu. Określanie identyfikatorów błędów dla celów diagnostycznych i skryptów obsługujących określone warunki błędu z określonymi procedurami obsługi błędów. Użytkownik powinien mieć możliwość użycia identyfikatora błędu w celu 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, aby 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 wywołująca 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 ustanowisz semantyka błędów z tym identyfikatorem dla całego cyklu życia pomocy technicznej produktu. Nie należy używać go ponownie w kontekście, który jest semantycznie różni się od oryginalnego kontekstu. Jeśli semantyka tego błędu ulegnie zmianie, utwórz, a następnie użyj nowego identyfikatora.

  • Zazwyczaj należy użyć określonego identyfikatora błędu tylko dla wyjątków określonego typu CLR. Jeśli typ wyjątku lub typ obiektu docelowego ulegnie zmianie, utwórz, a następnie użyj nowego identyfikatora.

  • Wybierz tekst identyfikatora błędu, który zwięźle odpowiada zgłaszanemu błędowi. Użyj standardowych konwencji nazewnictwa i wielkości liter programu .NET Framework. Nie używaj białych znaków ani znaków interpunkcyjnych. Nie lokalizuj identyfikatorów błędów.

  • Nie generuj dynamicznie identyfikatorów błędów w sposób nieodkonalny. Na przykład nie dołączaj informacji o błędach, takich jak identyfikator procesu. Identyfikatory błędów są przydatne tylko wtedy, gdy odpowiadają identyfikatorom błędów widocznym przez innych użytkowników, którzy mają ten sam warunek błędu.

Kategoria błędów

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

Unikaj używania stałej System.Management.Automation.ErrorCategoryNotSpecified. 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 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. (Ta klasa jest uzyskiwana za pośrednictwem właściwości błędu System.Management.Automation.Automation.ErrorRecord.CategoryInfo).

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

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

  • Kategoria: stała zdefiniowana przez program Windows PowerShell System.Management.Automation.Automation.ErrorCategory.

  • TargetName: domyślnie nazwa obiektu, który przetwarzał polecenie cmdlet podczas 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ąpienia

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 wiadomości jest przeznaczony tylko do celów debugowania (zgodnie z wytycznymi programu .NET Framework). Zalecamy utworzenie komunikatu o błędzie, który zastępuje lub rozszerza domyślny tekst wiadomości. Udostępnij komunikat bardziej przyjazny dla użytkownika i bardziej szczegółowy 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ż udostępniają dodatkowe informacje o lokalizacji, które mogą być używane przez program Windows PowerShell.

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

Przed wywołaniem metod System.Management.Automation.Cmdlet.WriteError lub System.Management.Automation.Cmdlet.ThrowTerminatingError* należy dodać komunikat o błędzie. Aby dodać komunikat zastępczy, ustaw właściwość System.Management.Automation.ErrorRecord.ErrorDetails rekordu błędu. Po ustawieniu tej właściwości program Windows PowerShell wyświetla właściwość System.Management.Automation.ErrorDetails.Message* zamiast domyślnego tekstu wiadomości.

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

Informacje o wywołaniu

Gdy polecenie cmdlet używa System.Management.Automation.Cmdlet.WriteError lub System.Management.Automation.Cmdlet.ThrowTerminatingError* zgłosić rekord błędu, program Windows PowerShell automatycznie dodaje informacje opisujące polecenie wywoływane podczas wystąpienia błędu. Te informacje są dostarczane przez obiekt System.Management.Automation.InvocationInfo, który zawiera nazwę polecenia cmdlet, które zostało wywołane przez polecenie, polecenie i informacje o potoku lub skrypcie. Ta właściwość jest tylko do odczytu.

Zobacz też

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

raportowania błędów programu Windows PowerShell

pisanie polecenia cmdlet programu Windows PowerShell

  • Last updated on