Compartilhar via

about_Functions_Advanced

Descrição curta

Apresenta funções avançadas que são uma maneira de criar cmdlets usando scripts.

Descrição longa

Um cmdlet é um único comando que participa da semântica de pipeline do PowerShell. Isso inclui cmdlets binários, funções avançadas do PowerShell e cmdlets CDXML.

As funções avançadas permitem criar cmdlets que são gravados como uma função do PowerShell. As funções avançadas facilitam a criação de cmdlets sem a necessidade de gravar e compilar um cmdlet binário. Cmdlets binários são classes .NET que são escritas em uma linguagem .NET, como C#.

As funções avançadas usam o atributo CmdletBinding para identificá-las como funções que atuam como cmdlets. O atributo CmdletBinding é semelhante ao atributo Cmdlet usado em classes de cmdlet compiladas para identificar a classe como um cmdlet. Para obter mais informações sobre esse atributo, consulte about_Functions_CmdletBindingAttribute.

Os parâmetros da função são variáveis declaradas na instrução param(). Você pode usar o atributo [Parameter()] opcional sozinho ou em combinação com o atributo [Alias()] ou qualquer um dos atributos de validação de parâmetro. Para obter mais informações sobre como declarar parâmetros, consulte about_Functions_Advanced_Parameters.

O exemplo a seguir mostra uma função que aceita um nome e, em seguida, imprime uma saudação usando o nome fornecido. Observe também que essa função define um nome que inclui um par verbo (Enviar) e substantivo (Saudação) como o par verbo-substantivo de um cmdlet compilado. No entanto, as funções não são necessárias para ter um nome de substantivo de verbo.

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

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

Essa função executa o trabalho no bloco process, que é equivalente ao método ProcessingRecord usado em cmdlets compilados. O bloco process e os outros blocos nomeados são descritos em about_Functions_Advanced_Methods.

As funções avançadas diferem dos cmdlets compilados das seguintes maneiras:

  • A associação de parâmetro de função avançada não gera uma exceção quando uma matriz de cadeias de caracteres é associada a um parâmetro booliano.
  • O atributo ValidateSet e o atributo ValidatePattern não podem passar parâmetros nomeados.
  • Funções avançadas não podem ser usadas em transações.

PIPELINESTOPTOKEN

A partir do PowerShell 7.6-preview.4, $PSCmdlet inclui a propriedade PipelineStopToken que permite acessar um CancellationToken vinculado à origem do evento de parada do PowerShell. O token é disparado quando o pipeline do PowerShell recebe uma solicitação para parar. Use-o com um método .NET que aceita uma sobrecarga CancellationToken para sair do método quando solicitado, em vez de aguardar até que o método retorne.

No exemplo a seguir, a função está chamando HttpClient.GetStringAsync, o que pode levar tempo para responder quando a rede está lenta ou há muitos dados sendo retornados.

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

Consulte também

  • Last updated on