410
¿Está listo para llevar sus habilidades de PowerShell al siguiente nivel y liberar el verdadero poder de las funciones avanzadas? ¡No busque más! En esta publicación de blog, lo guiaremos a través del fascinante mundo del atributo PowerShell CmdletBinding, un atributo innovador que puede potenciar sus capacidades de secuencias de comandos.
Requisitos
- Una computadora con Windows PowerShell 5.1 o PowerShell 7.x y posterior.
- Un editor de secuencias de comandos, como Visual Studio Code o PowerShell ISE.
Funciones simples versus funciones avanzadas
¿Se ha preguntado alguna vez cómo los cmdlets compilados, como los integrados, incluidos Get-Process, Get-Service, etc., tienen un conjunto predeterminado de parámetros? Parámetros como -ErrorAcción, -Acción de advertenciay -Verboso, para nombrar unos pocos. Eso es porque incluyeron el Enlace de cmdlet atributo cuando fueron desarrollados y compilados.
Pero no tiene que escribir cmdlets en Microsoft .NET para acceder a estas funciones avanzadas. Puedes usar el Enlace de cmdlet atributo en sus scripts y funciones.
Entonces, ¿cuál es la diferencia entre funciones simples y avanzadas? Como referencia, tengo dos funciones convenientemente nombradas Función simple y Función avanzada.
Para ilustrar la diferencia, mostraré la sintaxis de ambos:
Get-Command Simple-Function -Syntax Get-Command Advanced-Function -Syntax
El resultado muestra que la función avanzada tiene más parámetros, como -Y si y -Confirmar. También tiene acceso al PowerShell parámetros comunes. Además, al parámetro se le asigna un tipo de dato específico (cadena) y se puede configurar como obligatorio.
Exploraremos cómo puede usar estos parámetros de funciones avanzadas con el atributo PowerShell CmdletBinding.
Convertir una función simple en avanzada agregando el atributo CmdletBinding
Comencemos con la creación de una función simple llamada matar-pokemon. Esta función comienza con este código:
Function Kill-Pokemon {
param (
$Name
)
Write-Output "You just killed $Name."
}
Cuando ejecute esta función, obtendrá el siguiente resultado.
Comprobando su sintaxis, puede confirmar que no es una función avanzada.
Get-Command Kill-Pokemon -Syntax
Entonces, ¿cómo hacemos que esta función sea avanzada? Dos cosas: agregue el atributo CmdletBinding y el bloque de parámetros.
Function Kill-Pokemon {
[CmdletBinding()]
param (
[Parameter()]
[String]
$Name
)
Write-Output "You just killed $Name."
}
La función ahora tiene acceso a los parámetros comunes y el parámetro está fuertemente tipado.
Lo que significa que la función ahora tiene estos parámetros adicionales.
Adición del argumento SupportsShouldProcess
El Los apoyos deben procesar El argumento en el atributo CmdletBinding expone dos nuevos parámetros a la función.
- -Y si — Este parámetro muestra un mensaje sobre lo que hará la función sin ejecutarla.
- -Confirmar — Este parámetro solicita al usuario que confirme la acción pendiente que realizará la función. Si el usuario confirma, la acción continuará. Si el usuario no confirma, la acción se detendrá.
Ahora vamos a actualizar la función.
Function Kill-Pokemon {
[CmdletBinding(
SupportsShouldProcess
)]
param (
[Parameter()]
[String]
$Name
)
if ($PSCmdlet.ShouldProcess($Name)) {
Write-Output "You just killed $Name."
}
}
En este ejemplo, el Los apoyos deben procesar El argumento se inserta en el Enlace de cmdlet atributo. Para aplicar este argumento, debe hacer referencia a él usando esta línea: $PSCmdlet.DeberíaProcesar($Nombre)dónde $Nombre es el parámetro involucrado.
Prueba el -Y si parámetro:
Kill-Pokemon -Name Bulbasaur -WhatIf
Como puede ver, el resultado le dice qué le habría hecho la operación al objetivo.
Ahora, prueba el -Confirmar parámetro.
Kill-Pokemon -Name Bulbasaur -Confirm
Con él, la función solicita confirmación. respondiendo con Y o A confirmará la operación.
Adición del argumento ConfirmImpact
En la sección anterior, agregamos el DeberíaProcesar argumento que expuso la -Confirmar parámetro. Pero la confirmación solo se activa cuando especifica el -Confirmar parámetro durante la ejecución.
Por otro lado, el Confirmar impacto El argumento muestra automáticamente el mensaje de confirmación si el nivel de impacto coincide con el $ConfirmarPreferencia variable (Baja, Media, Alta).
En este ejemplo, el $ConfirmarPreferencia el valor es Alto.
Modifiquemos la función para agregar el Confirmar impacto argumento y ponerlo a nivel Alto.
Function Kill-Pokemon {
[CmdletBinding(
SupportsShouldProcess,
ConfirmImpact="High"
)]
param (
[Parameter()]
[String]
$Name
)
if ($PSCmdlet.ShouldProcess($Name)) {
Write-Output "You just killed $Name."
}
}
Cuando ejecuta la función, el mensaje de confirmación se activa incluso si no utiliza el -Confirmar parámetro.
La confirmación se activó porque configuramos expresamente el nivel de impacto de la función en Alto. Si establecemos el nivel de impacto de la función en algo más bajo, como, Mediola confirmación no debe activarse.
La confirmación no se mostró porque el nivel de impacto de la función es más bajo (Medio) que la $ConfirmarPreferencia valor (Alto).
Uso de atributos de parámetros avanzados
El atributo PowerShell CmdletBinding ha abierto más oportunidades para personalizar y controlar sus funciones. Una es la capacidad de controlar los atributos de los parámetros, como hacerlos obligatorios, incluirlos en un conjunto de parámetros único, definir su posición y permitirles aceptar valores de la canalización.
Aplicación de parámetros obligatorios
Puede hacer que un parámetro sea obligatorio en una función agregando el Obligatorio = $falso argumento. También puede utilizar la versión abreviada Obligatorio.
En este ejemplo, hagamos que la variable $Name sea obligatoria.
param ( [Parameter( Mandatory )] [String] $Name )
Entonces, si ejecuta la función sin especificar el parámetro -Name, se le pedirá que lo ingrese.
Configuración de la posición del parámetro
Puede especificar la posición de un parámetro agregando el Posición = norte argumento. Cuando un parámetro es posicional, especificar el nombre del parámetro antes del valor se vuelve opcional.
param ( [Parameter( Mandatory, Position = 1 )] [String] $Name, [Parameter( Position = 2 )] [String] $Type )
En el ejemplo anterior, el Nombre el parámetro está en posición 1mientras que la Tipo el parámetro está en posición 2. Entonces, en lugar de emitir el siguiente comando:
Kill-Pokemon -Name Pikachu -Type Electric
Puede soltar el nombre del parámetro y simplemente proporcionar el valor del parámetro siguiendo sus posiciones.
Kill-Pokemon Pikachu Electric
Y el resultado será el mismo.
Aceptar valores de la canalización
Otra característica de función avanzada es aceptar un valor de la canalización. Para habilitar esta característica, debe agregar el ValueFromPipeline atributo al parámetro. Por ejemplo, para hacer que el parámetro -Name acepte su valor de la canalización:
[Parameter( Mandatory, Position = 1, ValueFromPipeline )]
¿Qué quiere decir esto? En lugar de ejecutar este comando especificando el parámetro -Name.
Kill-Pokemon -Name Pikachu
Puedes hacer esto en su lugar.
"Pikachu" | Kill-Pokemon
La función producirá el mismo resultado.
Validación de parámetros
Otro uso excelente de las funciones avanzadas con CmdletBinding es la validación de parámetros. Hay muchos atributos de validación de parámetros, pero uno es el ValidarConjunto atributo.
La función de salida actualmente tiene dos parámetros: Nombre y Tipo. Suponga que desea restringir los tipos solo para aceptar un conjunto predefinido de valores; entonces, puedes usar el ValidarConjunto atributo para definirlos.
En este ejemplo, el [ValidateSet()] bloque contiene sólo cuatro valores en el conjunto.
[Parameter( Position = 2 )] [ValidateSet( 'Eletric', 'Flying', 'Poison', 'Ground' )] [String] $Type
El efecto es que ahora solo puede ingresar los cuatro valores.
¿Qué sucede si ingresó a la fuerza un valor no incluido en el ValidarConjunto ¿bloquear? Obtendrá el siguiente error.
Porque «Fantasma” no está en el ValidarConjunto bloque, es un valor no válido y la función falla.
Conclusión
El atributo PowerShell CmdletBinding revoluciona la forma en que los desarrolladores crean funciones avanzadas. Con CmdletBinding, podemos mejorar nuestras funciones con características como admitir parámetros comunes, habilitar la entrada de canalización e implementar el manejo avanzado de errores. Tenemos control sobre parámetros obligatorios, opcionales y dinámicos para construir funciones que cumplan con requisitos específicos.
El atributo de parámetro ValueFromPipeline de CmdletBinding facilita la integración perfecta con la canalización de PowerShell. Las funciones pueden aceptar sin esfuerzo la entrada de la canalización, lo que permite una interacción fluida con otros comandos de PowerShell.
La validación de parámetros mejora aún más la flexibilidad y la fiabilidad de las funciones. Los atributos de validación imponen restricciones de entrada, evitando errores y comportamientos inesperados. En resumen, el atributo CmdletBinding permite a los desarrolladores de PowerShell crear funciones avanzadas versátiles, eficientes y fáciles de usar.
Aprovechar sus capacidades conduce a un código más limpio y fácil de mantener, lo que ahorra tiempo y esfuerzo a largo plazo. Adopte esta poderosa característica y eleve las secuencias de comandos de PowerShell a nuevas alturas.
Lo que aprendió en esta publicación apenas rasca la superficie y pretende brindarle un punto de partida para implementar funciones avanzadas. Hay mucho más por descubrir, y depende de usted descubrirlos y usarlos. ¡Buena suerte!
