Informacje o funkcjach CmdletBindingAttributeAbout Functions CmdletBindingAttribute

06/11/2020
Czas czytania: 3 min

Krótki opisShort description

Opisuje atrybut, który sprawia, że funkcja działa jak skompilowane polecenie cmdlet.Describes the attribute that makes a function work like a compiled cmdlet.

Długi opisLong description

Ten CmdletBinding atrybut jest atrybutem funkcji, które umożliwiają ich działanie, takie jak skompilowane polecenia cmdlet zapisane w języku C#.The CmdletBinding attribute is an attribute of functions that makes them operate like compiled cmdlets written in C#. Zapewnia dostęp do funkcji poleceń cmdlet.It provides access to the features of cmdlets.

Program PowerShell wiąże parametry funkcji, które mają CmdletBinding atrybut w taki sam sposób, jak powiązanie parametrów skompilowanych poleceń cmdlet.PowerShell binds the parameters of functions that have the CmdletBinding attribute in the same way that it binds the parameters of compiled cmdlets. $PSCmdletZmienna automatyczna jest dostępna dla funkcji z CmdletBinding atrybutem, ale $Args zmienna nie jest dostępna.The $PSCmdlet automatic variable is available to functions with the CmdletBinding attribute, but the $Args variable is not available.

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 parametru.In functions that have the CmdletBinding attribute, unknown parameters and positional arguments that have no matching positional parameters cause parameter binding to fail.

Uwaga

Skompilowane polecenia cmdlet używają wymaganego Cmdlet atrybutu, który jest podobny do CmdletBinding atrybutu, który jest opisany w tym temacie.Compiled cmdlets use the required Cmdlet attribute, which is similar to the CmdletBinding attribute that is described in this topic.

SkładniaSyntax

Poniższy przykład pokazuje Format funkcji, która określa wszystkie opcjonalne argumenty CmdletBinding atrybutu.The following example shows the format of a function that specifies all the optional arguments of the CmdletBinding attribute. Poniżej przedstawiono krótki opis każdego argumentu.A brief description of each argument follows this example.

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

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

ConfirmImpactConfirmImpact

Argument ConfirmImpact określa, kiedy akcja funkcji powinna zostać potwierdzona przez wywołanie metody ShouldProcess .The ConfirmImpact argument specifies when the action of the function should be confirmed by a call to the ShouldProcess method. Wywołanie metody ShouldProcess powoduje wyświetlenie monitu o potwierdzenie tylko wtedy, gdy argument ConfirmImpact jest równy lub większy niż wartość $ConfirmPreference zmiennej preferencji.The call to the ShouldProcess method displays a confirmation prompt only when the ConfirmImpact argument is equal to or greater than the value of the $ConfirmPreference preference variable. (Wartość domyślna argumentu to Średni ). Ten argument należy określić tylko wtedy, gdy jest również określony argument SupportsShouldProcess .(The default value of the argument is Medium.) Specify this argument only when the SupportsShouldProcess argument is also specified.

Aby uzyskać więcej informacji na temat żądań potwierdzenia, zobacz żądanie potwierdzenia.For more information about confirmation requests, see Requesting Confirmation.

DefaultParameterSetNameDefaultParameterSetName

Argument DefaultParameterSetName określa nazwę zestawu parametrów, który będzie próbować użyć programu PowerShell, gdy nie można określić, który parametr ma być używany.The DefaultParameterSetName argument specifies the name of the parameter set that PowerShell will attempt to use when it cannot determine which parameter set to use. Można uniknąć tego problemu, wprowadzając unikatowy parametr dla każdego parametru Ustaw obowiązkowy parametr.You can avoid this issue by making the unique parameter of each parameter set a mandatory parameter.

HelpURIHelpURI

Argument HelpURI określa adres internetowy tematu pomocy, który opisuje funkcję.The HelpURI argument specifies the internet address of the online version of the help topic that describes the function. Wartość argumentu HelpURI musi rozpoczynać się od ciągu "http" lub "https".The value of the HelpURI argument must begin with "http" or "https".

Wartość argumentu HelpURI jest używana dla wartości właściwości HelpURI obiektu CommandInfo , który Get-Command zwraca dla funkcji.The HelpURI argument value is used for the value of the HelpURI property of the CommandInfo object that Get-Command returns for the function.

Jednak jeśli pliki pomocy są zainstalowane na komputerze, a wartość pierwszego linku w sekcji RelatedLinks w pliku pomocy jest identyfikatorem 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.However, when help files are installed on the computer and the value of the first link in the RelatedLinks section of the help file is a URI, or the value of the first .Link directive in comment-based help is a URI, the URI in the help file is used as the value of the HelpUri property of the function.

Get-HelpPolecenie cmdlet używa wartości właściwości HelpURI , aby znaleźć wersję online tematu pomocy funkcji, gdy parametr online Get-Help jest określony w poleceniu.The Get-Help cmdlet uses the value of the HelpURI property to locate the online version of the function help topic when the Online parameter of Get-Help is specified in a command.

SupportsPagingSupportsPaging

Argument SupportsPaging dodaje do funkcji pierwsze parametry, Skip i IncludeTotalCount .The SupportsPaging argument adds the First , Skip , and IncludeTotalCount parameters to the function. Te parametry umożliwiają użytkownikom wybór danych wyjściowych z bardzo dużego zestawu wyników.These parameters allow users to select output from a very large result set. Ten argument jest przeznaczony dla poleceń cmdlet i funkcji, które zwracają dane z dużych magazynów danych, które obsługują wybór danych, takich jak baza danych SQL.This argument is designed for cmdlets and functions that return data from large data stores that support data selection, such as an SQL database.

Ten argument został wprowadzony w programie Windows PowerShell 3,0.This argument was introduced in Windows PowerShell 3.0.

Pierwszy : Pobiera tylko pierwsze "n" obiektów.First : Gets only the first 'n' objects.
Pomiń : ignoruje pierwsze "n" obiektów, a następnie pobiera pozostałe obiekty.Skip : Ignores the first 'n' objects and then gets the remaining objects.
IncludeTotalCount : raportuje liczbę obiektów w zestawie danych (liczba całkowita), po których następuje obiekty.IncludeTotalCount : Reports the number of objects in the data set (an integer) followed by the objects. Jeśli polecenie cmdlet nie może określić łącznej liczby, zwraca "nieznaną liczbę całkowitą".If the cmdlet cannot determine the total count, it returns "Unknown total count".

Program PowerShell zawiera NewTotalCount , metodę pomocnika, która pobiera łączną wartość licznika do zwrócenia i zawiera oszacowanie dokładności łącznej wartości licznika.PowerShell includes NewTotalCount , a helper method that gets the total count value to return and includes an estimate of the accuracy of the total count value.

Poniższa funkcja Przykładowa pokazuje, jak dodać obsługę parametrów stronicowania do funkcji zaawansowanej.The following sample function shows how to add support for the paging parameters to an advanced function.

function Get-Numbers {
    [CmdletBinding(SupportsPaging = $true)]
    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
}

SupportsShouldProcessSupportsShouldProcess

Argument SupportsShouldProcess dodaje do funkcji parametry Confirm i whatIf .The SupportsShouldProcess argument adds Confirm and WhatIf parameters to the function. Potwierdzenie parametru powoduje wyświetlenie przez użytkownika przed uruchomieniem polecenia dla każdego obiektu w potoku.The Confirm parameter prompts the user before it runs the command on each object in the pipeline. Parametr whatIf wyświetla zmiany wprowadzone przez polecenie zamiast uruchamiania polecenia.The WhatIf parameter lists the changes that the command would make, instead of running the command.

PositionalBindingPositionalBinding

Argument PositionalBinding określa, czy parametry w funkcji domyślnie są pozycjonowane.The PositionalBinding argument determines whether parameters in the function are positional by default. Wartość domyślna to $True.The default value is $True. Aby wyłączyć powiązanie pozycyjne, można użyć argumentu PositionalBinding z wartością $False .You can use the PositionalBinding argument with a value of $False to disable positional binding.

Argument PositionalBinding jest wprowadzany w programie Windows PowerShell 3,0.The PositionalBinding argument is introduced in Windows PowerShell 3.0.

Gdy parametry są pozycyjne, nazwa parametru jest opcjonalna.When parameters are positional, the parameter name is optional. Program PowerShell kojarzy nienazwane wartości parametrów z parametrami funkcji zgodnie z kolejnością lub położeniem nienazwanych wartości parametrów w poleceniu funkcji.PowerShell associates unnamed parameter values with the function parameters according to the order or position of the unnamed parameter values in the function command.

Gdy parametry nie są pozycyjne ("nazwane"), w poleceniu jest wymagana nazwa parametru (lub skrót lub alias nazwy).When parameters are not positional (they are "named"), the parameter name (or an abbreviation or alias of the name) is required in the command.

Gdy PositionalBinding jest $True , parametry funkcji są domyślnie pozycyjne.When PositionalBinding is $True, function parameters are positional by default. Program PowerShell przypisuje numer pozycji do parametrów w kolejności, w jakiej są one zadeklarowane w funkcji.PowerShell assigns position number to the parameters in the order in which they are declared in the function.

Gdy PositionalBinding jest $False , parametry funkcji nie są domyślnie pozycyjne.When PositionalBinding is $False, function parameters are not positional by default. Jeśli argument Position atrybutu jest zadeklarowany w parametrze , nazwa parametru (lub alias lub skrót) musi być uwzględniona, gdy parametr jest używany w funkcji.Unless the Position argument of the Parameter attribute is declared on the parameter, the parameter name (or an alias or abbreviation) must be included when the parameter is used in a function.

Argument Position atrybutu Parameter ma pierwszeństwo przed wartością domyślną PositionalBinding .The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. Można użyć argumentu Position , aby określić wartość pozycji dla parametru.You can use the Position argument to specify a position value for a parameter. Aby uzyskać więcej informacji na temat argumentu Position , zobacz about_Functions_Advanced_Parameters.For more information about the Position argument, see about_Functions_Advanced_Parameters.

UwagiNotes

Argument SupportsTransactions nie jest obsługiwany w zaawansowanych funkcjach.The SupportsTransactions argument is not supported in advanced functions.