Gravando um fluxo de trabalho de script

 

Aplica-se a: Windows Server 2012, Windows Server 2012 R2

Os tópicos desta seção explicam como gravar um fluxo de trabalho na linguagem de scripts do Windows PowerShell®, a mesma linguagem que você usa para gravar funções e scripts no Usando o Windows PowerShell. Você pode executar os fluxos de trabalho gravados na linha de comando, inclui-los nos scripts e inclui-los nos módulos de script.

Para obter informações sobre a gravação de fluxos de trabalho em XAML, a linguagem nativa do Windows Workflow Foundation, consulte Writing a Windows PowerShell Workflow (Gravando um fluxo de trabalho do Windows PowerShell) na Biblioteca MSDN.

Planejando um fluxo de trabalho

O Fluxo de Trabalho do Usando o Windows PowerShell é uma solução avançada que pode fazer alterações e reunir dados de alterações em centenas de computadores sempre que é executado. Planeje o design do fluxo de trabalho para obter simplicidade e eficiência. Lembre-se de que o fluxo de trabalho pode suspender-se ou ser suspenso pelos usuários, pode ser controlado por inúmeras PSSessions que se conectam a um processo individual do lado do servidor e pode sobreviver a reinicializações, inclusive funções e comandos executados em paralelo. Além disso, cada comando é executado em sua própria sessão.

Use as seguintes diretrizes de planejamento

  • Se os fluxos de trabalho forem novidade para você, reveja os tópicos de referência nesta seção, incluindo Diferenças sintáticas entre fluxos de trabalho de script e scripts.

  • Comece enumerando as tarefas que o fluxo de trabalho realizará. Marque as seções que podem ser executadas simultaneamente ou que não precisam ser executadas em uma ordem predeterminada. Nessas seções, marque todas as que devem ser executadas em ordem sequencial.

  • Organize as tarefas um funções no fluxo de trabalho. Para cada tarefa, use um cmdlet existente do Usando o Windows PowerShell ou crie um novo comando e adicione um ponto de verificação depois de cada etapa crítica.

  • Os fluxos de trabalho são projetados para serem executados em vários computadores de destino. Você não precisa criar sessões remotas nem usar comandos remotos no fluxo de trabalho, como os que usam o cmdlet Invoke-Command.

  • Como em qualquer script executado em vários computadores, considere variações entre os computadores que podem afetar a operação do script, inclusive a variação de sistemas operacionais, dispositivos, organização de sistemas de arquivos, variáveis dos ambientes e versões do Usando o Windows PowerShell.

  • Planeje com antecedência os tópicos de ajuda do fluxo de trabalho. Mantenha um registro das informações de que você precisa para se comunicar com os usuários, inclusive uma arquitetura preferencial do fluxo de trabalho, características da configuração preferencial da sessão e permissões.

Para gravar o fluxo de trabalho, use um editor de scripts, como o ISE (Ambiente de Script Integrado) do Windows PowerShell, que impõe a sintaxe do fluxo de trabalho e destaca os erros de sintaxe. As diferenças sintáticas entre os scripts e fluxos de trabalho são significativas. Portanto, uma ferramenta que lide com fluxos de trabalhos e também com scripts poupará um tempo significativo de codificação e teste.

Para obter mais informações sobre as tarefas adequadas aos fluxos de trabalhos, consulte "Como os fluxos de trabalho e os scripts do Usando o Windows PowerShell diferem" em Introduzindo o Fluxo de Trabalho do Windows PowerShell.

A palavra-chave Workflow

Comece com a palavra-chave workflow, que identifica um comando de fluxo de trabalho para o Usando o Windows PowerShell. A palavra-chave workflow é exigida em um fluxo de trabalho de script. O nome do fluxo de trabalho vem depois da palavra-chave workflow. O corpo do fluxo de trabalho fica entre chaves.

A seguir está o diagrama de sintaxe da palavra-chave Workflow.

workflow Test-Workflow
{
    ...
}

Para obter mais informações sobre palavras-chave na linguagem de scripts do Usando o Windows PowerShell consulte about_Language_Keywords.

Denominando fluxos de trabalho e seus elementos

Um fluxo de trabalho é um tipo de comando do Usando o Windows PowerShell. Selecione um nome usando o formato verbo-substantivo. Use o cmdlet Get-Verb e o tópico de ajuda Approved Verbs for Windows PowerShell Commands (Verbos aprovados para comandos do Windows PowerShell) para selecionar um verbo aprovado para o nome. O Usando o Windows PowerShell gera um aviso quando comandos que não contêm verbos aprovados são importados de um módulo. Use um substantivo descritivo e um prefixo ao substantivo, se necessário, para impedir um conflito de nome quando o fluxo de trabalho for importado para uma sessão.

Os nomes de parâmetros e de variáveis nos fluxos de trabalho podem conter apenas letras, números e os caracteres hífen (-) e sublinhado (_). Evite usar hifens nos nomes de parâmetros, pois cada uso de um nome de parâmetro com hífen no fluxo de trabalho e nas chamadas ao fluxo de trabalho deve estar entre chaves. Não utilize nomes dos parâmetros comuns de fluxo de trabalho, variáveis de tempo de execução de fluxo de trabalho nem outras palavras reservadas, como "fluxo de trabalho" e "paralelo".

Para obter mais informações sobre os parâmetros do tempo de execução do fluxo de trabalho, consulte o tópico de ajuda PSWorkflowRuntimeVariable Enumeration (Enumeração PSWorkflowRuntimeVariable) na biblioteca MSDN.

Para obter mais informações sobre as palavras reservadas, consulte “Palavras reservadas em fluxos de trabalho” em Diferenças sintáticas entre fluxos de trabalho de script e scripts e about_Reserved_Words.

Como adicionar parâmetros a um fluxo de trabalho

Para adicionar parâmetros a um fluxo de trabalho, use a palavra-chave Param com o atributo opcional Parameter. As técnicas são as mesmas usadas para adicionar parâmetros a uma função.

Os blocos de código a seguir mostram a sintaxe da palavra-chave Param e do atributo Parameter em um fluxo de trabalho de script.

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

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

Você também pode usar o atributo CmdletBinding para especificar os atributos ConfirmImpact, DefaultParameterSetName, HelpUri e SupportsShouldProcess.

O bloco de código a seguir mostra a sintaxe de um fluxo de trabalho de exemplo que usa o atributo CmdletBinding.

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

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

Não é preciso adicionar parâmetros comuns ao fluxo de trabalho. O Fluxo de trabalho do Usando o Windows PowerShell adiciona parâmetros comuns e parâmetros comuns de fluxo de trabalho a todos os fluxos de trabalho, inclusive os simples que não têm o atributo CmdletBinding ou Parameter.

Para obter mais informações sobre parâmetros em funções e fluxos de trabalho, consulte os tópicos de ajuda a seguir.

Como adicionar atividades a um fluxo de trabalho

Uma atividade é a unidade básica de trabalho em um fluxo de trabalho. Todos os comandos e expressões que você usa em um fluxo de trabalho são executados como uma atividade. No Fluxo de Trabalho do Usando o Windows PowerShell, a atividade é muito semelhante ao cmdlet. Para executar a atividade, você deve digitar o nome da atividade seguido por seus parâmetros. O Fluxo de Trabalho do Usando o Windows PowerShell converte muitos dos cmdlets incluídos no Usando o Windows PowerShell em atividades. Existe apenas um pequeno conjunto de cmdlets excluídos. Para obter uma lista de cmdlets excluídos, consulte "Excluded Cmdlets” (Cmdlets excluídos) em Usando atividades em fluxos de trabalho de script.

A maioria dos cmdlets principais do Usando o Windows PowerShell foi implementada como atividades. Para usá-los no fluxo de trabalho, basta digitar o nome ou alias do cmdlet.

Por exemplo, o fluxo de trabalho a seguir inclui a atividade Get-Process.

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

Quando um cmdlet não tem uma atividade correspondente e não foi excluído explicitamente, o Fluxo de Trabalho do Usando o Windows PowerShell o executa automaticamente na atividade inlineScript e retorna o resultado ao fluxo de trabalho.

Por exemplo, o seguinte fluxo de trabalho usa o cmdlet Get-WindowsFeature, que é executado implicitamente em uma atividade inlineScript.

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

Você pode até mesmo executar cmdlets que foram excluídos porque eles não estão implementados como atividades, mas deve executá-los em uma atividade inlineScript. Por exemplo, o fluxo de trabalho a seguir usa uma atividade inlineScript para executar o cmdlet Get-Variable, que foi excluído.

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

Você também pode usar expressões em um fluxo de trabalho, inclusive expressões aritméticas e instruções de comparação. O Fluxo de Trabalho do Usando o Windows PowerShell executa automaticamente expressões em uma atividade especial projetada para a finalidade.

Por exemplo, o fluxo de trabalho a seguir contém uma expressão. Como todas as expressões, ela é executada em uma atividade.

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

    320GB / 3MB
}

Para obter mais informações sobre as atividades, consulte Usando atividades em fluxos de trabalho de script.

Como usar os parâmetros de atividades

Atividades são comandos que contêm parâmetros, exatamente como os cmdlets. Quando um cmdlet é convertido em uma atividade, a sintaxe e os parâmetros permanecem os mesmos. Existem algumas exceções, que são listadas no tópico de ajuda "Usando atividades em fluxos de trabalho de Script".

No entanto, os parâmetro de posição não são válidos nas atividades. Portanto, todos os nomes de parâmetros são necessários. Aliases e abreviações de parâmetros são permitidas. Por exemplo, no fluxo de trabalho de exemplo a seguir, os parâmetros Name dos cmdlets Get-Process, Get-WindowsFeature e Get-Variable aparecem nos comandos.

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

Parâmetros dinâmicos também não são válidos nas atividades. Para chamar um parâmetro dinâmico, insira o comando em uma atividade InlineScript. Por exemplo, o fluxo de trabalho a seguir contém uma atividade inlineScript que usa o parâmetro dinâmico CodeSigningCert do cmdlet Get-ChildItem. O parâmetro CodeSigningCert é adicionado pelo Provedor de certificados e funciona apenas na unidade Cert:.

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

Para obter mais informações sobre a atividade inlineScript, consulte Executando comandos do Windows PowerShell em um fluxo de trabalho.

Como usar os parâmetros comuns de atividade

O Fluxo de Trabalho do Usando o Windows PowerShell adiciona às atividades um conjunto de parâmetros comuns de atividade. Esses parâmetros permitem que você defina opções críticas a um ambiente com vários computadores.

Alguns dos parâmetros comuns de fluxo de trabalho também são parâmetros comuns de atividade. Esse recurso permite criar exceções específicas da atividade para os valores de parâmetros comuns de fluxo de trabalho. Por exemplo, você pode usar o parâmetro PSComputerName de uma atividade para executar uma atividade apenas em computadores selecionados ou o parâmetro PSCredential para executar uma atividade com credenciais alternativas.

Os parâmetros comuns de atividade são válidos na maioria das atividades, mas não em todas elas. Por exemplo, os parâmetros comuns de atividade não são válidos nas atividades Suspend-Workflow e Checkpoint-Workflow. Além disso, eles não estão disponíveis em cmdlets ou expressões que o Fluxo de Trabalho do Usando o Windows PowerShell executa automaticamente em uma atividade. Os parâmetros comuns de atividade estão disponíveis na atividade InlineScript, mas não em comandos no bloco de script InlineScript.

As atividades do fluxo de trabalho a seguir usam os parâmetros comuns de atividade em que eles são 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 obter mais informações sobre os parâmetros comuns de atividade, consulte Usando atividades em fluxos de trabalho de script.

Como obter valores de parâmetros comuns

O Fluxo de Trabalho do Usando o Windows PowerShell adiciona variáveis de tempo de execução de fluxo de trabalho a todos os fluxos de trabalho. As variáveis de tempo de execução de fluxo de trabalho contêm os valores dos parâmetros comuns, parâmetros comuns de fluxo de trabalho e outros valores que são críticos aos fluxos de trabalho.

Os valores de variáveis são extremamente úteis. Reserve um tempo para examiná-los e use-os em seus fluxos de trabalho. Por exemplo, quando você executa um fluxo de trabalho, o parâmetro PSComputerName obtém o nome dos computadores de destino, mas quando você acessa a variável $PSComputerName em um fluxo de trabalho, ela contém o nome do computador no qual o fluxo de trabalho está em execução no momento.

Para obter mais informações sobre as variáveis de tempo de execução de fluxo de trabalho, consulte PSWorkflowRuntimeVariable Enumeration (Enumeração PSWorkflowRuntimeVariable).

Para acessar os valores de parâmetro a partir do fluxo de trabalho, use o nome da variável. Não é preciso definir a variável.

Por exemplo, o fluxo de trabalho a seguir usa o valor do parâmetro comum PSConnectionRetryCount referindo-se a ele como a variável $PSConnectionRetryCount.

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

O exemplo a seguir mostra que quando você usa o parâmetro PSConnectionRetryCount na execução do fluxo de trabalho, o valor do parâmetro é visível no fluxo de trabalho.

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

Para alterar os valores dos parâmetros comuns e de tempo de execução de um fluxo de trabalho, use a atividade Set-PSWorkflowData.

Por exemplo, o fluxo de trabalho a seguir contém um comando que altera o valor 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 obter mais informações sobre variáveis no Fluxo de Trabalho do Usando o Windows PowerShell, consulte os tópicos de ajuda a seguir.

Como obter valores de parâmetros comuns e variáveis

O Fluxo de Trabalho do Usando o Windows PowerShell adiciona variáveis de tempo de execução de fluxo de trabalho a todos os fluxos de trabalho. As variáveis de tempo de execução de fluxo de trabalho contêm os valores dos parâmetros comuns, parâmetros comuns de fluxo de trabalho e outros valores que são críticos aos fluxos de trabalho.

Os valores de variáveis são extremamente úteis. Reserve um tempo para examiná-los e use-os em seus fluxos de trabalho. Por exemplo, quando você executa um fluxo de trabalho, o parâmetro PSComputerName obtém o nome dos computadores de destino, mas quando você acessa a variável $PSComputerName em um fluxo de trabalho, ela contém o nome do computador no qual o fluxo de trabalho está em execução no momento.

Para obter mais informações sobre as variáveis de tempo de execução de fluxo de trabalho, consulte PSWorkflowRuntimeVariable Enumeration (Enumeração PSWorkflowRuntimeVariable).

Para acessar os valores de parâmetro a partir do fluxo de trabalho, use o nome da variável. Não é preciso definir a variável.

Por exemplo, o fluxo de trabalho a seguir usa o valor do parâmetro comum PSConnectionRetryCount referindo-se a ele como a variável $PSConnectionRetryCount.

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

O exemplo a seguir mostra que quando você usa o parâmetro PSConnectionRetryCount na execução do fluxo de trabalho, o valor do parâmetro é visível no fluxo de trabalho.

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

Para alterar os valores dos parâmetros comuns e de tempo de execução de um fluxo de trabalho, use a atividade Set-PSWorkflowData.

Por exemplo, o fluxo de trabalho a seguir contém um comando que altera o valor 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 obter mais informações sobre variáveis no Fluxo de Trabalho do Usando o Windows PowerShell, consulte os tópicos de ajuda a seguir.

Como executar um script em um fluxo de trabalho

Para executar um script (um arquivo .ps1) em um fluxo de trabalho, insira a chamada ao script em uma atividade InlineScript. Como outros comandos e atividades, o script é executado em todos os computadores de destino do fluxo de trabalho e o resultado é retornado ao fluxo de trabalho.

Por exemplo, o fluxo de trabalho a seguir contém uma atividade InlineScript que executa um script. O script é armazenado em um diretório compartilhado. O fluxo de trabalho usa o parâmetro de atividade PSPersist para obter um ponto de verificação quando o script é concluído.

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

Como os fluxos de trabalho são projetados para a execução em vários computadores, use um caminho absoluto para o arquivo de script, em vez de um caminho relativo.

Como executar comandos em paralelo

As palavras-chave Parallel e ForEach -Parallel otimizam seu fluxo de trabalho executando comandos simultaneamente e em uma determinada ordem. A palavra-chave Sequence executa comandos selecionados sequencialmente em um bloco de script Parallel. Essas palavras-chave são válidas apenas em um fluxo de trabalho. Elas são válidas em fluxos de trabalho aninhados, mas não em funções aninhadas de um fluxo de trabalho. Por padrão, os comandos são executados na sequência em que cada comando é concluído, antes do início do comando seguinte.

Como a execução paralela pode oferecer melhorias significativas de desempenho, especialmente quando o fluxo de trabalho se destina a inúmeros computadores, use-a sempre que possível.

Os seguintes tipos de comandos e atividades são bons candidatos à execução paralela.

  • Comandos que não compartilham dados, tais como os comandos Get-Process e Get-Service.

  • Comandos executados em uma coleção de itens semelhantes. A maioria das instruções ForEach são boas candidatas para execução de ForEach -Parallel.

Parallel

Os comandos em um bloco de script Parallel podem ser executados simultaneamente. A ordem de execução não é determinada.

O diagrama a seguir mostra a sintaxe de um fluxo de trabalho com a palavra-chave e o bloco de script Parallel.

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

Por exemplo, o fluxo de trabalho a seguir contém um bloco de script Parallel que executa atividades que obtêm processos e serviços do computador. Como as chamadas para Get-Process e Get-Service são independentes, elas podem ocorrer simultaneamente e em qualquer ordem.

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

ForEach -Parallel

O parâmetro Parallel da palavra-chave ForEach executa os comandos em um bloco de script ForEach uma vez para cada item na coleção especificada. Os itens da coleção são processados em paralelo. Os comandos do bloco de script são executados sequencialmente.

Como a instrução ForEach no Usando o Windows PowerShell, a variável que contém a coleção ($<Collection>) deve ser definida antes da instrução ForEach -Parallel, mas a variável que representa o item atual ($<item>) é definida na instrução ForEach -Parallel.

O diagrama a seguir mostra a sintaxe do comando.

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

Por exemplo, o fluxo de trabalho a seguir contém uma instrução Foreach -Parallel que processa os discos obtidos pela atividade Get-Disk. Os comandos do bloco de script são executados sequencialmente, mas são executados em paralelo nos discos.

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

Sequence

A palavra-chave Sequence executa comandos em sequência em um bloco de script Parallel. O bloco de script Sequence é executado em paralelo com outros comandos, mas os comandos do bloco de script Sequence são executados sequencialmente e na ordem especificada.

O bloco de código a seguir mostra a sintaxe de um bloco de script Sequence. A Atividade 3 poderá ser executada antes ou ao mesmo tempo que a Atividade 1 e a Atividade 2, mas a Atividade 4 só será executada depois que a Atividade 3 for concluída.

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

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