Escribir un flujo de trabajo de script

Artículo
04/03/2016

Se aplica a: Windows Server 2012, Windows Server 2012 R2

En los temas de esta sección se explica cómo escribir un flujo de trabajo en el lenguaje de scripting de Windows PowerShell®, el mismo lenguaje que se usa para escribir funciones y scripts en Windows PowerShell. Puedes ejecutar los flujos de trabajo que escribas en la línea de comandos, incluirlos en scripts e incluirlos en módulos de script.

Para más información sobre cómo escribir flujos de trabajo en XAML, el lenguaje nativo de Windows Workflow Foundation, consulte Escribir un flujo de trabajo de Windows PowerShell en MSDN Library.

Planificar un flujo de trabajo

El flujo de trabajo de Windows PowerShell es una potente solución que puede recopilar datos de cientos de equipos e introducir cambios en ellos cada vez que se ejecuta. Planifica el diseño del flujo de trabajo para que sea sencillo y eficiente. Ten en cuenta que el flujo de trabajo puede suspenderse por sí mismo o ser suspendido por los usuarios, que puede controlarse desde varias PSSessions conectadas a un solo proceso del lado servidor, que puede sobrevivir a reinicios, que puede incluir comandos y funciones ejecutados en paralelo, y que cada comando ejecuta su propia sesión.

Sigue estas instrucciones de planificación:

Si no está familiarizado con los flujos de trabajo, revise los temas de referencia de esta sección, incluidos Diferencias sintácticas entre los flujos de trabajo de script y los scripts.
Comienza enumerando las tareas que realizará el flujo de trabajo. Marca las secciones que pueden ejecutarse simultáneamente o que no necesitan ejecutarse en un orden predeterminado. Dentro de estas secciones, marca las que deban ejecutarse en orden secuencial.
Organiza las tareas por funciones dentro del flujo de trabajo. Para cada tarea, use un cmdlet de Windows PowerShell existente o crea un comando nuevo y agregue un punto de control después de cada paso crítico.
Los flujos de trabajo están diseñados para ejecutarse en varios equipos de destino. No es necesario crear en el flujo de trabajo sesiones remotas o utilizar comandos remotos, como los que usan el cmdlet Invoke-Command.
Como sucede con los scripts que se ejecutan en varios equipos, tenga en cuenta las variaciones entre los equipos que podrían afectar al funcionamiento de los scripts, incluidos los diferentes sistemas operativos, dispositivos, organización del sistema de archivos, variables de entorno y versiones de Windows PowerShell.
Planifica con antelación los temas de ayuda del flujo de trabajo. Mantén un registro de la información que debes comunicarles a los usuarios, incluida la arquitectura preferida para el flujo de trabajo, las características preferidas para la configuración de la sesión y los permisos.

Para escribir el flujo de trabajo, use un editor de scripts como el Entorno de scripting integrado (ISE) de Windows PowerShell, que aplica la sintaxis del flujo de trabajo y resalta los errores de sintaxis. Las diferencias sintácticas entre los scripts y los flujos de trabajo son considerables, por lo que ahorrarás bastante tiempo al codificar y realizar pruebas si usas una herramienta que conozca los flujos de trabajo y los scripts.

Para más información sobre las tareas que son adecuadas para los flujos de trabajo, consulte "Diferencias entre los flujos de trabajo y los scripts de Windows PowerShell" en Introducción al flujo de trabajo de Windows PowerShell.

La palabra clave "workflow"

Comience con la palabra clave workflow, que identifica un comando de flujo de trabajo en Windows PowerShell. La palabra clave workflow es necesaria en un flujo de trabajo de scripts. El nombre del flujo de trabajo debe aparecer tras la palabra clave workflow. El cuerpo del flujo de trabajo se encierra entre llaves.

A continuación se muestra el diagrama de sintaxis de la palabra clave Workflow.

workflow Test-Workflow
{
    ...
}

Para más información sobre las palabras clave en el lenguaje de scripting de Windows PowerShell, consulte about_Language_Keywords.

Nombres y elementos del flujo de trabajo

Un flujo de trabajo es un tipo de comando de Windows PowerShell. Selecciona un nombre con un formato verbo-sustantivo. Use el cmdlet Get-Verb y el tema de ayuda Verbos aprobados para comandos de Windows PowerShell para seleccionar un verbo aprobado para el nombre.Windows PowerShell genera una advertencia cuando se importan comandos que no incluyen verbos aprobados desde un módulo. Usa un sustantivo descriptivo y un prefijo de sustantivo, si es necesario, para evitar conflictos entre los nombres de los comandos cuando el flujo de trabajo se importe a una sesión.

Los nombres de parámetros y los nombres de variables de los flujos de trabajo solo pueden incluir letras, números, guion (-) y subrayado ( _ ). Evita utilizar el guion en los nombres de parámetros, ya que cada vez que uses un nombre de parámetro con guion en el flujo de trabajo y en llamadas al flujo de trabajo debes encerrarlo entre llaves. No use los nombres de los parámetros comunes de flujo de trabajo, las variables en tiempo de ejecución del flujo de trabajo ni otras palabras reservadas, como "workflow" y "parallel".

Para más información sobre los parámetros de tiempo de ejecución del flujo de trabajo, consulte el tema de ayuda Enumeración de PSWorkflowRuntimeVariable en MSDN Library.

Para más información sobre las palabras reservadas, consulte "Palabras reservadas en los flujos de trabajo" en Diferencias sintácticas entre los flujos de trabajo de script y los scripts y about_Reserved_Words.

Cómo agregar parámetros a un flujo de trabajo

Para agregar parámetros a un flujo de trabajo, use la palabra clave Param con el atributo opcional Parameter. Estas técnicas son idénticas a las que usas para agregar parámetros a una función.

Los siguientes bloques de código muestran la sintaxis de la palabra clave Param y el atributo Parameter en un flujo de trabajo de scripts.

workflow Test-Workflow
{
param ([Type]$<ParameterName>)
}

workflow Test-Workflow
{
    Param
    (
        [Parameter(Mandatory=<$True | $False>)]
        [<Type>]
        $<ParameterName>
    )
}

También puede usar el atributo CmdletBinding para especificar los atributos ConfirmImpact, DefaultParameterSetName, HelpUri y SupportsShouldProcess.

En el siguiente bloque de código se muestra la sintaxis de un flujo de trabajo de ejemplo que usa el atributo CmdletBinding.

workflow Test-Workflow
{   
    [CmdletBinding(ConfirmImpact=<String>,
        DefaultParameterSetName=<String>,
        HelpURI=<URI>,
        PositionalBinding=<Boolean>)]

    Param
    (
        [parameter(Mandatory=$true)]
        [String[]]
        $<ParameterName>
    )
}

No hace falta que agregues al flujo de trabajo parámetros comunes de flujo de trabajo. El flujo de trabajo de Windows PowerShell agrega los parámetros comunes y los parámetros comunes de flujo de trabajo a todos los flujos de trabajo, incluidos los flujos de trabajo simples que no tienen el atributo CmdletBinding o el atributo Parameter.

Para obtener más información sobre los parámetros en funciones y flujos de trabajo, consulta los siguientes temas de ayuda.

Cómo agregar actividades a un flujo de trabajo

Una actividad es la unidad de trabajo básica en un flujo de trabajo. Todos los comandos y expresiones que uses en un flujo de trabajo se ejecutan como una actividad. En el flujo de trabajo de Windows PowerShell, una actividad se parece mucho a un cmdlet. Puedes ejecutar una actividad escribiendo el nombre de la actividad seguido de sus parámetros. El flujo de trabajo de Windows PowerShell convierte muchos de los cmdlets incluidos en Windows PowerShell en actividades. Solo hay unos pocos cmdlets excluidos. Para obtener una lista de los cmdlets excluidos, consulte "Cmdlets excluidos" en Uso de actividades en flujos de trabajo de script.

La mayoría de los cmdlets del núcleo de Windows PowerShell se han implementado como actividades. Para usarlos en el flujo de trabajo, solo tienes que escribir el nombre del cmdlet o su alias.

Por ejemplo, el siguiente flujo de trabajo incluye la actividad Get-Process.

workflow Test-Workflow
{
    Get-Process -Name PowerShell
    gps -Name Winword
}

Cuando un cmdlet no tiene una actividad coincidente y no se excluye de manera explícita, el flujo de trabajo de Windows PowerShell ejecuta automáticamente el cmdlet en la actividad inlineScript y devuelve el resultado al flujo de trabajo.

Por ejemplo, el siguiente flujo de trabajo usa el cmdlet Get-WindowsFeature, que ejecuta implícitamente una actividad inlineScript.

workflow Test-Workflow
{
    Get-Process -Name PowerShell
    Get-WindowsFeature -Name PowerShell, PowerShell-v2
}

Incluso puede ejecutar cmdlets excluidos porque no se implementan como actividades, pero debe ejecutarlos en una actividad inlineScript. Por ejemplo, el siguiente flujo de trabajo usa una actividad inlineScript para ejecutar el cmdlet Get-Variable, que se excluye.

workflow Test-Workflow
{
    Get-Process -Name PowerShell
    Get-WindowsFeature -Name PowerShell, PowerShell-v2
    InlineScript { Get-Variable -Name PSHome }
}

También puedes usar expresiones en un flujo de trabajo, incluidas expresiones aritméticas e instrucciones de comparación. El flujo de trabajo de Windows PowerShell ejecuta automáticamente expresiones en una actividad especial diseñada con este fin.

Por ejemplo, el siguiente flujo de trabajo incluye una expresión. Como todas las expresiones, se ejecuta en una actividad.

workflow Test-Workflow
{
    Get-Process -Name PowerShell
    Get-WindowsFeature -Name PowerShell, PowerShell-v2
    InlineScript { Get-Variable PSHome }

    320GB / 3MB
}

Para más información sobre las actividades, consulte Uso de actividades en flujos de trabajo de script.

Cómo usar los parámetros de actividades

Las actividades son comandos que tienen parámetros, igual que los cmdlets. Cuando un cmdlet se convierte en una actividad, la sintaxis y los parámetros siguen siendo iguales. Existen unas pocas excepciones que se enumeran en el tema de ayuda "Actividades en flujos de trabajo de script".

Sin embargo, los parámetros posicionales no son válidos en las actividades, por lo que son necesarios todos los nombres de parámetro. Se permiten las abreviaturas y los alias de parámetro. Por ejemplo, en el flujo de trabajo de ejemplo siguiente, los parámetros Name de los cmdlets Get-Process, Get-WindowsFeature y Get-Variable aparecen en los comandos.

workflow Test-Workflow
{
    Get-Process -Name PowerShell
    Get-WindowsFeature -Name PowerShell, PowerShell-v2
    InlineScript { Get-Variable -Name PSHome }
}

Los parámetros dinámicos tampoco son válidos en las actividades. Para llamar a un parámetro dinámico, incluya el comando en una actividad InlineScript. Por ejemplo, el siguiente flujo de trabajo incluye una actividad inlineScript que usa el parámetro dinámico CodeSigningCert del cmdlet Get-ChildItem. El proveedor de certificados agrega el parámetro CodeSigningCert y solo funciona en la unidad Cert:.

workflow Test-Workflow
{
   InlineScript {Get-ChildItem -Path Cert:\CurrentUser -CodeSigningCert}
}

Para más información sobre la actividad inlineScript, consulte Ejecutar comandos de Windows PowerShell en un flujo de trabajo.

Cómo usar parámetros comunes de actividades

El flujo de trabajo de Windows PowerShell agrega a las actividades una serie de parámetros comunes de actividades. Dichos parámetros permiten configurar opciones cruciales en un entorno con varios equipos.

Algunos de los parámetros comunes del flujo de trabajo son también parámetros comunes de actividades. Esta característica permite crear excepciones específicas de actividades para los valores de parámetro comunes del flujo de trabajo. Por ejemplo, puede usar el parámetro PSComputerName de una actividad para ejecutar una actividad solo en los equipos seleccionados, o el parámetro PSCredential para ejecutar una actividad con credenciales alternativas.

Los parámetros comunes de actividades son válidos en la mayoría de las actividades, pero no en todas. Por ejemplo, los parámetros comunes de actividades no son válidos en las actividades Suspend-Workflow y Checkpoint-Workflow. Asimismo, los parámetros comunes de actividades no están disponibles en cmdlets o expresiones que el flujo de trabajo de Windows PowerShell ejecuta automáticamente en una actividad. Los parámetros comunes de actividades están disponibles en la actividad InlineScript, pero no en comandos en el bloque de script de InlineScript.

Las actividades del siguiente flujo de trabajo usan los parámetros comunes de actividades cuando son válidos.

workflow Test-Workflow
{
    Get-Process -Name PowerShell -PSComputerName Server01, Server 12
    InlineScript { Get-Variable -Name PSHome } -PSRunningTimeoutSec 3600

    #No activity common parameters.
    Get-WindowsFeature -Name PowerShell, PowerShell-v2  

    #No activity common parameters.
    320GB / 3MB
}

Para más información sobre los parámetros comunes de actividades, consulte Uso de actividades en flujos de trabajo de script.

Cómo obtener valores de parámetro comunes

El flujo de trabajo de Windows PowerShell agrega a todos los flujos de trabajo las variables en tiempo de ejecución del flujo de trabajo. Las variables en tiempo de ejecución del flujo de trabajo incluyen los valores de parámetro comunes, los parámetros comunes del flujo de trabajo y otros valores cruciales para los flujos de trabajo.

Los valores de las variables son extremadamente útiles. Tómate todo el tiempo que necesites para revisarlos y utilizarlos en tus flujos de trabajo. Por ejemplo, cuando se ejecuta un flujo de trabajo, el parámetro PSComputerName toma los nombres de los equipos de destino, pero si accede a la variable $PSComputerName en un flujo de trabajo, comprobará que contiene el nombre del equipo en el que se está ejecutando actualmente el flujo de trabajo.

Para obtener información sobre las variables en tiempo de ejecución del flujo de trabajo, consulte la Enumeración de PSWorkflowRuntimeVariable.

Para acceder a los valores de parámetro desde dentro del flujo de trabajo, usa el nombre de la variable. No hace falta que definas la variable.

Por ejemplo, el siguiente flujo de trabajo usa el valor del parámetro común PSConnectionRetryCount haciendo referencia a él como la variable $PSConnectionRetryCount.

workflow Test-Workflow
{
    "Retry count is $PSConnectionRetryCount."
}

En el siguiente ejemplo se muestra que cuando se usa el parámetro PSConnectionRetryCount al ejecutar el flujo de trabajo, el valor de parámetro puede verse en el flujo de trabajo.

PS C:\>Test-Workflow -PSConnectionRetryCount 4
Retry count is 4.

Para cambiar los valores de los parámetros comunes y en tiempo de ejecución en un flujo de trabajo, use la actividad Set-PSWorkflowData.

Por ejemplo, en el siguiente flujo de trabajo se incluye un comando que cambia el valor de PSConnectionRetryCount.

workflow Test-Workflow
{
    "Retry count is $PSConnectionRetryCount."
    Set-PSWorkflowData -PSConnectionRetryCount 5
    "Retry count is $PSConnectionRetryCount."
}

PS C:\>Test-Workflow -PSConnectionRetryCount 4
Retry count is 4.
Retry count is 5.

Para más información sobre las variables en el flujo de trabajo de Windows PowerShell, consulte los siguientes temas de ayuda.

Usar variables en flujos de trabajo de script
Enumeración de PSWorkflowRuntimeVariable
about_Get-PSWorkflowData
about_Set-PSWorkflowData

Cómo obtener variables en tiempo de ejecución y valores de parámetro comunes

Para obtener información sobre las variables en tiempo de ejecución del flujo de trabajo, consulte la Enumeración de PSWorkflowRuntimeVariable.

Para acceder a los valores de parámetro desde dentro del flujo de trabajo, usa el nombre de la variable. No hace falta que definas la variable.

Por ejemplo, el siguiente flujo de trabajo usa el valor del parámetro común PSConnectionRetryCount haciendo referencia a él como la variable $PSConnectionRetryCount.

workflow Test-Workflow
{
    "Retry count is $PSConnectionRetryCount."
}

En el siguiente ejemplo se muestra que cuando se usa el parámetro PSConnectionRetryCount al ejecutar el flujo de trabajo, el valor de parámetro puede verse en el flujo de trabajo.

PS C:\>Test-Workflow -PSConnectionRetryCount 4
Retry count is 4.

Para cambiar los valores de los parámetros comunes y en tiempo de ejecución en un flujo de trabajo, use la actividad Set-PSWorkflowData.

Por ejemplo, en el siguiente flujo de trabajo se incluye un comando que cambia el valor de PSConnectionRetryCount.

workflow Test-Workflow
{
    "Retry count is $PSConnectionRetryCount."
    Set-PSWorkflowData -PSConnectionRetryCount 5
    "Retry count is $PSConnectionRetryCount."
}

PS C:\>Test-Workflow -PSConnectionRetryCount 4
Retry count is 4.
Retry count is 5.

Para más información sobre las variables en el flujo de trabajo de Windows PowerShell, consulte los siguientes temas de ayuda.

Cómo ejecutar un script en un flujo de trabajo

Para ejecutar un script (un archivo .ps1) en un flujo de trabajo, incluya la llamada al script en una actividad InlineScript. Al igual que otros comandos y actividades, el script se ejecuta en todos los equipos de destino del flujo de trabajo y el resultado se devuelve al flujo de trabajo.

Por ejemplo, el siguiente flujo de trabajo incluye una actividad InlineScript que ejecuta un script. El script se almacena en un directorio compartido. El flujo de trabajo usa el parámetro de actividad PSPersist para tomar un punto de control cuando el script se completa.

workflow Test-Workflow
{
   $AssetData =InlineScript {\\Server01\Share01\Get-AssetData.ps1 -All} -PSPersist
   ...
}

Dado que los flujos de trabajo están diseñados para ejecutarse en varios ordenadores, debes usar una ruta de acceso absoluta al archivo de script, en lugar de una ruta de acceso relativa.

Cómo ejecutar comandos en paralelo

Las palabras clave Parallel y ForEach -Parallel optimizan el flujo de trabajo mediante la ejecución de comandos simultáneamente y en un orden indeterminado. La palabra clave Sequence ejecuta los comandos seleccionados secuencialmente dentro un bloque de script de Parallel. Estas palabras clave son válidas únicamente en un flujo de trabajo. Son válidas en flujos de trabajo anidados, pero no en funciones anidadas en un flujo de trabajo. De manera predeterminada, los comandos se ejecutan siguiendo un orden, en el que cada comando se completa antes de que comience el comando siguiente.

Dado que la ejecución en paralelo puede aportar unas mejoras considerables en el rendimiento, sobre todo cuando el flujo de trabajo tiene como destino varios equipos, te conviene usarla siempre que sea posible.

Los siguientes tipos de comandos y actividades son buenos candidatos para la ejecución en paralelo.

Los comandos que no comparten datos, como Get-Process y Get-Service.
Comandos que se ejecutan en una colección de elementos similares. La mayoría de instrucciones ForEach son buenas candidatas para la ejecución de ForEach -Parallel.

Paralelo

Los comandos de un bloque de script Parallel pueden ejecutarse simultáneamente. El orden en el que se ejecutan no está determinado.

En el siguiente diagrama se muestra la sintaxis de un flujo de trabajo con la palabra clave Parallel y un bloque de script.

workflow Test-Workflow
{
    Parallel
    {
         <Activity>
         <Activity>
...
    }
}

Por ejemplo, el siguiente flujo de trabajo incluye un bloque de script paralelo que ejecuta actividades que obtienen procesos y servicios del equipo. Dado que las llamadas a Get-Process y Get-Service son independientes, pueden ejecutarse simultáneamente y en cualquier orden.

workflow Test-Workflow
{
    Parallel
    {
         Get-Process
         Get-Service
    }
}

ForEach -Parallel

El parámetro Parallel de la palabra clave ForEach ejecuta los comandos de un bloque de script ForEach una vez para cada elemento de la colección especificada. Los elementos de la colección se procesan en paralelo. Los comandos del bloque de script se ejecutan simultáneamente.

Al igual que sucede con la instrucción ForEach en Windows PowerShell, la variable que contiene la colección ($<Collection>) debe definirse antes de la instrucción ForEach -Parallel, pero la variable que representa el elemento actual ($<item>) se define en la instrucción ForEach -Parallel.

El siguiente diagrama muestra la sintaxis de comandos.

workflow Test-Workflow
{
    ForEach -Parallel ($<item> in $<collection>)
    {
       <Activity1>
       <Activity2>
 ...
    }
}

Por ejemplo, el siguiente flujo de trabajo contiene una instrucción Foreach -Parallel que procesa los discos que obtiene la actividad Get-Disk. Los comandos del bloque de script se ejecutan secuencialmente, pero se ejecutan en los discos en paralelo.

workflow Test-Workflow
{
    $Disks = Get-Disk
    ForEach -Parallel ($Disk in $Disks)
    {
        $DiskPath = $Disk.Path   
        $Disk | Initialize-Disk
        Set-Disk -Path $DiskPath
    }
}

Secuencia

La palabra clave Sequence ejecuta comandos en secuencia dentro de un bloque de script Parallel. El bloque de script Sequence se ejecuta en paralelo con otros comandos, pero los comandos que están dentro del bloque de script de secuencia se ejecutan secuencialmente y en el orden especificado.

En el siguiente bloque de código se muestra la sintaxis de un bloque de script Sequence. La Actividad 3 puede ejecutarse antes o al mismo tiempo que la Actividad 1 y la Actividad 2, pero la Actividad 4 no se ejecuta hasta que la Actividad 3 se haya completado.

workflow Test-Workflow
{
    parallel
    {
       <Activity1>
       <Activity2>

       sequence 
       {
           <Activity3>
           <Activity4>
           ...
       }
        ...
    }
}