Découvrir les principaux concepts de workflow Windows PowerShell pour les runbooks AutomationLearning key Windows PowerShell Workflow concepts for Automation runbooks

Les Runbooks d'Azure Automation sont implémentés en tant que workflows Windows PowerShell.Runbooks in Azure Automation are implemented as Windows PowerShell Workflows. Un workflow Windows PowerShell est similaire à un script Windows PowerShell, mais il présente des différences significatives qui peuvent être déconcertantes pour un nouvel utilisateur.A Windows PowerShell Workflow is similar to a Windows PowerShell script but has some significant differences that can be confusing to a new user. Bien que cet article soit destiné à vous aider à écrire des runbooks à l’aide de workflow PowerShell, nous vous recommandons d’écrire des runbooks à l’aide de PowerShell, sauf si vous avez besoin de points de contrôle.While this article is intended to help you write runbooks using PowerShell workflow, we recommend you write runbooks using PowerShell unless you need checkpoints. Il existe plusieurs différences de syntaxe lors de la création de runbooks de workflow PowerShell et ces différences nécessitent un peu plus de travail pour l’écriture de workflows efficaces.There are several syntax differences when authoring PowerShell Workflow runbooks and these differences require a bit more work to write effective workflows.

Un workflow est une séquence d'étapes liées et programmées qui permet d'effectuer des tâches longues ou nécessitant la coordination de plusieurs phases entre plusieurs appareils ou nœuds gérés.A workflow is a sequence of programmed, connected steps that perform long-running tasks or require the coordination of multiple steps across multiple devices or managed nodes. Les avantages d'un workflow par rapport à un script normal incluent la possibilité d'exécuter simultanément une action sur plusieurs appareils et de récupérer automatiquement après une défaillance.The benefits of a workflow over a normal script include the ability to simultaneously perform an action against multiple devices and the ability to automatically recover from failures. Un workflow Windows PowerShell est un script Windows PowerShell qui utilise Windows Workflow Foundation.A Windows PowerShell Workflow is a Windows PowerShell script that uses Windows Workflow Foundation. Le workflow est écrit avec la syntaxe Windows PowerShell et lancé par Windows PowerShell, mais il est traité par Windows Workflow Foundation.While the workflow is written with Windows PowerShell syntax and launched by Windows PowerShell, it is processed by Windows Workflow Foundation.

Plus d'informations sur les rubriques de cet article, consultez Présentation du workflow Windows PowerShell.For complete details on the topics in this article, see Getting Started with Windows PowerShell Workflow.

Structure de base d'un workflowBasic structure of a workflow

La première étape de la conversion d'un script PowerShell en un workflow PowerShell consiste à y intégrer le mot clé Workflow .The first step to converting a PowerShell script to a PowerShell workflow is enclosing it with the Workflow keyword. Un workflow commence par le mot clé Workflow suivi du corps du script entre accolades.A workflow starts with the Workflow keyword followed by the body of the script enclosed in braces. Le nom du workflow suit le mot clé Workflow, comme illustré dans la syntaxe suivante.The name of the workflow follows the Workflow keyword as shown in the following syntax:

Workflow Test-Workflow
{
    <Commands>
}

Le nom du workflow doit correspondre au nom du Runbook Automation.The name of the workflow must match the name of the Automation runbook. Si le Runbook est importé, le nom de fichier doit correspondre au nom du workflow et se terminer par .ps1.If the runbook is being imported, then the filename must match the workflow name and must end in .ps1.

Pour ajouter des paramètres au workflow, utilisez le mot clé Param , comme pour un script.To add parameters to the workflow, use the Param keyword just as you would to a script.

Modifications du codeCode changes

Le code d'un workflow PowerShell est quasiment identique au code d'un script PowerShell, à l'exception de quelques modifications importantes.PowerShell workflow code looks almost identical to PowerShell script code except for a few significant changes. Les sections suivantes décrivent les modifications que vous devez apporter à un script PowerShell pour l’exécuter dans un workflow.The following sections describe changes that you need to make to a PowerShell script for it to run in a workflow.

ActivitésActivities

Une activité est une tâche spécifique dans un workflow.An activity is a specific task in a workflow. Tout comme un script se compose d'une ou de plusieurs commandes, un workflow se compose d'une ou de plusieurs activités exécutées en séquence.Just as a script is composed of one or more commands, a workflow is composed of one or more activities that are carried out in a sequence. Le workflow Windows PowerShell convertit automatiquement la plupart des applets de commande Windows PowerShell en activités lors de son exécution.Windows PowerShell Workflow automatically converts many of the Windows PowerShell cmdlets to activities when it runs a workflow. Lorsque vous spécifiez une de ces applets de commande dans votre Runbook, l’activité correspondante est exécutée par Windows Workflow Foundation.When you specify one of these cmdlets in your runbook, the corresponding activity is run by Windows Workflow Foundation. Pour ces applets de commande sans activité correspondante, le workflow Windows PowerShell exécute automatiquement l'applet de commande au sein d'une activité InlineScript .For those cmdlets without a corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet within an InlineScript activity. Il existe un ensemble d'applets de commande qui sont exclues et ne peuvent pas être utilisées dans un workflow, à moins que vous ne les incluiez explicitement dans un bloc InlineScript.There is a set of cmdlets that are excluded and cannot be used in a workflow unless you explicitly include them in an InlineScript block. Pour plus d'informations sur ces concepts, consultez Utilisation des activités dans les workflows de script.For further details on these concepts, see Using Activities in Script Workflows.

Les activités de workflow partagent un ensemble de paramètres communs pour configurer leur opération.Workflow activities share a set of common parameters to configure their operation. Pour plus d’informations sur les paramètres communs de flux de travail, consultez about_WorkflowCommonParameters.For details about the workflow common parameters, see about_WorkflowCommonParameters.

Paramètres positionnelsPositional parameters

Vous ne pouvez pas utiliser les paramètres positionnels avec les activités et les applets de commande dans un workflow.You can't use positional parameters with activities and cmdlets in a workflow. Cela signifie que vous devez utiliser des noms de paramètres.All this means is that you must use parameter names.

Par exemple, utilisez le code suivant pour afficher tous les services en cours d'exécution.For example, consider the following code that gets all running services.

Get-Service | Where-Object {$_.Status -eq "Running"}

Si vous essayez d’exécuter ce même code dans un workflow, vous recevez un message de type « le jeu de paramètres est introuvable avec les paramètres nommés spécifiés ».If you try to run this same code in a workflow, you receive a message like "Parameter set cannot be resolved using the specified named parameters." Pour corriger ce problème, entrez le nom du paramètre comme dans l’exemple suivant.To correct this, provide the parameter name as in the following.

Workflow Get-RunningServices
{
    Get-Service | Where-Object -FilterScript {$_.Status -eq "Running"}
}

Objets désérialisésDeserialized objects

Dans les workflows, les objets sont désérialisés.Objects in workflows are deserialized. Cela signifie que leurs propriétés restent disponibles, mais pas leurs méthodes.This means that their properties are still available, but not their methods. Par exemple, utilisez le code PowerShell suivant qui arrête un service à l'aide de la méthode Stop de l'objet Service.For example, consider the following PowerShell code that stops a service using the Stop method of the Service object.

$Service = Get-Service -Name MyService
$Service.Stop()

Si vous essayez d’exécuter ce code dans un workflow, vous obtenez une erreur indiquant que « l’appel de méthode n’est pas pris en charge dans un workflow Windows PowerShell ».If you try to run this in a workflow, you receive an error saying "Method invocation is not supported in a Windows PowerShell Workflow."

Une option consiste à intégrer ces deux lignes de code dans un bloc InlineScript, où $Service représente un objet de service au sein du bloc.One option is to wrap these two lines of code in an InlineScript block in which case $Service would be a service object within the block.

Workflow Stop-Service
{
    InlineScript {
        $Service = Get-Service -Name MyService
        $Service.Stop()
    }
}

Une autre option consiste à utiliser une autre applet de commande qui exécute les mêmes fonctionnalités que la méthode, si celle-ci est disponible.Another option is to use another cmdlet that performs the same functionality as the method, if one is available. Dans notre exemple, l’applet de commande Stop-Service fournit les mêmes fonctionnalités que la méthode Stop, et vous pouvez utiliser les éléments suivants pour un workflow.In our sample, the Stop-Service cmdlet provides the same functionality as the Stop method, and you could use the following for a workflow.

Workflow Stop-MyService
{
    $Service = Get-Service -Name MyService
    Stop-Service -Name $Service.Name
}

InlineScriptInlineScript

L'activité InlineScript est utile lorsque vous devez exécuter une ou plusieurs commandes comme un script PowerShell standard au lieu d'un workflow PowerShell.The InlineScript activity is useful when you need to run one or more commands as traditional PowerShell script instead of PowerShell workflow. Alors que les commandes d'un workflow sont envoyées à Windows Workflow Foundation pour être traitées, les commandes d'un bloc InlineScript sont traitées par Windows PowerShell.While commands in a workflow are sent to Windows Workflow Foundation for processing, commands in an InlineScript block are processed by Windows PowerShell.

InlineScript utilise la syntaxe illustrée ci-dessous.InlineScript uses the following syntax shown below.

InlineScript
{
    <Script Block>
} <Common Parameters>

Vous pouvez renvoyer la sortie d'un bloc InlineScript en l'affectant à une variable.You can return output from an InlineScript by assigning the output to a variable. L'exemple suivant arrête un service puis renvoie le nom du service.The following example stops a service and then outputs the service name.

Workflow Stop-MyService
{
    $Output = InlineScript {
        $Service = Get-Service -Name MyService
        $Service.Stop()
        $Service
    }

    $Output.Name
}

Vous pouvez passer des valeurs dans un bloc InlineScript, mais vous devez utiliser le modificateur de portée $Using .You can pass values into an InlineScript block, but you must use $Using scope modifier. L'exemple suivant est identique à l'exemple précédent, sauf que le nom du service est fourni par une variable.The following example is identical to the previous example except that the service name is provided by a variable.

Workflow Stop-MyService
{
    $ServiceName = "MyService"

    $Output = InlineScript {
        $Service = Get-Service -Name $Using:ServiceName
        $Service.Stop()
        $Service
    }

    $Output.Name
}

Même si les activités InlineScript peuvent être critiques dans certains workflows, elles ne prennent pas en charge les constructions de workflow et doivent être utilisées uniquement lorsque cela est nécessaire pour les raisons suivantes :While InlineScript activities may be critical in certain workflows, they do not support workflow constructs and should only be used when necessary for the following reasons:

  • Vous ne pouvez pas utiliser de points de contrôle à l’intérieur d’un bloc InlineScript.You cannot use checkpoints inside an InlineScript block. Si une défaillance se produit dans le bloc, l'exécution doit reprendre depuis le début du bloc.If a failure occurs within the block, it must be resumed from the beginning of the block.
  • Vous ne pouvez pas effectuer d’exécution en parallèle à l’intérieur d’un bloc InlineScriptBlock.You cannot use parallel execution inside an InlineScriptBlock.
  • InlineScript affecte l'extensibilité du workflow puisque l'activité maintient la session Windows PowerShell pendant toute la durée du bloc InlineScript.InlineScript affects scalability of the workflow since it holds the Windows PowerShell session for the entire length of the InlineScript block.

Pour plus d’informations sur l’utilisation d’InlineScript, consultez Exécution des commandes Windows PowerShell dans un workflow et about_InlineScript.For more information on using InlineScript, see Running Windows PowerShell Commands in a Workflow and about_InlineScript.

Traitement en parallèleParallel processing

L'un des avantages des workflows Windows PowerShell est la possibilité d'exécuter un ensemble de commandes en parallèle, et non séquentiellement comme avec un script classique.One advantage of Windows PowerShell Workflows is the ability to perform a set of commands in parallel instead of sequentially as with a typical script.

Vous pouvez utiliser le mot clé Parallel pour créer un bloc de script avec plusieurs commandes qui s’exécutent simultanément.You can use the Parallel keyword to create a script block with multiple commands that run concurrently. Pour ce faire, utilisez la syntaxe illustrée ci-dessous.This uses the following syntax shown below. Dans ce cas, Activity1 et Activity2 démarrent en même temps.In this case, Activity1 and Activity2 starts at the same time. Activity3 démarre uniquement quand Activity1 et Activity2 sont toutes deux terminées.Activity3 starts only after both Activity1 and Activity2 have completed.

Parallel
{
    <Activity1>
    <Activity2>
}
<Activity3>

Par exemple, considérez les commandes PowerShell suivantes qui copier plusieurs fichiers vers une destination sur le réseau.For example, consider the following PowerShell commands that copy multiple files to a network destination. Ces commandes sont exécutées séquentiellement afin que le fichier termine la copie avant de démarrer la suivante.These commands are run sequentially so that one file must finish copying before the next is started.

Copy-Item -Path C:\LocalPath\File1.txt -Destination \\NetworkPath\File1.txt
Copy-Item -Path C:\LocalPath\File2.txt -Destination \\NetworkPath\File2.txt
Copy-Item -Path C:\LocalPath\File3.txt -Destination \\NetworkPath\File3.txt

Le workflow suivant exécute ces commandes en parallèle afin qu'elles commencent toutes la copie en même temps.The following workflow runs these same commands in parallel so that they all start copying at the same time. Le message confirmant la fin de l’opération apparaît uniquement une fois toutes les copies effectuées.Only after they are all copied is the completion message displayed.

Workflow Copy-Files
{
    Parallel
    {
        Copy-Item -Path "C:\LocalPath\File1.txt" -Destination "\\NetworkPath"
        Copy-Item -Path "C:\LocalPath\File2.txt" -Destination "\\NetworkPath"
        Copy-Item -Path "C:\LocalPath\File3.txt" -Destination "\\NetworkPath"
    }

    Write-Output "Files copied."
}

Vous pouvez utiliser la construction ForEach-Parallel pour traiter simultanément les commandes de chaque élément d'une collection.You can use the ForEach -Parallel construct to process commands for each item in a collection concurrently. Les éléments de la collection sont traités en parallèle, tandis que les commandes du bloc de script sont exécutées séquentiellement.The items in the collection are processed in parallel while the commands in the script block run sequentially. Pour ce faire, utilisez la syntaxe illustrée ci-dessous.This uses the following syntax shown below. Dans ce cas, Activity1 démarre en même temps pour tous les éléments de la collection.In this case, Activity1 starts at the same time for all items in the collection. Pour chaque élément, Activity2 démarre une fois Activity1 terminée.For each item, Activity2 starts after Activity1 is complete. Activity3 démarre uniquement quand Activity1 et Activity2 sont toutes deux terminées pour tous les éléments.Activity3 starts only after both Activity1 and Activity2 have completed for all items. Nous utilisons le paramètre ThrottleLimit pour limiter le parallélisme.We use the ThrottleLimit parameter to limit the parallelism. Une valeur ThrottleLimit trop élevée peut entraîner des problèmes.Too high of a ThrottleLimit can cause problems. La valeur idéale pour le paramètre ThrottleLimit dépend de nombreux facteurs dans votre environnement.The ideal value for the ThrottleLimit parameter depends on many factors in your environment. Vous devez commencer avec une valeur faible, puis essayer différentes valeurs croissantes jusqu’à ce que vous en trouviez une qui fonctionne pour votre situation spécifique.You should try start with a low value and try different increasing values until you find one that works for your specific circumstance.

ForEach -Parallel -ThrottleLimit 10 ($<item> in $<collection>)
{
    <Activity1>
    <Activity2>
}
<Activity3>

L'exemple suivant est similaire à l'exemple précédent concernant la copie de fichiers en parallèle.The following example is similar to the previous example copying files in parallel. Dans ce cas, un message s'affiche pour chaque fichier après la copie.In this case, a message is displayed for each file after it copies. Le message confirmant la fin de l'opération apparaît uniquement une fois toutes les copies effectuées.Only after they are all completely copied is the final completion message displayed.

Workflow Copy-Files
{
    $files = @("C:\LocalPath\File1.txt","C:\LocalPath\File2.txt","C:\LocalPath\File3.txt")

    ForEach -Parallel -ThrottleLimit 10 ($File in $Files)
    {
        Copy-Item -Path $File -Destination \\NetworkPath
        Write-Output "$File copied."
    }

    Write-Output "All files copied."
}

Notes

Nous vous déconseillons d'exécuter des Runbooks enfants en parallèle car les résultats obtenus ne sont pas fiables.We do not recommend running child runbooks in parallel since this has been shown to give unreliable results. Parfois, la sortie du runbook enfant n’apparaît pas, et les paramètres d’un runbook enfant peuvent affecter les autres runbooks enfants parallèles.The output from the child runbook sometimes does not show up, and settings in one child runbook can affect the other parallel child runbooks. Les variables comme $VerbosePreference, $WarningPreference et d’autres, ne peuvent pas être propagées dans les runbooks enfants.Variables such as $VerbosePreference, $WarningPreference, and others may not be propagated to the child runbooks. De plus, si le runbook enfant modifie ces valeurs, celles-ci peuvent ne pas être correctement restaurées après l’appel.And if the child runbook changes these values, they may not be properly restored after invocation.

Points de contrôleCheckpoints

Un point de contrôle est un instantané de l'état actuel du workflow qui inclut la valeur actuelle des variables et toute sortie générée à ce stade.A checkpoint is a snapshot of the current state of the workflow that includes the current value for variables and any output generated to that point. Si un flux de travail se termine par erreur ou est suspendu, il démarrera à la prochaine exécution à partir de son dernier point de contrôle et non depuis le début du worfklow.If a workflow ends in error or is suspended, then the next time it is run it will start from its last checkpoint instead of the start of the workflow. Vous pouvez définir un point de contrôle dans un workflow avec l'activité Checkpoint-Workflow .You can set a checkpoint in a workflow with the Checkpoint-Workflow activity. Azure Automation dispose d’une fonctionnalité appelée équitable, où n’importe quel runbook qui s’exécute pendant 3 heures est déchargée pour permettre l’exécution des autres runbooks.Azure Automation has a feature called fair share, where any runbook that runs for 3 hours is unloaded to allow other runbooks to run. Finalement, le runbook déchargé sera rechargé, et lorsqu’il s’agit, il reprend l’exécution à partir du dernier point de contrôle prise dans le runbook.Eventually, the unloaded runbook will be reloaded, and when it is, it will resume execution from the last checkpoint taken in the runbook. Afin de garantir que le runbook se termine finalement, vous devez ajouter des points de contrôle à des intervalles qui s’exécutent depuis moins de 3 heures.In order to guarantee that the runbook will eventually complete, you must add checkpoints at intervals that run for less than 3 hours. Si lors de chaque exécution un point de contrôle est ajouté, et si le runbook obtient supprimé au bout de 3 heures en raison d’une erreur, le runbook va reprendre indéfiniment.If during each run a new checkpoint is added, and if the runbook gets evicted after 3 hours due to an error, then the runbook will be resumed indefinitely.

Dans l'exemple de code suivant, une exception se produit après qu'Activity2 a provoqué l'arrêt du workflow.In the following sample code, an exception occurs after Activity2 causing the workflow to end. Lorsque le workflow est réexécuté, il commence par exécuter Activity2, juste après le dernier point de contrôle défini.When the workflow is run again, it starts by running Activity2 since this was just after the last checkpoint set.

<Activity1>
Checkpoint-Workflow
<Activity2>
<Exception>
<Activity3>

Vous devez définir les points de contrôle d'un workflow après les activités qui peuvent être sujettes à une exception et qui ne doivent pas être réexécutées à la reprise du workflow.You should set checkpoints in a workflow after activities that may be prone to exception and should not be repeated if the workflow is resumed. Par exemple, votre workflow peut créer une machine virtuelle.For example, your workflow may create a virtual machine. Vous pouvez définir un point de contrôle avant et après les commandes de création de la machine virtuelle.You could set a checkpoint both before and after the commands to create the virtual machine. En cas d'échec de la création, les commandes doivent être répétées si le workflow est redémarré.If the creation fails, then the commands would be repeated if the workflow is started again. Si le workflow échoue après que la création a réussi, la machine virtuelle n’est pas recréée à la reprise du workflow.If the workflow fails after the creation succeeds, then the virtual machine will not be created again when the workflow is resumed.

L'exemple suivant copie plusieurs fichiers vers un emplacement réseau et définit un point de contrôle après chaque fichier.The following example copies multiple files to a network location and sets a checkpoint after each file. Si l’emplacement réseau est perdu, le workflow s’arrête en générant une erreur.If the network location is lost, then the workflow ends in error. Lorsqu’il est relancé, il reprend au dernier point de contrôle, ce qui signifie que seuls les fichiers qui ont déjà été copiés sont ignorés.When it is started again, it will resume at the last checkpoint meaning that only the files that have already been copied are skipped.

Workflow Copy-Files
{
    $files = @("C:\LocalPath\File1.txt","C:\LocalPath\File2.txt","C:\LocalPath\File3.txt")

    ForEach ($File in $Files)
    {
        Copy-Item -Path $File -Destination \\NetworkPath
        Write-Output "$File copied."
        Checkpoint-Workflow
    }

    Write-Output "All files copied."
}

Étant donné que les informations d’identification de nom d’utilisateur ne sont pas conservées après l’appel de l’activité Suspend-Workflow ou après le dernier point de contrôle, vous devez définir les informations d’identification sur « null », puis les récupérer à nouveau à partir du magasin de ressources après l’activité Suspend-Workflow ou après l’appel du point de contrôle.Because username credentials are not persisted after you call the Suspend-Workflow activity or after the last checkpoint, you need to set the credentials to null and then retrieve them again from the asset store after Suspend-Workflow or checkpoint is called. Sinon, le message d’erreur suivant peut s’afficher : Impossible de reprendre la tâche de workflow, soit parce que les données de persistance n’ont pas pu être enregistrées en totalité, soit parce que les données de persistance enregistrées ont été endommagées. Vous devez redémarrer le workflow.Otherwise, you may receive the following error message: The workflow job cannot be resumed, either because persistence data could not be saved completely, or saved persistence data has been corrupted. You must restart the workflow.

Le même code ci-dessous montre comment traiter ce problème dans vos Runbooks de workflow PowerShell.The following same code demonstrates how to handle this in your PowerShell Workflow runbooks.

workflow CreateTestVms
{
    $Cred = Get-AzureAutomationCredential -Name "MyCredential"
    $null = Connect-AzureRmAccount -Credential $Cred

    $VmsToCreate = Get-AzureAutomationVariable -Name "VmsToCreate"

    foreach ($VmName in $VmsToCreate)
        {
        # Do work first to create the VM (code not shown)

        # Now add the VM
        New-AzureRmVm -VM $Vm -Location "ChinaNorth" -ResourceGroupName "ResourceGroup01"

        # Checkpoint so that VM creation is not repeated if workflow suspends
        $Cred = $null
        Checkpoint-Workflow
        $Cred = Get-AzureAutomationCredential -Name "MyCredential"
        $null = Connect-AzureRmAccount -EnvironmentName AzureChinaCloud -Credential $Cred
        }
}

Important

Add-AzureRmAccount est désormais un alias de Connect-AzureRMAccount.Add-AzureRmAccount is now an alias for Connect-AzureRMAccount. Quand vous effectuez une recherche dans vos éléments de bibliothèque, si vous ne voyez pas Connect-AzureRMAccount, vous pouvez utiliser Add-AzureRmAccount ou mettre à jour vos modules dans votre compte Automation.When searching your library items, if you do not see Connect-AzureRMAccount, you can use Add-AzureRmAccount, or you can update your modules in your Automation Account.

Cette procédure n’est pas nécessaire si vous vous authentifiez à l’aide d’un compte d’identification configuré avec un service principal.This is not required if you are authenticating using a Run As account configured with a service principal.

Pour plus d'informations sur les points de contrôle, consultez Ajout de points de contrôle à un workflow de script.For more information about checkpoints, see Adding Checkpoints to a Script Workflow.

Étapes suivantesNext steps