Сведения о командлете FunctionsBindingAttribute

Статья
05/09/2024

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

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

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

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

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

ConfirmImpact

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

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

DefaultParameterSetName

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

HelpURI

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

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

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

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

SupportsPaging

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

Этот аргумент появился в Windows PowerShell 3.0.

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

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

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

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
}

SupportsShouldProcess

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

PositionalBinding

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

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

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

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

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

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

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