about_Trap

Krótki opis

Opisuje słowo kluczowe obsługujące błąd zakończenia.

Długi opis

Błąd zakończenia uniemożliwia uruchomienie instrukcji. Jeśli program PowerShell nie obsługuje błędu zakończenia w jakiś sposób, program PowerShell również przestanie uruchamiać funkcję lub skrypt w bieżącym potoku. W innych językach, takich jak C#, błędy krytyczne są nazywane wyjątkami.

Słowo kluczowe trap określa listę instrukcji do wykonania w przypadku wystąpienia błędu krytycznego. trap instrukcje mogą obsługiwać błędy zakończenia w następujący sposób:

• Wyświetl błąd po przetworzeniu bloku instrukcji trap i kontynuowaniu wykonywania skryptu lub funkcji zawierającej trap. To zachowanie jest domyślne.

  Notatka

  Gdy błąd zakończenia występuje w bloku instrukcji podrzędnej, takim jak if instrukcja lub foreach pętla, instrukcje w trap bloku są uruchamiane i wykonywanie jest kontynuowane w następnej instrukcji poza blokiem podrzędnym.

• Wyświetl błąd i przerwij wykonanie skryptu lub funkcji zawierającej trap, używając break w instrukcji trap.

• Wycisz błąd, ale kontynuuj wykonywanie skryptu lub funkcji zawierającej trap przy użyciu continue w instrukcji trap.

Lista instrukcji trap może zawierać wiele warunków lub wywołań funkcji. trap może zapisywać dzienniki, warunki testowe, a nawet uruchamiać inny program.

Składnia

Instrukcja trap ma następującą składnię:

trap [[<error type>]] {<statement list>}

Instrukcja trap zawiera listę instrukcji do uruchomienia po wystąpieniu błędu krytycznego. Instrukcja trap składa się ze słowa kluczowego trap, po którym opcjonalnie następuje wyrażenie typu, oraz blok instrukcji zawierający listę instrukcji do uruchomienia, gdy błąd zostanie przechwycony. Wyrażenie typu uściśla, jakie typy błędów przechwytuje trap.

Skrypt lub polecenie może zawierać wiele instrukcji trap. trap instrukcje mogą pojawiać się w dowolnym miejscu w skrypcie lub poleceniu.

Przechwytywanie wszystkich błędów kończących

Gdy wystąpi błąd zakończenia, który nie jest obsługiwany w inny sposób w skrypsie lub poleceniu, program PowerShell sprawdza instrukcję trap, która obsługuje błąd. Jeśli istnieje instrukcja trap, program PowerShell kontynuuje uruchamianie skryptu lub polecenia w instrukcji trap.

Poniższy przykład to minimalna instrukcja trap:

trap { 'Error found.' }

Ta instrukcja trap wychwytuje wszelkie błędy zakończenia.

W poniższym przykładzie funkcja zawiera bezsensowny ciąg, który powoduje błąd wykonania.

function TrapTest {
    trap { 'Error found.' }
    nonsenseString
}

TrapTest

Uruchomienie tej funkcji zwraca następujące dane wyjściowe:

Error found.
nonsenseString:
Line |
   3 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Poniższy przykład zawiera instrukcjętrap, która wyświetla błąd przy użyciu zmiennej lub $PSItem automatycznej$_:

function TrapTest {
    trap { "Error found: $_" }
    nonsenseString
}

TrapTest

Uruchomienie tej wersji funkcji zwraca następujące dane wyjściowe:

Error found: The term 'nonsenseString' is not recognized as the name of a
cmdlet, function, script file, or operable program. Check the spelling of
the name, or if a path was included, verify that the path is correct and
try again.
nonsenseString:
Line |
   3 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Ważny

trap instrukcje można zdefiniować w dowolnym miejscu w danym skrypcie, ale zawsze mają zastosowanie do wszystkich instrukcji w tym skrypcie. W czasie wykonywania instrukcje trap w bloku są definiowane przed wykonaniem innych instrukcji. W innych językach, takich jak JavaScript, jest to nazywane podnoszenia. Oznacza to, że instrukcje trap mają zastosowanie do wszystkich instrukcji w tym bloku, nawet jeśli wykonanie nie osiągnęło jeszcze punktu, w którym zostały zdefiniowane. Na przykład zdefiniowanie trap na końcu skryptu i zgłoszenie błędu w pierwszej instrukcji nadal wyzwala trap.

Wychwytywanie określonych błędów

Skrypt lub polecenie może zawierać wiele instrukcji trap. Można zdefiniować trap w celu obsługi określonych błędów.

Poniższy przykład to instrukcja trap, która wychwytuje określony błąd CommandNotFoundException:

trap [System.Management.Automation.CommandNotFoundException] {
    'Command error trapped'
}

Gdy funkcja lub skrypt napotka ciąg, który nie jest zgodny ze znanym poleceniem, ta instrukcja trap wyświetla ciąg Command error trapped. Po uruchomieniu listy instrukcji trap program PowerShell zapisuje obiekt błędu do strumienia błędów, a następnie kontynuuje skrypt.

Program PowerShell używa typów wyjątków platformy .NET. W poniższym przykładzie określono typ błędu System.Exception:

trap [System.Exception] { 'An error trapped' }

Typ błędu CommandNotFoundException dziedziczy z typu System.Exception. Ta instrukcja wychwytuje wszelkie błędy zgłaszane przez nieznane polecenia. Wychwytuje również inne typy błędów.

Typ wyjątku dla błędu można znaleźć, sprawdzając obiekt błędu. W poniższym przykładzie pokazano, jak uzyskać pełną nazwę wyjątku dla ostatniego błędu w sesji:

nonsenseString
$Error[0].Exception.GetType().FullName

nonsenseString: The term 'nonsenseString' is not recognized as a name of a
cmdlet, function, script file, or executable program. Check the spelling
of the name, or if a path was included, verify that the path is correct
and try again.

System.Management.Automation.CommandNotFoundException

Skrypt może zawierać więcej niż jedną instrukcję trap. Tylko jedna instrukcja trap może wychwytować każdy typ błędu. W przypadku wystąpienia błędu zakończenia program PowerShell wyszukuje trap element z najbardziej konkretnym dopasowaniem, zaczynając od bieżącego skryptu wykonywania.

Poniższy przykładowy skrypt zawiera błąd. Skrypt zawiera ogólną instrukcję trap, która wychwytuje wszelkie błędy końcowe, oraz określoną instrukcję trap, która definiuje typ błędu CommandNotFoundException.

trap { 'Other terminating error trapped' }
trap [System.Management.Automation.CommandNotFoundException] {
  'Command error trapped'
}
nonsenseString

Uruchomienie tego skryptu daje następujący wynik:

Command error trapped
nonsenseString:
Line |
   5 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Ponieważ program PowerShell nie rozpoznaje nonsenseString jako polecenia cmdlet lub innego elementu, zwraca błąd CommandNotFoundException. Instrukcja trap wychwytuje ten konkretny błąd końcowy.

Poniższy przykładowy skrypt zawiera te same instrukcje trap z innym błędem:

trap { 'Other terminating error trapped' }
trap [System.Management.Automation.CommandNotFoundException] {
    'Command error trapped'
}
1/$null

Uruchomienie tego skryptu daje następujący wynik:

Other terminating error trapped
RuntimeException:
Line |
   5 |  1/$null
     |  ~~~~~~~
     | Attempted to divide by zero.

Próba podzielenia przez zero nie powoduje utworzenia błędu CommandNotFoundException. Druga instrukcja trap, która wychwytuje wszelkie błędy zakończenia, wychwytuje błąd dzielenia przez zero.

Błędy podlewek w bloku skryptów

Domyślnie po wystąpieniu błędu zakończenia wykonywanie jest transferowane do instrukcji trap. Po uruchomieniu bloku trap kontrolka powraca do następnego bloku instrukcji po lokalizacji błędu.

Na przykład w przypadku wystąpienia błędu zakończenia w foreach instrukcji instrukcja jest uruchamiana, trap a wykonanie jest kontynuowane w następnej instrukcji po foreach bloku, a nie w foreach bloku.

trap { 'An error occurred!'}
foreach ($x in 3..-1) {
       "1/$x = "
       "`t$(1/$x)"
}
'after loop'

1/3 =
        0.333333333333333
1/2 =
        0.5
1/1 =
        1
1/0 =
An error occurred!
RuntimeException:
Line |
   4 |         "`t$(1/$x)"
     |              ~~~~
     | Attempted to divide by zero.
after loop

W danych wyjściowych można zobaczyć, że pętle będą kontynuowane do ostatniej iteracji. Gdy skrypt próbuje podzielić wartość 1 przez 0, program PowerShell zgłasza błąd krytyczny. Skrypt pomija pozostałą część instrukcji foreach , uruchamia instrukcję try i kontynuuje działanie po instrukcji foreach .

Przechwytywanie błędów i zakres

Jeśli błąd zakończenia występuje w tym samym skrypcie blok co trap instrukcja, program PowerShell uruchamia listę instrukcji zdefiniowanych przez trap. Wykonanie jest kontynuowane w instrukcji po błędzie. trap Jeśli instrukcja znajduje się w innym skrybloku od błędu, wykonanie będzie kontynuowane w następnej instrukcji, która znajduje się w tym samym skrybloku trap co instrukcja .

Jeśli na przykład wystąpi błąd w funkcji, a instrukcja trap znajduje się w funkcji, skrypt będzie kontynuowany w następnej instrukcji. Poniższy skrypt zawiera błąd i instrukcję trap:

function function1 {
    trap { 'An error: ' }
    NonsenseString
    'function1 was completed'
}

function1

Uruchomienie tego skryptu daje następujący wynik:

An error:
NonsenseString:
Line |
   3 |      NonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'NonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.
function1 was completed

Instrukcja trap w funkcji wychwyci błąd. Po wyświetleniu komunikatu program PowerShell wznowi uruchomienie funkcji. Zwróć uwagę, że Function1 został ukończony po instrukcji trap.

Porównaj to zachowanie z poniższym przykładem, który zawiera ten sam błąd i instrukcję trap. W tym przykładzie instrukcja trap występuje poza funkcją:

function function2 {
    NonsenseString
    'function2 was completed'
}

trap { 'An error:' }

function2

Uruchomienie funkcji Function2 daje następujący wynik:

An error:
NonsenseString:
Line |
   2 |      NonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'NonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

W tym przykładzie polecenie function2 was completed nie zostało uruchomione. W obu przykładach w funkcji występuje błąd końcowy. W tym przykładzie jednak instrukcja trap znajduje się poza funkcją . Program PowerShell nie wraca do funkcji po uruchomieniu instrukcji trap.

Ostrożność

Jeśli dla tego samego warunku błędu zdefiniowano wiele pułapek, jest używany pierwszy trap zdefiniowany leksykalnie (najwyższy w bloku skryptów).

W poniższym przykładzie działa tylko trap z whoops 1.

Remove-Item -ErrorAction Stop ThisFileDoesNotExist
trap { 'whoops 1'; continue }
trap { 'whoops 2'; continue }

Ważny

Instrukcja trap jest ograniczona do miejsca kompilowania. Jeśli masz instrukcję trap wewnątrz funkcji lub skryptu używającego notacji kropkowej, to gdy funkcja lub skrypt kończą działanie, wszystkie instrukcje trap wewnątrz zostaną usunięte.

Używanie słów kluczowych break i continue

Słowa kluczowe break i continue można użyć w instrukcji trap, aby określić, czy skrypt lub polecenie będzie nadal działać po błędzie zakończenia.

Jeśli dołączysz instrukcję break na liście instrukcji trap, program PowerShell zatrzyma funkcję lub skrypt. Następująca przykładowa funkcja używa słowa kluczowego break w instrukcji trap:

function break_example {
    trap {
        'Error trapped'
        break
    }
    1/$null
    'Function completed.'
}

break_example

Error trapped
ParentContainsErrorRecordException:
Line |
   6 |      1/$null
     |      ~~~~~~~
     | Attempted to divide by zero.

Ponieważ instrukcja trap zawierała słowo kluczowe break, funkcja nie będzie nadal działać, a wiersz Function completed nie jest uruchamiany.

Jeśli w instrukcji continue dołączysz słowo kluczowe trap, PowerShell wznawia działanie po instrukcji, która spowodowała błąd, tak samo jak bez break lub continue. Jednak w przypadku słowa kluczowego continue program PowerShell nie zapisuje błędu w strumieniu błędów.

Następująca przykładowa funkcja używa słowa kluczowego continue w instrukcji trap:

function ContinueExample {
    trap {
        'Error trapped'
        continue
    }
    foreach ($x in 3..-1) {
       "1/$x = "
       "`t$(1/$x)"
    }
    'End of function'
}

ContinueExample

1/3 =
        0.333333333333333
1/2 =
        0.5
1/1 =
        1
1/0 =
Error trapped
End of function

Funkcja zostanie wznowiona po uwięzieniu błędu, a instrukcja End of function zostanie uruchomiona. Żaden błąd nie jest zapisywany w strumieniu błędów.

Notatki

trap instrukcje umożliwiają zapewnienie obsługi wszystkich błędów zakończenia w bloku skryptów. Aby uzyskać bardziej szczegółową obsługę błędów, użyj try/catch bloków, w których pułapki są definiowane przy użyciu catch instrukcji. Instrukcje catch dotyczą tylko kodu w skojarzonej instrukcji try. Aby uzyskać więcej informacji, zobacz about_Try_Catch_Finally.

Zobacz także

• about_Break
• o_Kontynuuj
• about_Scopes
• about_Throw
• o_Try_Catch_Finally