about_Functions_CmdletBindingAttribute

Artykuł
07/03/2024

Krótki opis

Opisuje atrybut, który sprawia, że funkcja działa jak skompilowane polecenie cmdlet.

Długi opis

Atrybut CmdletBinding jest atrybutem funkcji, które sprawiają, że działają jak skompilowane polecenia cmdlet napisane w języku C#. Zapewnia dostęp do funkcji poleceń cmdlet.

Gdy używasz atrybutu CmdletBinding , program PowerShell automatycznie dodaje parametry wspólne. Nie można utworzyć żadnych parametrów, które używają tych samych nazw co common parameters. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Program PowerShell wiąże parametry funkcji, które mają CmdletBinding atrybut w taki sam sposób, jak wiąże parametry skompilowanych poleceń cmdlet. Zmienna automatyczna $PSCmdlet jest dostępna dla funkcji z atrybutem CmdletBinding , ale zmienna $Args nie jest dostępna.

W funkcjach, które mają CmdletBinding atrybut, nieznane parametry i argumenty pozycyjne, które nie mają pasujących parametrów pozycyjnych, powodują niepowodzenie powiązania parametrów.

Uwaga

Skompilowane polecenia cmdlet używają wymaganego Cmdlet atrybutu, który jest podobny do atrybutu opisanego CmdletBinding w tym temacie.

Składnia

W poniższym przykładzie pokazano format funkcji, która określa wszystkie opcjonalne argumenty atrybutu CmdletBinding . W tym przykładzie przedstawiono krótki opis każdego argumentu.

{
    [CmdletBinding(ConfirmImpact=<String>,
    DefaultParameterSetName=<String>,
    HelpURI=<URI>,
    SupportsPaging=<Boolean>,
    SupportsShouldProcess=<Boolean>,
    PositionalBinding=<Boolean>)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

Typy argumentów logicznych atrybutu CmdletBinding domyślnie mają wartość False po pominięciu atrybutu CmdletBinding . Ustaw wartość argumentu na $true lub po prostu wyświetl argument według nazwy. Na przykład następujące atrybuty cmdletBinding są równoważne.

{
    [CmdletBinding(SupportsPaging=$true)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

ConfirmImpact

Argument ConfirmImpact określa, kiedy akcja funkcji powinna zostać potwierdzona przez wywołanie metody ShouldProcess. Wywołanie metody ShouldProcess wyświetla monit o potwierdzenie tylko wtedy, gdy argument ConfirmImpact jest równy lub większy niż wartość zmiennej $ConfirmPreference preferencji. (Wartość domyślna argumentu to Średni.) Określ ten argument tylko wtedy, gdy określono również argument SupportsShouldProcess .

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

DefaultParameterSetName

Argument DefaultParameterSetName określa nazwę zestawu parametrów, którego program PowerShell będzie próbował użyć, gdy nie może określić, który parametr ma być używany. Ten problem można uniknąć, tworząc unikatowy parametr każdego parametru ustawiając obowiązkowy parametr.

Identyfikator URI Pomocy

Argument HelpURI określa adres internetowy wersji online tematu pomocy opisującego funkcję. Wartość argumentu HelpURI musi zaczynać się od ciągu "http" lub "https".

Wartość argumentu HelpURI jest używana dla wartości właściwości HelpURI obiektu CommandInfo, który Get-Command zwraca dla funkcji.

Jeśli jednak pliki pomocy są instalowane na komputerze, a wartość pierwszego linku w sekcji RelatedLinks pliku pomocy to identyfikator URI lub wartość pierwszej .Link dyrektywy w pomocy opartej na komentarzach jest identyfikatorem URI, identyfikator URI w pliku pomocy jest używany jako wartość właściwości HelpUri funkcji.

Polecenie Get-Help cmdlet używa wartości właściwości HelpURI, aby zlokalizować wersję online tematu pomocy funkcji, gdy parametr Get-Help Online polecenia jest określony w poleceniu.

Obsługa etapu przejściowego

Argument SupportsPaging dodaje do funkcji parametry First, Skip i IncludeTotalCount . Te parametry umożliwiają użytkownikom wybieranie danych wyjściowych z bardzo dużego zestawu wyników. Ten argument jest przeznaczony dla poleceń cmdlet i funkcji, które zwracają dane z dużych magazynów danych obsługujących wybór danych, takich jak baza danych SQL.

Ten argument został wprowadzony w programie Windows PowerShell 3.0.

Najpierw: pobiera tylko pierwsze obiekty "n".
Pomiń: ignoruje pierwsze obiekty "n", a następnie pobiera pozostałe obiekty.
IncludeTotalCount: raportuje liczbę obiektów w zestawie danych (liczba całkowita), a następnie obiekty. Jeśli polecenie cmdlet nie może określić łącznej liczby, zwraca wartość "Nieznana łączna liczba".

Program PowerShell zawiera wartość NewTotalCount, metodę pomocnika, która pobiera łączną wartość licznika do zwrócenia i zawiera oszacowanie dokładności łącznej wartości liczbowej.

Poniższa przykładowa funkcja pokazuje, jak dodać obsługę parametrów stronicowania do funkcji zaawansowanej.

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    param()

    $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
    $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
      $FirstNumber - 1, 100)

    if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
        $TotalCountAccuracy = 1.0
        $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
          $TotalCountAccuracy)
        Write-Output $TotalCount
    }
    $FirstNumber .. $LastNumber | Write-Output
}

SupportsShouldProcess

Argument SupportsShouldProcess dodajeparametry Confirm i WhatIf do funkcji. Parametr Confirm monituje użytkownika przed uruchomieniem polecenia dla każdego obiektu w potoku. W parametrze WhatIf wymieniono zmiany wprowadzone przez polecenie zamiast uruchamiać polecenie .

Powiązanie pozycyjne

Argument PositionalBinding określa, czy parametry w funkcji są domyślnie pozycyjne. Domyślna wartość to $True. Możesz użyć argumentu PositionalBinding z wartością $False , aby wyłączyć powiązanie pozycyjne.

Argument PositionalBinding jest wprowadzany w programie Windows PowerShell 3.0.

Gdy parametry są pozycyjne, nazwa parametru jest opcjonalna. Program PowerShell kojarzy nienazwane wartości parametrów z parametrami funkcji zgodnie z kolejnością lub pozycją nienazwanych wartości parametrów w poleceniu funkcji.

Jeśli parametry nie są pozycyjne (są "nazwane"), nazwa parametru (lub skrót lub alias nazwy) jest wymagana w poleceniu.

Gdy parametr PositionalBinding to $True, parametry funkcji są domyślnie pozycyjne. Program PowerShell przypisuje numer pozycji do parametrów w kolejności, w której są zadeklarowane w funkcji.

Gdy parametr PositionalBinding to $False, parametry funkcji nie są domyślnie pozycyjne. Jeśli argument Position atrybutu Parametr nie zostanie zadeklarowany w parametrze, nazwa parametru (lub alias lub skrót) musi być uwzględniona, gdy parametr jest używany w funkcji.

Argument Position atrybutu Parametr ma pierwszeństwo przed wartością domyślną PositionalBinding. Możesz użyć argumentu Pozycja , aby określić wartość pozycji dla parametru. Aby uzyskać więcej informacji na temat argumentu Position , zobacz about_Functions_Advanced_Parameters.

Uwagi

Argument SupportsTransactions nie jest obsługiwany w funkcjach zaawansowanych.

Słowa kluczowe

about_Functions_CmdletBinding_Attribute

Udostępnij za pośrednictwem