Compartir por

about_Functions_Advanced

Descripción breve

Presenta funciones avanzadas que son una manera de crear cmdlets mediante scripts.

Descripción larga

Un cmdlet es un único comando que participa en la semántica de canalización de PowerShell. Esto incluye cmdlets binarios, funciones avanzadas de PowerShell y cmdlets CDXML.

Las funciones avanzadas permiten crear cmdlets escritos como una función de PowerShell. Las funciones avanzadas facilitan la creación de cmdlets sin tener que escribir y compilar un cmdlet binario. Los cmdlets binarios son clases de .NET escritas en un lenguaje .NET como C#.

Las funciones avanzadas usan el atributo CmdletBinding para identificarlos como funciones que actúan como cmdlets. El atributo CmdletBinding es similar al atributo Cmdlet que se usa en las clases de cmdlet compiladas para identificar la clase como un cmdlet. Para obtener más información sobre este atributo, vea about_Functions_CmdletBindingAttribute.

Los parámetros de la función son variables declaradas en la instrucción param(). Puede usar el atributo opcional [Parameter()] solo o en combinación con el atributo [Alias()] o cualquiera de los atributos de validación de parámetros. Para obtener más información sobre cómo declarar parámetros, vea about_Functions_Advanced_Parameters.

En el ejemplo siguiente se muestra una función que acepta un nombre y, a continuación, imprime un saludo con el nombre proporcionado. Fíjate también en que esta función define un nombre que incluye una pareja de verbo (Send) y sustantivo (Greeting), como la pareja de verbo y sustantivo de un cmdlet compilado. Sin embargo, no es necesario que las funciones tengan un nombre verbo-sustantivo.

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

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

Esta función realiza el trabajo en el bloque process, que es equivalente al método ProcessingRecord usado en cmdlets compilados. El bloque process y los demás bloques con nombre se describen en about_Functions_Advanced_Methods.

Las funciones avanzadas difieren de los cmdlets compilados de las maneras siguientes:

  • El enlace de parámetros de función avanzada no produce una excepción cuando una matriz de cadenas está enlazada a un parámetro booleano.
  • El atributo ValidateSet y el atributo ValidatePattern no pueden pasar parámetros con nombre.
  • Las funciones avanzadas no se pueden usar en transacciones.

PIPELINESTOPTOKEN

A partir de PowerShell 7.6-preview.4, $PSCmdlet incluye la propiedad PipelineStopToken que permite acceder a un CancellationToken vinculado al origen de eventos de detención de PowerShell. El token se desencadena cuando la canalización de PowerShell recibe una solicitud de detención. Úselo con un método .NET que acepte una sobrecarga de CancellationToken para salir del método cuando se solicite en lugar de esperar hasta que el método devuelva.

En el ejemplo siguiente, la función llama a HttpClient.GetStringAsync, que puede tardar tiempo en responder cuando la red es lenta o hay una gran cantidad de datos que se devuelven.

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 también

  • Last updated on