Scripts

Puede crear scripts de PowerShell en PowerShell Universal para ejecutarlos manualmente, según una programación o cuando se produzcan eventos en la plataforma. Se almacenan en disco y se conservan en un repositorio Git local o remoto.

El fichero de configuración scripts.ps1 almacena las propiedades del script.

Añadir un nuevo script

Para añadir un nuevo script, haga clic en el botón New Script en la página Automation / Scripts. Puede proporcionar varias configuraciones para el script.

Cuadro de diálogo New Script

Opciones del script

Name

Este es el nombre del script tal como se muestra en Universal Automation. También es el nombre que se utiliza para conservar el script en disco. El nombre debe ser único dentro de la carpeta actual.

Módulo y comando

Consulte Módulos y comandos a continuación.

Description

Esta descripción del script se muestra en varios lugares de la interfaz de usuario de UA y la devuelven los cmdlets de Universal.

Disable Manual Invocation

Esto impide que un script se ejecute manualmente. Se aplica tanto en la interfaz de usuario como en el servidor web y los cmdlets.

Max Job History

El historial máximo de trabajos define la cantidad de trabajos que se almacenan al ejecutar este script. El valor predeterminado es 100. Los trabajos también se depuran según la configuración de duración de retención de trabajos de todo el servidor de la página Configuración / General.

Error Action

La acción de error cambia cómo reacciona el script cuando se produce un error. De forma predeterminada, los errores de terminación y los que no terminan la ejecución se ignoran y el script siempre se completa correctamente. Puede cambiar esta configuración a stop para que los scripts fallen inmediatamente cuando se produzca un error.

Si desea escribir errores directamente en el panel de errores sin provocar cambios en la forma en que se gestiona el script (por ejemplo, en un controlador de excepciones), utilice Write-PSUError para generar el registro de error y este aparecerá en la pestaña de errores del trabajo.

Environment

Esto le permite definir el entorno de PowerShell necesario para el script. De forma predeterminada, utiliza el entorno de PowerShell predeterminado de todo el servidor. Los entornos de PowerShell se localizan automáticamente la primera vez que se inicia Universal Server o se leen del fichero environments.ps1. También puede añadir un entorno en la página Configuración / Environments.

Timeout

El número de minutos antes de que el script agote el tiempo de espera. El valor predeterminado de 0 significa que el script se ejecutará indefinidamente. Una vez que un script alcanza su tiempo de espera, se cancela.

Descartar la canalización

Cuando está marcada, esta opción desactiva el almacenamiento de la salida de la canalización. Esto reduce considerablemente la sobrecarga de CPU y almacenamiento de los trabajos, pero el script sigue escribiendo en los flujos de información, advertencia y error.

Concurrent Jobs

Define el número máximo de trabajos simultáneos con los que se puede ejecutar el script. El valor predeterminado es 100.

New-PSUScript -Name Script.ps1 -Path Script.Ps1 -ConcurrentJobs 1

Roles de ejecución

Mediante la propiedad Execution Roles, puede establecer qué roles se asignan mientras se ejecuta el script. De forma predeterminada, el script se ejecutará según los roles del llamante. En algunos casos, por ejemplo al utilizar Secrets con Roles, puede que desee proporcionar roles adicionales que el llamante quizá no posea. Cuando los scripts se ejecutan en una programación (Schedule), no tendrán ningún rol, por lo que proporcionarlos mediante Execution Roles permitirá utilizar variables Secret con Roles en el script programado.

Ejecutar un script

Puede ejecutar un script en la interfaz de usuario desde la página Automation / Scripts haciendo clic en Run o haciendo clic en View y luego en Run. En cada caso, aparece el diálogo Run, que le permite seleccionar varias configuraciones para el trabajo.

Cuadro de diálogo Run Script

Ejecutar un script con parámetros

Obtenga más información sobre los parámetros aquí.

PowerShell Universal determina automáticamente los parámetros definidos en sus scripts. Aprovecha el análisis estático de código para determinar el tipo, los valores predeterminados y algunas validaciones que luego se presentan en la interfaz de usuario.

Por ejemplo, puede tener un script con los siguientes parámetros:

param(
    $Test,
    [DateTime]$Time, 
    [int]$Number,
    [PSCredential]$Credential,
    [System.ConsoleColor]$Color
)

El resultado es un conjunto de opciones de entrada basadas en los tipos de parámetros.

Cuadro de diálogo de parámetros del script

Ejecutar un script como otro usuario

El entorno integrado no admite la ejecución con credenciales alternativas.

Puede ejecutar scripts como otro usuario configurando variables secretas. PowerShell Universal utiliza el módulo Microsoft Secret Management para integrarse con los proveedores de secretos. Consulte las variables para obtener más información sobre los secretos.

1. Cree una nueva variable secreta de tipo PSCredential.

Haga clic en Platform \ Variables y luego en Create Secret. Seleccione el tipo de variable PSCredential. Introduzca el nombre de usuario y la contraseña. Asegúrese de que el valor Disable Run As Support esté desmarcado.

Crear variable secreta

1. Ejecute el script y seleccione la credencial

Vuelva a Automation \ Scripts y haga clic en el botón Run Script. Seleccione un entorno distinto del entorno Integrated. De forma predeterminada, será PowerShell 7 o Windows PowerShell 5.1.

Ahora se le pedirá seleccionar la credencial mediante el menú desplegable Run As. Desde ahí, puede seleccionar la credencial en el diálogo de ejecución.

Ejecutar como usuario

Ejecutar un script en otro ordenador

Puede utilizar el menú desplegable Computer para seleccionar otras máquinas en las que ejecutar un script. El valor predeterminado es ejecutarlo en cualquier ordenador disponible.

Ejecutar un script en todos los ordenadores

Puede ejecutar un script en todos los ordenadores seleccionando la opción All Computers en el menú desplegable Computer.

Ejecutar un script desde una app con salida

Si desea ejecutar un script desde una app y mostrar la salida a medida que se ejecuta, utilice el siguiente ejemplo. Aprovecha Invoke-PSUScript y Get-PSUJobOutput.

New-UDButton -OnClick {
    $Job = Invoke-PSUScript -Name Script.ps1
    while($Job.Status -eq 'Running' -or $Job.Status -eq 'Queued')
    {
        [array]$Output = Get-PSUJobOutput -Job $Job
        $Job = Get-PSUJob -Id $Job.Id
        $Session:Code = $Output | ForEach-Object { 
            "$_`r`n"
        } | Join-String 
        Sync-UDElement -Id 'code'
        Start-Sleep -Seconds 1
    }
} -Text 'Run Script'

New-UDDynamic -Id 'code' -Content {
    if ($Session:Code)
    {
        New-UDSyntaxHighlighter -Code $Session:Code -Language batch
    }
}

Equilibrio de carga

PowerShell Universal utiliza un algoritmo de equilibrio de carga basado en el servidor menos ocupado. Si más de un servidor es un destino válido para un trabajo, PowerShell Universal seleccionará el servidor con el menor número de trabajos en ejecución en ese servidor.

Comunicación remota

Puede utilizar la comunicación remota de PowerShell aprovechando Invoke-Command . PowerShell Universal no admite el uso de Enter-PSSession ni Import-PSSession.

Ayuda basada en comentarios

Puede utilizar la ayuda basada en comentarios para definir la descripción, una sinopsis, la ayuda de los parámetros y enlaces para sus scripts. Estos se mostrarán en la interfaz de usuario de PowerShell Universal.

<#
.SYNOPSIS 

This is a script for pinging other computers. 

.DESCRIPTION

This script can ping other computers. 

.PARAMETER HostName

The host name or address to ping. 

.LINK
https://www.ironmansoftware.com
#>
param($HostName)

Test-NetConnection $HostName

Lo anterior produce la siguiente interfaz de usuario. La sinopsis se muestra como descripción corta y una descripción más larga se muestra en la sección de descripción. Los enlaces aparecen debajo de la descripción.

Información adicional del script

Módulos y comandos

Los comandos y cmdlets que se encuentran en los módulos pueden utilizarse como destino de los scripts en lugar de escribir el script directamente.

Supongamos que tenemos un módulo llamado PSUModule que contiene la siguiente función.

function Show-HelloWorld {
    param($Name)
    "Hello, $Name!"
}

Es posible exponer esta función como un script utilizando la siguiente sintaxis en scripts.ps1.

New-PSUScript -Module 'PSUModule' -Command 'Show-HelloWorld'

La función aparece igual que otros scripts en la consola de administración. Los parámetros, el texto de ayuda y otras funciones de PSU funcionan igual que con los scripts.

Estadísticas

Utilizando el historial de trabajos de un script, PowerShell Universal proporcionará estadísticas básicas sobre la ejecución del script. Estas incluyen la tasa de éxito, el tiempo medio de ejecución y desgloses por entorno, usuario y ordenador de ejecución.

Estadísticas del script

Compatibilidad con Start-Job

Aunque es posible iniciar trabajos con Invoke-PSUScript, puede ser deseable iniciar un trabajo mediante el cmdlet Start-Job de PowerShell. El uso de Start-Job no registra el trabajo en PowerShell Universal y la información de ejecución no estará presente en la tabla de trabajos.

Los entornos Integrated, PowerShell 7 y Windows PowerShell 5.1 no son compatibles con Start-Job porque son hosts de PowerShell personalizados. Para utilizar Start-Job, tendrá que configurar un entorno de PowerShell personalizado. Haga clic en Configuración \ Environments. A continuación, haga clic en Create New Environment. Asigne un nombre al entorno, seleccione el tipo de entorno Custom y especifique pwsh.exe como ruta del ejecutable.

Ahora podrá utilizar este entorno para ejecutar el cmdlet Start-Job.

API

• New-PSUScript
• Remove-PSUScript
• Set-PSUScript
• Get-PSUScript