Obsługa błędów w narzędziu Crescendo

Przed Crescendo 1.1 błędy poleceń natywnych były przesyłane strumieniowo bezpośrednio do użytkownika, a nie przechwytywane przez Crescendo. Uniemożliwiło to utworzenie ulepszonej obsługi błędów. Teraz Crescendo może przechwytywać dane wyjściowe błędów (stderr) z natywnego polecenia.

Domyślnie, jeśli nie zdefiniujesz procedury obsługi danych wyjściowych, Crescendo używa domyślnej procedury obsługi. Domyślna procedura obsługi danych wyjściowych zapewnia, że błędy uwzględniają -ErrorVariable parametry i -ErrorAction i dodaje błędy do $Error. Jeśli ustawisz HandlerType wartość ByPass, Crescendo nie przechwytuje błędów, a wszystkie dane wyjściowe są przesyłane strumieniowo bezpośrednio do użytkownika.

Crescendo v1.1 dodaje dwie wewnętrzne funkcje do zarządzania błędami.

• Push-CrescendoNativeError Dodaje błędy do kolejki błędów. Ta funkcja jest automatycznie wywoływana przez program obsługi danych wyjściowych. Nie musisz dzwonić do niego bezpośrednio.
• Pop-CrescendoNativeError Usuwa błąd z kolejki błędów. Ta funkcja służy do sprawdzania błędów w procedurze obsługi danych wyjściowych, aby można było je obsłużyć lub przekazać do obiektu wywołującego.

Domyślnie $PSNativeCommandUseErrorActionPreference jest ustawiona na wartość $true. Powoduje to, że Crescendo generuje dodatkowy rekord błędu dla każdego błędu. Aby temu zapobiec, Crescendo zmienia wartość na $false dla każdego wygenerowanego polecenia cmdlet. Ta zmiana jest ograniczona do poleceń cmdlet w wygenerowanym module, więc nie ma wpływu na polecenia cmdlet poza modułem.

Zwracanie błędów do użytkownika

Poniższa definicja programu obsługi danych wyjściowych służy Pop-CrescendoNativeError do zwracania błędów do użytkownika.

"OutputHandlers": [
    {
        "ParameterSetName": "Default",
        "StreamOutput": true,
        "HandlerType": "Inline",
        "Handler": "PROCESS { $_ } END { Pop-CrescendoNativeError -EmitAsError }"
    }
]

Przykład — polecenie natywne zapisuje informacje i błędy na standardowe wyjście błędów

Rozważmy następujący scenariusz. Masz narzędzie wiersza polecenia, które wykonuje następujące czynności:

• Zapisuje wiadomości informacyjne, takie jak tekst banera, postęp i inne, aby stderr
• Zapisuje komunikaty o błędach do stderr
• Zapisuje pomyślne dane wyjściowe danych do stdout

Chcesz utworzyć procedurę obsługi danych wyjściowych Crescendo, która może rozróżniać komunikaty informacyjne i błędy, a także konwertować dane z pomyślnych danych wyjściowych na obiekty programu PowerShell.

W poniższych przykładach przedstawiono fikcyjne narzędzie wiersza polecenia o nazwie fizztool.exe , które ma zachowanie opisane wcześniej.

Udany przykład

Oto przykładowe wywołanie narzędzia, które powinno zakończyć się powodzeniem:

fizztool.exe --key fizz

Wiersz praw autorskich jest zapisywany na stderr, a obiekt JSON jest zapisywany na standardowe wyjście.

fizztool.exe v1.0.0 (c) 2021 Tailspin Toys, Ltd.

{
    "fizz": "buzz"
}

Jeśli uruchomisz go z programu PowerShell, zobaczysz następujące dane wyjściowe:

fizztool.exe --key fizz | ConvertFrom-Json

fizztool.exe v1.0.0 (c) 2021 Tailspin Toys, Ltd.

fizz
----
buzz

Przykład niepowodzenia

Oto przykładowe wywołanie narzędzia, które powoduje błąd:

fizztool.exe --key buzz

Wiersz praw autorskich i komunikat o błędzie są zapisywane w .stderr

fizztool.exe v1.0.0 (c) 2021 Tailspin Toys, Ltd.
ERROR: Key not found: buzz

Jeśli uruchomisz go z programu PowerShell, zobaczysz następujące dane wyjściowe:

fizztool.exe --key buzz | ConvertFrom-Json

fizztool.exe v1.0.0 (c) 2021 Tailspin Toys, Ltd.
ERROR: Key not found: buzz

Postępowanie z błędami w Crescendo

Poniższa konfiguracja Crescendo definiuje polecenie cmdlet Get-FizzBuzz , które wywołuje fizztool.exemetodę , przetwarza dane wyjściowe i obsługuje warunki błędów.

{
    "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
    "Commands": [
        {
            "Verb": "Get",
            "Noun": "FizzBuzz",
            "OriginalName": "fizztool",
            "Parameters": [
                {
                    "Name": "Key",
                    "OriginalName": "--key",
                    "ParameterType": "string",
                    "OriginalPosition": 0,
                    "Required": true
                },
            ],
            "OutputHandlers": [
                {
                    "ParameterSetName": "Default",
                    "HandlerType": "Function",
                    "Handler": "FizzToolParser"
                }
            ]
        }
    ]
}

Program obsługi danych wyjściowych używa następującej FizzToolParser funkcji do przetwarzania danych wyjściowych.

function FizzToolParser {
    param(
        [Parameter(Mandatory)]
        [AllowNull()]
        $cmdResults = ''
    )

    if ($null -ne $cmdResults) {
        $cmdResults | Out-String | ConvertFrom-Json
    } else {
        Pop-CrescendoNativeError |
            Where-Object {$_ -like 'ERROR:*'} |
            Write-Error
    }
}

Funkcja FizzToolParser wykonuje następujące akcje:

• Jeśli $cmdResults wartość nie ma wartości null, konwertuje dane wyjściowe JSON na obiekt programu PowerShell.
• Jeśli $cmdResults ma wartość null, sprawdza, czy nie ma błędów.
  • Pop-CrescendoNativeError Pobiera dane wyjściowe błędu z tej kolejki.
  • Błędy są filtrowane w celu wybrania wiadomości rozpoczynających się od ERROR:. Komunikaty informacyjne, takie jak informacja o prawach autorskich, są ignorowane.
  • Możesz sprawdzić błędy i obsłużyć je lub przekazać je do wywołującego, jak pokazano w funkcji.

Korzystanie z nowego polecenia cmdlet

Get-FizzBuzz -Key fizz

fizz
----
buzz

Get-FizzBuzz -Key buzz

Write-Error: ERROR: Key not found: buzz