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

about_Functions_Advanced

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

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

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

Командлет — это одна команда, которая участвует в семантике конвейера PowerShell. Сюда входят двоичные командлеты, расширенные функции PowerShell и командлеты CDXML.

Расширенные функции позволяют создавать командлеты, написанные как функция PowerShell. Расширенные функции упрощают создание командлетов без необходимости записывать и компилировать двоичный командлет. Двоичные командлеты — это классы .NET, написанные на языке .NET, например C#.

Расширенные функции используют атрибут CmdletBinding, чтобы определить их как функции, которые действуют как командлеты. Атрибут CmdletBinding аналогичен атрибуту Командлета, который используется в скомпилированных классах командлетов для идентификации класса в качестве командлета. Дополнительные сведения об этом атрибуте см. в about_Functions_CmdletBindingAttribute.

Параметры функции — это переменные, объявленные в инструкции param(). Можно использовать необязательный атрибут [Parameter()] отдельно или в сочетании с атрибутом [Alias()] или любым из атрибутов проверки параметров. Дополнительные сведения о объявлении параметров см. в about_Functions_Advanced_Parameters.

В следующем примере показана функция, которая принимает имя, а затем выводит приветствие с помощью предоставленного имени. Кроме того, обратите внимание, что эта функция определяет имя, включающее пару глаголов (Send) и noun (Приветствие), например пару скомпилированных командлетов. Однако функции не требуются для имени существительного глагола.

function Send-Greeting
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Name
    )

    process
    {
        Write-Host ("Hello " + $Name + "!")
    }
}

Эта функция выполняет работу в блоке process, который эквивалентен методу ProcessingRecord, используемому в скомпилированных командлетах. Блок process и другие именованные блоки описаны в about_Functions_Advanced_Methods.

Расширенные функции отличаются от скомпилированных командлетов следующими способами:

  • Расширенная привязка параметров функции не вызывает исключения, если массив строк привязан к параметру логических.
  • Атрибут ValidateSet и атрибут ValidatePattern не могут передавать именованные параметры.
  • Расширенные функции нельзя использовать в транзакциях.

PIPELINESTOPTOKEN

Начиная с PowerShell 7.6-preview.4, $PSCmdlet включает свойство PipelineStopToken, позволяющее получить доступ к CancellationToken, привязанной к источнику событий остановки PowerShell. Маркер активируется, когда конвейер PowerShell получает запрос на остановку. Используйте его с методом .NET, который принимает перегрузку CancellationToken для выхода из метода, если запрашивается, а не ожидает, пока метод не возвращается.

В следующем примере функция вызывает HttpClient.GetStringAsync, что может занять некоторое время для реагирования, когда сеть медленно или есть много возвращаемых данных.

function Invoke-CancelableWebRequest {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Url
    )

    $client = [System.Net.Http.HttpClient]::new()
    $client.GetStringAsync(
        $Url,
        $PSCmdlet.PipelineStopToken).GetAwaiter().GetResult()
}

Invoke-CancelableWebRequest -Url https://httpbin.org/delay/10
# Press ctrl+c to cancel

См. также

  • Last updated on