about_Functions_CmdletBindingAttribute

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.

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

Poniższy przykład przedstawia format funkcji, która określa wszystkie opcjonalne argumenty atrybutu CmdletBinding . Krótki opis każdego argumentu jest zgodny z tym przykładem.

{
    [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{}
}

Potwierdzanie ćwierkanie

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 zostanie również określony argument SupportsShouldProcess .

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

DefaultParameterSetName

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

Identyfikator HELPURI

Argument HelpURI określa adres internetowy wersji online tematu pomocy, który opisuje 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 zwracanego Get-Command dla funkcji.

Jednak gdy pliki pomocy są instalowane na komputerze, a wartość pierwszego linku w sekcji RelatedLinks pliku pomocy jest identyfikatorem URI lub wartością pierwszej .Link dyrektywy w pomocy opartej na komentarzach jest identyfikator 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-HelpOnline polecenia jest określony w poleceniu.

Obsługa punktów przejściowych

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 Windows PowerShell 3.0.

  • Pierwszy: pobiera tylko pierwsze obiekty "n".
  • Pomiń: ignoruje pierwsze obiekty "n", a następnie pobiera pozostałe obiekty.
  • IncludeTotalCount: zgłasza 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 dodaje parametry Confirm i WhatIf do funkcji. Parametr Confirm monituje użytkownika przed uruchomieniem polecenia dla każdego obiektu w potoku. Parametr WhatIf wyświetla zmiany wprowadzone przez polecenie zamiast uruchamiać polecenie .

Powiązanie pozycyjne

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

Argument PositionalBinding jest wprowadzany w 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 pozycjaAlBinding to $True, parametry funkcji są domyślnie pozycyjne. Program PowerShell przypisuje numer pozycji do parametrów w kolejności, w której są deklarowane w funkcji.

Gdy parametr positionalBinding to $False, parametry funkcji nie są domyślnie pozycyjne. Jeśli argument pozycji 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 Pozycji 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 Pozycji , zobacz about_Functions_Advanced_Parameters.

Uwagi

Argument Obsługuje transakcje nie jest obsługiwany w funkcjach zaawansowanych.

Słowa kluczowe

about_Functions_CmdletBinding_Attribute

Zobacz też