about_Functions_CmdletBindingAttribute

Článek
07/02/2024

Krátký popis

Popisuje atribut, který dělá funkci jako zkompilovanou rutinu.

Dlouhý popis

Atribut CmdletBinding je atribut funkcí, díky kterým fungují jako zkompilované rutiny napsané v jazyce C#. Poskytuje přístup k funkcím rutin.

Při použití atributu CmdletBinding PowerShell automaticky přidá společné parametry. Nemůžete vytvořit žádné parametry, které používají stejné názvy jako společné parametry. Další informace najdete v tématu about_CommonParameters.

PowerShell vytvoří vazbu parametrů funkcí, které mají CmdletBinding atribut stejným způsobem, jakým sváže parametry zkompilovaných rutin. Automatická $PSCmdlet proměnná je dostupná pro funkce s atributem CmdletBinding , ale $Args proměnná není k dispozici.

Ve funkcích s atributem CmdletBinding , neznámými parametry a pozičními argumenty, které nemají odpovídající poziční parametry, způsobují selhání vazby parametrů.

Poznámka:

Zkompilované rutiny používají požadovaný Cmdlet atribut, který se podobá atributu CmdletBinding popsanému v tomto tématu.

Syntaxe

Následující příklad ukazuje formát funkce, která určuje všechny volitelné argumenty atributu CmdletBinding . Stručný popis každého argumentu následuje v tomto příkladu.

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

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

Logické typy argumentů atributu CmdletBinding se při vynechání z atributu CmdletBinding ve výchozím nastavení mají hodnotu False. Nastavte hodnotu argumentu na $true argument nebo ho uveďte podle názvu. Například následující atributy RutinBinding jsou ekvivalentní.

{
    [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 určuje, kdy má být akce funkce potvrzena voláním Metody ShouldProcess . Volání Metody ShouldProcess zobrazí výzvu k potvrzení pouze v případě , že argument ConfirmImpact je roven nebo větší než hodnota $ConfirmPreference proměnné předvolby. (Výchozí hodnota argumentu je Střední.) Tento argument zadejte pouze v případě, že je zadán také argument SupportsShouldProcess .

Další informace o žádostech o potvrzení najdete v tématu Žádost o potvrzení.

DefaultParameterSetName

Argument DefaultParameterSetName určuje název sady parametrů, kterou se PowerShell pokusí použít, pokud nemůže určit, který parametr se má použít. Tomuto problému se můžete vyhnout tím, že jedinečný parametr každého parametru nastavíte jako povinný parametr.

Identifikátor HELPURI

Argument HelpURI určuje internetovou adresu online verze tématu nápovědy, která popisuje funkci. Hodnota argumentu HelpURI musí začínat řetězcem http nebo https.

Hodnota argumentu HelpURI se používá pro hodnotu HelpURI vlastnost CommandInfo objektu, který Get-Command vrací pro funkci.

Pokud jsou však soubory nápovědy nainstalovány v počítači a hodnota prvního odkazu v části RelatedLinks souboru nápovědy je identifikátor URI nebo hodnota první .Link direktivy v nápovědě založené na komentáři je identifikátor URI, identifikátor URI v souboru nápovědy se použije jako hodnota vlastnosti HelpUri funkce.

Rutina Get-Help používá hodnotu vlastnosti HelpURI k vyhledání online verze tématu nápovědy funkce při zadání parametru Get-Help Online v příkazu.

SupportsPaging

Argument SupportsPaging přidá do funkce parametry First, Skip a IncludeTotalCount . Tyto parametry umožňují uživatelům vybrat výstup z velmi velké sady výsledků. Tento argument je určený pro rutiny a funkce, které vracejí data z velkých úložišť dat, která podporují výběr dat, jako je databáze SQL.

Tento argument byl zaveden ve Windows PowerShellu 3.0.

První: Získá pouze první "n" objekty.
Přeskočit: Přeskočí první n objekty a pak získá zbývající objekty.
IncludeTotalCount: Zaznamenává počet objektů v sadě dat (celé číslo) následované objekty. Pokud rutina nemůže určit celkový počet, vrátí neznámý celkový počet.

PowerShell obsahuje NewTotalCount, pomocnou metodu, která získá celkovou hodnotu počtu, která se má vrátit, a obsahuje odhad přesnosti celkové hodnoty počtu.

Následující ukázková funkce ukazuje, jak přidat podporu parametrů stránkování do pokročilé funkce.

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 přidá do funkce parametry Confirm a WhatIf . Parametr Confirm vyzve uživatele před spuštěním příkazu na každém objektu v kanálu. Parametr WhatIf uvádí změny, které by příkaz udělal, místo spuštění příkazu.

PositionalBinding

Argument PositionalBinding určuje, zda jsou parametry ve funkci ve výchozím nastavení poziční. Výchozí hodnota je $True. Argument PositionalBinding s hodnotou $False zakázání poziční vazby můžete použít.

Argument PositionalBinding je zaveden v prostředí Windows PowerShell 3.0.

Pokud jsou parametry poziční, název parametru je volitelný. PowerShell přidruží nepojmenované hodnoty parametrů k parametrům funkce podle pořadí nebo pozice nepojmenovaných hodnot parametrů v příkazu funkce.

Pokud parametry nejsou poziční (jsou pojmenované), v příkazu se vyžaduje název parametru (nebo zkratka nebo alias názvu).

Pokud je $TruePositionalBinding , parametry funkce jsou ve výchozím nastavení poziční. PowerShell přiřadí číslo pozice k parametrům v pořadí, ve kterém jsou deklarovány ve funkci.

Pokud je $FalsePositionalBinding , parametry funkce nejsou ve výchozím nastavení poziční. Pokud není argument Position atributu Parametr deklarován u parametru, musí být při použití parametru ve funkci zahrnut název parametru (nebo alias nebo zkratka).

Argument Position atributu Parameter má přednost před výchozí hodnotou PositionalBinding . Argument Pozice můžete použít k určení hodnoty pozice pro parametr. Další informace o argumentu Pozice najdete v tématu about_Functions_Advanced_Parameters.

Sdílet prostřednictvím