Udostępnij za pośrednictwem

about_Functions_Advanced_Methods

  • Artykuł

Krótki opis

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

Długi opis

Funkcje określające CmdletBinding atrybut 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 generowania ThrowTerminatingError 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 zapoznać się z klasą CmdletBindingAttribute , 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 beginbloki funkcji , processi end . 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 end bloku funkcji. Jeśli jednak używasz dowolnego z tych nazwanych bloków lub zdefiniuj dynamicparam blok, musisz umieścić cały kod w nazwanym bloku.

W poniższym przykładzie przedstawiono konspekt funkcji, która zawiera begin blok jednorazowego przetwarzania wstępnego, process blok przetwarzania wielu rekordów i end blok jednorazowego przetwarzania końcowego.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

Uwaga

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 można używać process bez definiowania innych bloków. process Liczba wykonań 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 process bloku. Zmienna automatyczna $input zawiera moduł wyliczający 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 process blok raz.
  • W potoku process blok 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, process blok nie jest wykonywany.
    • Bloki begin, endi clean nadal są wykonywane.

Ważne

Jeśli parametr funkcji jest ustawiony na akceptowanie danych wejściowych potoku, a process blok 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 CmdletBindingmetody , process blok 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 beginbloki , i end . process Jest to semantycznie podobne do finally bloku, który obejmuje wszystkie inne nazwane bloki funkcji skryptu lub polecenia 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 za pomocą klawiszy Ctrl+c lub StopProcessing()

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

Uwaga

clean Dodanie bloku to zmiana powodująca niezgodność. Ponieważ clean jest analizowany jako słowo kluczowe, uniemożliwia użytkownikom bezpośrednie wywoływanie polecenia o nazwie clean jako pierwszej instrukcji w bloku skryptu. 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, ShouldProcess gdy metoda zwraca $truewartość . 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, który nie kończy się, funkcja powinna wywołać metodę opisaną WriteError w Write sekcji metody. 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 do kończenie błędów i polecenia cmdlet Write-Error w przypadku 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żesz również użyć różnych Write poleceń cmdlet, 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.

Uwaga

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 jest to metoda używana, WriteObject 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 WriteProgress metody tak, aby wyświetlane informacje 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 w celu wyświetlenia pełnych komunikatów 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.

Uwaga

Komunikaty ostrzegawcze można również wyświetlić, konfigurując zmienną $WarningPreference lub przy użyciu Verbose opcji wiersza polecenia i Debug . 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 też