Udostępnij za pośrednictwem

about_Functions_Advanced_Methods

Krótki opis

Opisuje, w jaki sposób funkcje określające atrybut CmdletBinding mogą używać metod i właściwości dostępnych do skompilowanych poleceń cmdlet.

Długi opis

Funkcje określające atrybut CmdletBinding mogą uzyskiwać dostęp do dodatkowych metod i właściwości za pośrednictwem zmiennej $PSCmdlet. Metody te obejmują następujące metody:

  • Te same metody przetwarzania wejściowego są dostępne dla wszystkich funkcji.
  • Metody ShouldProcess i ShouldContinue używane do uzyskiwania opinii użytkowników przed wykonaniem akcji.
  • Metoda ThrowTerminatingError generowania rekordów błędów.
  • Kilka Write metod, które zwracają różne typy danych wyjściowych.

Wszystkie metody i właściwości klasy PSCmdlet są dostępne dla funkcji zaawansowanych. Aby uzyskać więcej informacji, zobacz System.Management.Automation.PSCmdlet.

Aby uzyskać więcej informacji na temat atrybutu CmdletBinding, zobacz about_Functions_CmdletBindingAttribute. Aby uzyskać cmdletBindingAttribute klasy, zobacz System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Metody przetwarzania danych wejściowych

Metody opisane w tej sekcji są określane jako metody przetwarzania danych wejściowych. W przypadku funkcji te trzy metody są reprezentowane przez bloki begin, processi end funkcji. Program PowerShell 7.3 dodaje metodę procesu blokowego clean.

Nie musisz używać żadnych z tych bloków w funkcjach. Jeśli nie używasz nazwanego bloku, program PowerShell umieszcza kod w bloku end funkcji. Jeśli jednak używasz dowolnego z tych nazwanych bloków lub zdefiniuj blok dynamicparam, musisz umieścić cały kod w nazwanym bloku.

W poniższym przykładzie przedstawiono konspekt funkcji zawierającej blok begin jednorazowego przetwarzania wstępnego, blok process na potrzeby przetwarzania wielu rekordów oraz blok end jednorazowego przetwarzania końcowego.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Nuta

Te bloki dotyczą wszystkich funkcji, a nie tylko funkcji korzystających z atrybutu CmdletBinding.

begin

Ten blok służy do zapewnienia opcjonalnego jednorazowego przetwarzania wstępnego dla funkcji. Środowisko uruchomieniowe programu PowerShell używa kodu w tym bloku raz dla każdego wystąpienia funkcji w potoku.

process

Ten blok służy do udostępniania przetwarzania rekordów według rekordów dla funkcji. Blok process można użyć bez definiowania innych bloków. Liczba process wykonywania bloków zależy od sposobu używania funkcji i danych wejściowych odbieranych przez funkcję.

Zmienna automatyczna $_ lub $PSItem zawiera bieżący obiekt w potoku do użycia w bloku process. Zmienna automatyczna $input zawiera moduł wyliczający, który jest dostępny tylko dla funkcji i bloków skryptów. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

  • Wywołanie funkcji na początku lub poza potokiem wykonuje blok process raz.
  • W potoku blok process jest wykonywany raz dla każdego obiektu wejściowego, który dociera do funkcji.
  • Jeśli dane wejściowe potoku docierające do funkcji są puste, blok processnie wykonać.
    • Bloki begin, endi clean nadal są wykonywane.

Ważny

Jeśli parametr funkcji jest ustawiony na akceptowanie danych wejściowych potoku, a blok process nie jest zdefiniowany, przetwarzanie rekordu po rekordzie zakończy się niepowodzeniem. W takim przypadku funkcja będzie wykonywana tylko raz, niezależnie od danych wejściowych.

Podczas tworzenia funkcji, która akceptuje dane wejściowe potoku i używa CmdletBinding, blok process powinien używać zmiennej parametru zdefiniowanej dla danych wejściowych potoku zamiast $_ lub $PSItem. Na przykład:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

Ten blok służy do udostępniania opcjonalnego jednorazowego przetwarzania końcowego dla funkcji.

clean

Blok clean został dodany w programie PowerShell 7.3.

Blok clean jest wygodnym sposobem czyszczenia zasobów obejmujących begin, processi bloki end. Jest to semantycznie podobne do bloku finally, który obejmuje wszystkie inne nazwane bloki funkcji skryptu lub polecenie cmdlet skryptu. Czyszczenie zasobów jest wymuszane w następujących scenariuszach:

  1. gdy wykonywanie potoku kończy się normalnie bez przerywania błędu
  2. gdy wykonywanie potoku zostanie przerwane z powodu błędu zakończenia
  3. gdy potok zostanie zatrzymany przez Select-Object -First
  4. gdy potok jest zatrzymywany przez Ctrl+c lub StopProcessing()

Blok czysty odrzuca wszystkie dane wyjściowe zapisane w strumieniu Powodzenie.

Ostrożność

Dodanie bloku clean jest zmianą powodującą niezgodność. Ponieważ clean element jest analizowany jako słowo kluczowe, uniemożliwia użytkownikom bezpośrednie wywoływanie polecenia o nazwie clean jako pierwszej instrukcji w bloku skryptów. Jednak prawdopodobnie nie będzie to problem. Nadal można wywołać polecenie przy użyciu operatora wywołania (& clean).

Metody potwierdzenia

ShouldProcess

Ta metoda jest wywoływana w celu żądania potwierdzenia od użytkownika, zanim funkcja wykona akcję, która spowoduje zmianę systemu. Funkcja może kontynuować na podstawie wartości logicznej zwracanej przez metodę . Tę metodę można wywołać tylko z bloku process {} funkcji. Atrybut CmdletBinding musi również zadeklarować, że funkcja obsługuje ShouldProcess (jak pokazano w poprzednim przykładzie).

Aby uzyskać więcej informacji na temat tej metody, zobacz System.Management.Automation.Cmdlet.ShouldProcess.

Aby uzyskać więcej informacji na temat żądania potwierdzenia, zobacz Żądanie potwierdzenia.

ShouldContinue

Ta metoda jest wywoływana w celu żądania drugiego komunikatu potwierdzenia. Powinna być wywoływana, gdy metoda ShouldProcess zwraca wartość $true. Aby uzyskać więcej informacji na temat tej metody, zobacz System.Management.Automation.Cmdlet.ShouldContinue.

Metody błędów

Funkcje mogą wywoływać dwie różne metody w przypadku wystąpienia błędów. W przypadku wystąpienia błędu bez zakończenia funkcja powinna wywołać metodę WriteError opisaną w sekcji metody Write. Gdy wystąpi błąd zakończenia i funkcja nie może kontynuować, powinna wywołać metodę ThrowTerminatingError. Można również użyć instrukcji throw w celu zakończenia błędów i polecenia cmdlet Write-Error dla błędów niepowodujących zakończenia.

Aby uzyskać więcej informacji, zobacz System.Management.Automation.Cmdlet.ThrowTerminatingError.

Metody zapisu

Funkcja może wywołać następujące metody, aby zwrócić różne typy danych wyjściowych. Zwróć uwagę, że nie wszystkie dane wyjściowe przechodzą do następnego polecenia w potoku. Można również użyć różnych poleceń cmdlet Write, takich jak Write-Error.

WriteCommandDetail

Aby uzyskać informacje o metodzie WriteCommandDetails, zobacz System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Aby podać informacje, które mogą służyć do rozwiązywania problemów z funkcją, należy wywołać metodę WriteDebug. Metoda WriteDebug wyświetla komunikaty debugowania dla użytkownika. Aby uzyskać więcej informacji, zobacz System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Funkcje powinny wywoływać tę metodę, gdy wystąpią błędy niepowodujące zakończenia, a funkcja została zaprojektowana tak, aby kontynuować przetwarzanie rekordów. Aby uzyskać więcej informacji, zobacz System.Management.Automation.Cmdlet.WriteError.

Nuta

Jeśli wystąpi błąd zakończenia, funkcja powinna wywołać metodę ThrowTerminatingError.

WriteObject

Metoda WriteObject umożliwia funkcji wysyłanie obiektu do następnego polecenia w potoku. W większości przypadków WriteObject jest metodą używaną, gdy funkcja zwraca dane. Aby uzyskać więcej informacji, zobacz System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

W przypadku funkcji z akcjami, które trwają długo, ta metoda umożliwia funkcji wywoływanie metody WriteProgress w celu wyświetlenia informacji o postępie. Na przykład można wyświetlić procent ukończony. Aby uzyskać więcej informacji, zobacz System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Aby podać szczegółowe informacje o tym, co robi funkcja, należy wywołać metodę WriteVerbose, aby wyświetlić pełne komunikaty dla użytkownika. Domyślnie pełne komunikaty nie są wyświetlane. Aby uzyskać więcej informacji, zobacz System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Aby podać informacje o warunkach, które mogą powodować nieoczekiwane wyniki, należy wywołać metodę WriteWarning, aby wyświetlić użytkownikowi komunikaty ostrzegawcze. Domyślnie są wyświetlane komunikaty ostrzegawcze. Aby uzyskać więcej informacji, zobacz System.Management.Automation.PSCmdlet.WriteWarning.

Nuta

Można również wyświetlić komunikaty ostrzegawcze, konfigurując zmienną $WarningPreference lub używając opcji Verbose i Debug wiersza polecenia. Aby uzyskać więcej informacji na temat zmiennej $WarningPreference, zobacz about_Preference_Variables.

Inne metody i właściwości

Aby uzyskać informacje o innych metodach i właściwościach, do których można uzyskać dostęp za pośrednictwem zmiennej $PSCmdlet, zobacz System.Management.Automation.PSCmdlet.

Na przykład właściwość ParameterSetName umożliwia wyświetlenie używanego zestawu parametrów. Zestawy parametrów umożliwiają utworzenie funkcji wykonującej różne zadania na podstawie parametrów określonych podczas uruchamiania funkcji.

Zobacz także

  • Last updated on