Crear funciones en PowerShell es una excelente manera de hacer que sus scripts sean modulares y reutilizables. Pero si desea que esas funciones se adapten a diferentes escenarios, agregar parámetros de función puede llevarlas al siguiente nivel.

En este tutorial, ampliaremos una función de registro básica agregando parámetros para controlar el mensaje de registro, la ruta del archivo y la validación.

Al final, verá cómo los parámetros pueden hacer que sus funciones sean versátiles, resistentes a errores y potentes adiciones a su kit de herramientas de PowerShell.

Definiendo lo básico Write-Log Función

Comenzaremos con una función básica que toma un único parámetro de entrada para el mensaje de registro y lo agrega a un archivo de registro estándar con una marca de tiempo.

En este ejemplo:

• El $LogMessage El parámetro está marcado como obligatorio, por lo que PowerShell lo solicita si no proporciona un valor.
• Cada entrada del registro incluye una marca de tiempo formateada como HH:mm:ss.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path "C:\Scripts\software_installer.log" -Value "$timeGenerated - $LogMessage"
}

Probando el Write-Log Función

Ahora que el Write-Log La función tiene una estructura básica y acepta parámetros, es hora de probar su funcionalidad. Las pruebas ayudan a garantizar que cada aspecto de la función, desde la configuración predeterminada hasta las entradas personalizadas, funcione según lo esperado y maneje los errores con elegancia.

Pruebe el Write-Log función llamándola con un mensaje personalizado:

Write-Log -LogMessage 'Testing a new log message'

Este comando agrega una nueva entrada con una marca de tiempo al archivo de registro (C:\Scripts\software_installer.log).

Algunas cosas a tener en cuenta sobre el Write-Log función:

Con estas mejoras, el Write-Log La función ayuda a agilizar las tareas de registro, haciendo que los scripts sean más limpios y fáciles de mantener.

Puede ver el último mensaje de registro comprobando el contenido del archivo de registro:

Get-Content -Path "C:\Scripts\software_installer.log"

Este comando muestra todas las entradas del registro, incluido su último mensaje con una marca de tiempo.

Pero tal vez llamaste accidentalmente Write-Log sin un LogMessage parámetro:

Write-Log

Lo notarás, porque LogMessage es necesario: PowerShell impedirá que la función se ejecute. Pero, si LogMessage no fueran obligatorios, se escribiría un mensaje vacío, creando una entrada “ups” no deseada.

Verifique el resultado volviendo a verificar el archivo de registro:

Get-Content -Path "C:\Scripts\software_installer.log"

Agregar flexibilidad con una ruta de archivo de registro personalizada

Si bien la función funciona muy bien, hagámosla aún más flexible agregando un $LogFilePath parámetro. Este parámetro le permite especificar una ruta de archivo personalizada y al mismo tiempo proporciona una ruta predeterminada.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [string]$LogFilePath="C:\Scripts\software_installer.log"
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

Note que $LogFilePath tiene una ruta predeterminada de C:\Scripts\software_installer.logpero puede proporcionar cualquier ruta válida.

Para especificar una ruta de archivo diferente, llame Write-Log como esto:

Write-Log -LogMessage 'Custom path log message' -LogFilePath 'C:\Scripts\custom_log.log'

Hacer cumplir la ruta del archivo con ValidateScript

No desea que su función registre archivos que no existen. De hecho, puede asegurarse de que el archivo exista antes de iniciar sesión utilizando el ValidateScript atributo de parámetro. Este atributo le permite ejecutar código con el valor de un parámetro, verificándolo antes de ejecutar la función.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [ValidateScript({ Test-Path -Path $_ })]
        [string]$LogFilePath="C:\Scripts\software_installer.log"
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

Con ValidateScript, Write-Log comprueba que la ruta del archivo que proporcionas existe. Si el archivo no existe, PowerShell se detiene y devuelve un error.

Puede crear un archivo vacío antes de llamarlo para asegurarse de que la función funcione como se esperaba:

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Log entry in a new file' -LogFilePath 'C:\Scripts\softwarex_installer.log'

Pruebas Write-Log Funcionalidad y validaciones

Después de agregar flexibilidades a su función, es natural probar si funciona según lo previsto. Debe garantizar una funcionalidad de registro sólida examinando el ValidateScript atributo y vea cómo mejora su Write-Log función.

veamos como ValidateScript funciona intentando iniciar sesión en un archivo inexistente:

Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

En este caso, el ValidateScript El atributo comprueba si la ruta del archivo de registro especificada existe llamando Test-Path. Si la ruta no existe, la función devuelve un error.

La función falla porque C:\Scripts\softwarex_installer.log no existe. Puedes verificar esto ejecutando Test-Path a mano:

Test-Path 'C:\Scripts\softwarex_installer.log'

Desde Test-Path regresa $falseel archivo efectivamente falta.

Para solucionar este problema, cree un archivo de registro en blanco y vuelva a realizar la prueba.

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

Ahora, la función funciona como se esperaba.

Confirme el resultado viendo el archivo de registro:

Get-Content -Path 'C:\Scripts\softwarex_installer.log'

Usando ValidateScript y otros atributos de validación de parámetros imponen el uso correcto de los parámetros de función, lo que reduce los errores y hace que las funciones de PowerShell sean más confiables.

Conclusión

Agregar parámetros a las funciones de PowerShell mejora enormemente su flexibilidad y utilidad. Con una combinación de valores predeterminados, atributos obligatorios y validación, sus funciones pueden manejar una variedad de entradas manteniendo la confiabilidad.

Con estas técnicas, ahora puede crear funciones escalables y fáciles de usar que se adaptan perfectamente a varios scripts.

Amplíe estas habilidades a medida que crea herramientas PowerShell más avanzadas para optimizar y mejorar su flujo de trabajo. Mira esto Parámetros de PowerShell ¡Tutorial y profundiza en los parámetros de la función!