Usar el atributo CmdletBinding en PowerShell

1. Atributo CmdletBinding en PowerShell
2. Utilice el atributo CmdletBinding con el parámetro Verbose
3. Utilice el atributo CmdletBinding con el objeto $PSCmdlet y SupportsShouldProcess
4. Use 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 sola función dentro del entorno de PowerShell. Los cmdlets se pueden escribir en cualquier lenguaje .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 funciones que no están disponibles en las funciones simples de PowerShell.

1. Admite parámetros comunes como -WhatIf, ErrorAction, Verbose, etc.
2. Solicitud de confirmaciones
3. Soporte de parámetros obligatorios

Atributo CmdletBinding en PowerShell

La función simple de PowerShell se puede escribir como una función avanzada al heredar las funciones básicas de cmdlet discutidas anteriormente. El atributo CmdletBinding le permite acceder a estas funciones básicas de cmdlet.

A continuación se 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. Entonces, esto se llama una función simple de PowerShell.

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

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

La función Helloworld-To-UpperCase se ha convertido en una función avanzada que hereda todas las funciones básicas de cmdlet. Los parámetros básicos de cmdlet están disponibles para esta función.

Si llama a esta función con - en la ventana de PowerShell, debería enumerar todos los parámetros comunes provenientes del cmdlet.

helloworld-to-uppercase -

Producción:

Los parámetros y características comunes de cmdlet se pueden usar dentro de nuestras funciones avanzadas para ampliar la funcionalidad.

Utilice el atributo CmdletBinding con el parámetro Verbose

El -verbose es uno de los valiosos parámetros comunes que pueden 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 Write-Verbose en la ventana de PowerShell.

HelloWorld-To-UpperCase -Verbose

Producción:

Utilice 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 problemas. Este objeto contiene varios métodos como ShouldContinue, ShouldProcess, ToString, WriteDebug, etc.

Utilice 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 en $True.

El método ShouldContinue tiene varios métodos sobrecargados, y usaremos 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

Producción:

Si el usuario hace clic en Sí, debe 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 kept in lowercase.

Use 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 tomar un parámetro de tipo cadena llamado $palabra. Cuando la función ha llamado, 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 $palabra 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 añadido algunas banderas para controlar el comportamiento del parámetro $palabra. Dado que es obligatorio, debemos proporcionar un valor de cadena cuando se ejecuta la función.

HelloWorld-To-UpperCase -Confirm "stringtouppercase"

PowerShell sigue solicitando eso si no proporcionamos el argumento de texto.

Puede usar varias banderas para controlar los parámetros en sus funciones, como se muestra en la siguiente sintaxis del atributo Parámetro.

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