about_Functions_CmdletBindingAttribute

Статья
07/02/2024

Краткое описание

Описывает атрибут, который делает функцию работой, как скомпилированный командлет.

Подробное описание

Атрибут CmdletBinding — это атрибут функций, которые делают их работать как скомпилированные командлеты, написанные на C#. Он предоставляет доступ к функциям командлетов.

При использовании атрибута CmdletBinding PowerShell автоматически добавляет общие параметры. Невозможно создать какие-либо параметры, использующие те же имена, что и общие параметры. Дополнительные сведения см. в разделе about_CommonParameters.

PowerShell привязывает параметры функций, имеющих CmdletBinding атрибут, так же, как и параметры скомпилированных командлетов. Автоматическая $PSCmdlet переменная доступна для функций с атрибутом CmdletBinding , но $Args переменная недоступна.

В функциях, имеющих CmdletBinding атрибут, неизвестные параметры и позиционные аргументы, которые не имеют соответствующих позиционных параметров, приводят к сбою привязки параметров.

Примечание.

Скомпилированные командлеты используют обязательный Cmdlet атрибут, CmdletBinding аналогичный атрибуту, описанному в этом разделе.

Синтаксис

В следующем примере показан формат функции, указывающей все необязательные аргументы атрибута CmdletBinding . Краткое описание каждого аргумента следует этому примеру.

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

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

Логические типы аргументов атрибута КомандлетBinding по умолчанию — False , если опущены из атрибута КомандлетBinding . Задайте значение $true аргумента или просто перечислите аргумент по имени. Например, следующие атрибуты КомандлетBinding эквивалентны.

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

Аргумент ConfirmImpact указывает, когда действие функции должно быть подтверждено вызовом метода MustProcess . Вызов метода ShouldProcess отображает запрос подтверждения только в том случае, если аргумент ConfirmImpact равен или больше значения переменной $ConfirmPreference предпочтения. (Значение аргумента по умолчанию — Средний.) Укажите этот аргумент, только если аргумент SupportsShouldProcess также указан.

Дополнительные сведения о запросах на подтверждение см. в разделе "Запрос подтверждения".

DefaultParameterSetName

Аргумент DefaultParameterSetName указывает имя набора параметров, который PowerShell попытается использовать, если не удается определить, какой набор параметров будет использоваться. Эту проблему можно избежать, сделав уникальный параметр каждого параметра обязательным.

Вспомогательный код ресурса (URI)

Аргумент HelpURI указывает интернет-адрес веб-версии раздела справки, описывающей функцию. Значение аргумента HelpURI должно начинаться с http или https.

Значение аргумента HelpURI используется для значения свойства HelpURI объекта CommandInfo, возвращающего Get-Command функцию.

Однако при установке файлов справки на компьютере и значении первой ссылки в разделе RelatedLinks файла справки является универсальный код ресурса (URI) или значение первой .Link директивы в справке на основе комментариев — URI в файле справки, URI в файле справки используется в качестве значения свойства HelpUri функции.

Командлет Get-Help использует значение свойства HelpURI для поиска веб-версии справки функции, если параметр Get-Help Online указан в команде.

ПоддержкаPaging

Аргумент SupportsPaging добавляет параметры First, Skip и IncludeTotalCount в функцию. Эти параметры позволяют пользователям выбирать выходные данные из очень большого результирующий набор. Этот аргумент предназначен для командлетов и функций, которые возвращают данные из больших хранилищ данных, поддерживающих выбор данных, например базу данных SQL.

Этот аргумент был представлен в Windows PowerShell 3.0.

Сначала: возвращает только первые объекты n.
Пропустить: игнорирует первые объекты n, а затем получает оставшиеся объекты.
IncludeTotalCount: сообщает количество объектов в наборе данных (целое число), за которым следует объекты. Если командлет не может определить общее число, он возвращает значение "Неизвестное общее число".

PowerShell включает NewTotalCount, вспомогательный метод, который получает общее значение счетчика для возврата и включает оценку точности общего значения счетчика.

В следующем примере функции показано, как добавить поддержку параметров разбиения на страницах в расширенную функцию.

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

Аргумент SupportsShouldProcess добавляет параметры Confirm и WhatIf в функцию. Параметр Confirm запрашивает пользователя перед выполнением команды для каждого объекта в конвейере. Параметр WhatIf перечисляет изменения, внесенные командой, вместо выполнения команды.

PositionalBinding

Аргумент PositionalBinding определяет, являются ли параметры функции позициональными по умолчанию. Значение по умолчанию — $True. Аргумент PositionalBinding можно использовать со значением $False отключения позиционной привязки.

Аргумент PositionalBinding представлен в Windows PowerShell 3.0.

Если параметры позициональные, имя параметра является необязательным. PowerShell связывает неназванные значения параметров с параметрами функции в соответствии с порядком или положением неименованных значений параметров в команде функции.

Если параметры не позициональные (они "именованы"), имя параметра (или сокращенное или псевдоним имени) требуется в команде.

При использовании $TruePositionalBinding параметры функции по умолчанию позиционируются. PowerShell назначает номер позиции параметрам в том порядке, в котором они объявлены в функции.

При использовании $FalsePositionalBinding параметры функции по умолчанию не позиционируются. Если аргумент Position атрибута Параметра не объявлен в параметре, имя параметра (или псевдоним или сокращение) должно быть включено, если параметр используется в функции.

Аргумент Position атрибута Параметра имеет приоритет над значением По умолчанию PositionalBinding. Аргумент Position можно использовать для указания значения позиции для параметра. Дополнительные сведения о аргументе Position см. в about_Functions_Advanced_Parameters.

Примечания.

Аргумент SupportsTransactions не поддерживается в расширенных функциях.

Ключевые слова

about_Functions_CmdletBinding_Attribute

Поделиться через