about_Functions_CmdletBindingAttribute

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

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

Длинное описание

Атрибут 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. (Значение по умолчанию аргумента — средний.) Укажите этот аргумент, только если также указан аргумент ПоддерживаетShouldProcess.

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

DefaultParameterSetName

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

HelpUri

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

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

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

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

ПоддержкаPaging

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

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

First: возвращает только первые объекты 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
}

ПоддержкаShouldProcess

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

PositionalBinding

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

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

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

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

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

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

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

Примечания.

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

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

about_Functions_CmdletBinding_Attribute

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-02-05