Cómo usar el atributo CmdletBinding en PowerShell

El cmdlet es un script ligero que realiza una única función dentro del entorno de PowerShell. Los cmdlets pueden ser escritos en cualquier lenguaje de .Net.

Por lo general, un cmdlet se expresa como un par verbo-sustantivo para ejecutar un comando. El comando es una orden al sistema operativo subyacente para realizar un servicio específico por parte del usuario final.

El entorno de PowerShell incluye más de 200 cmdlets básicos, como New-Item, Move-Item, Set-Location y Get-Location. El cmdlet comparte un conjunto común de características no disponibles en funciones simples de PowerShell.

1. Soporta parámetros comunes como -WhatIf, ErrorAction, Verbose, etc.
2. Solicita confirmaciones
3. Soporte para parámetros obligatorios

Atributo CmdletBinding en PowerShell

La función simple de PowerShell puede ser escrita como una función avanzada heredando las características básicas del cmdlet discutidas anteriormente. El atributo CmdletBinding permite acceder a estas características básicas del cmdlet.

Lo siguiente muestra la sintaxis del atributo CmdletBinding con todos los argumentos posibles.

{
    [CmdletBinding(ConfirmImpact = <String>,
        DefaultParameterSetName = <String>,
        HelpURI = <URI>,
        SupportsPaging = <Boolean>,
        SupportsShouldProcess = <Boolean>,
        PositionalBinding = <Boolean>)]

    Param ($myparam)
    Begin {}
    Process {}
    End {}
}

Digamos que tenemos una función simple de PowerShell llamada Helloworld-To-UpperCase.

Function Helloworld-To-UpperCase {
    "helloworld".ToUpper();
}

No hay parámetros adjuntos a esta función. Por lo tanto, se llama a esto una función simple de PowerShell.

Pero podemos usar el atributo CmdletBinding para convertir esta función en una avanzada y acceder a las características y parámetros básicos del cmdlet, como se muestra a continuación.

Function Helloworld-To-UpperCase {
    [CmdletBinding()]Param()
    "helloworld".ToUpper();
}

La función Helloworld-To-UpperCase ha sido convertida a una función avanzada que hereda todas las características básicas del cmdlet. Los parámetros básicos del cmdlet están disponibles para esta función.

Si llamas a esta función con - en la ventana de PowerShell, debería listar todos los parámetros comunes que provienen del cmdlet.

helloworld-to-uppercase -

Salida:

Los parámetros y características comunes del cmdlet pueden ser utilizados dentro de nuestras funciones avanzadas para extender la funcionalidad.

Usa el Atributo CmdletBinding Con el Parámetro Verbose

El -verbose es uno de los valiosos parámetros comunes que puede mostrar un mensaje cuando se ejecuta la función avanzada.

Function Helloworld-To-UpperCase {
    [CmdletBinding()]Param()

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    "helloworld".ToUpper();
}

Cuando llamamos a la función anterior con el parámetro -verbose, imprimirá todas las cadenas de Write-Verbose en la ventana de PowerShell.

HelloWorld-To-UpperCase -Verbose

Salida:

Usa el Atributo CmdletBinding Con el Objeto $PSCmdlet y SupportsShouldProcess

Dado que hemos utilizado el atributo CmdletBinding, nuestra función avanzada puede acceder al objeto $PSCmdlet sin complicaciones. Este objeto contiene varios métodos como ShouldContinue, ShouldProcess, ToString, WriteDebug, etc.

Usa el Atributo CmdletBinding Con el Método ShouldContinue

Este método permite a los usuarios manejar las solicitudes de confirmación. Mientras tanto, es obligatorio establecer el argumento SupportsShouldProcess a $True.

El método ShouldContinue tiene varios métodos sobrecargados, y utilizaremos el que tiene dos parámetros.

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess = $True)]Param()

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        "helloworld".ToUpper();
    }
    Else {
        "helloworld kept in lowercase."
    }
}

Podemos llamar a la función con el parámetro -Confirm, y mostrará un cuadro de confirmación como se muestra a continuación.

HelloWorld-To-UpperCase -Confirm

Salida:

Si el usuario hace clic en Sí, debería implementar el método en el bloque if e imprimir la cadena helloworld en letras mayúsculas.

Si no, debería mostrar el mensaje helloworld mantenido en minúsculas.

Usa el Atributo CmdletBinding Con el Atributo Parameter Para Controlar los Parámetros de La Función

Hagamos que nuestra función avanzada tome un parámetro como una cadena.

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess = $True)]
    Param([string]$word)

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        $word.ToUpper();
    }
    Else {
        "helloworld kept in lowercase."
    }
}

Hemos cambiado la función Helloworld-To-UpperCase para que tome un parámetro de tipo cadena llamado $word. Cuando se llame a la función, necesitamos proporcionar una cadena como argumento.

El texto proporcionado se convertirá a mayúsculas. Si el usuario no ha proporcionado ningún argumento de texto, la función dará una salida vacía.

Podemos controlar esto haciendo que el parámetro $word sea obligatorio y dando la posición del parámetro 0.

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess = $True)]
    Param(
        [Parameter(
            Mandatory = $True, Position = 0
        ) ]
        [string]$word
    )

    #Verbose
    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    #If/Else block for request processing
    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        $word.ToUpper();
    }
    Else {
        "helloworld kept in lowercase."
    }
}

Hemos agregado algunas banderas para controlar el comportamiento del parámetro $word. Dado que es obligatorio, necesitamos proporcionar un valor de cadena cuando se ejecute la función.

HelloWorld-To-UpperCase -Confirm "stringtouppercase"

PowerShell seguirá pidiendo eso si no proporcionamos el argumento de texto.

Puedes usar varias banderas para controlar los parámetros en tus funciones, como se muestra en la siguiente sintaxis del atributo Parameter.

Param
(
    [Parameter(
        Mandatory = <Boolean>,
        Position = <Integer>,
        ParameterSetName = <String>,
        ValueFromPipeline = <Boolean>,
        ValueFromPipelineByPropertyName = <Boolean>,
        ValueFromRemainingArguments = <Boolean>,
        HelpMessage = <String>,
    )]
    [string[]]
    $Parameter1
)