Cómo usar el atributo CmdletBinding en PowerShell

1. Atributo CmdletBinding en PowerShell
2. Usa el Atributo CmdletBinding Con el Parámetro Verbose
3. Usa el Atributo CmdletBinding Con el Objeto $PSCmdlet y SupportsShouldProcess
4. Usa el Atributo CmdletBinding Con el Atributo Parameter Para Controlar los Parámetros de La Función

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();
}

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
)