Inlärnings nyckel koncept för Windows PowerShell-arbetsflöden för Automation-runbooksLearning key Windows PowerShell Workflow concepts for Automation runbooks

Runbooks i Azure Automation implementeras som Windows PowerShell-arbetsflöden.Runbooks in Azure Automation are implemented as Windows PowerShell Workflows. Ett Windows PowerShell-arbetsflöde liknar ett Windows PowerShell-skript men har några viktiga skillnader som kan vara förvirrande för en ny användare.A Windows PowerShell Workflow is similar to a Windows PowerShell script but has some significant differences that can be confusing to a new user. Även om den här artikeln är avsedd att hjälpa dig att skriva Runbooks med hjälp av PowerShell-arbetsflöde rekommenderar vi att du skriver Runbooks med hjälp av PowerShell om du inte behöver kontroll punkter.While this article is intended to help you write runbooks using PowerShell workflow, we recommend you write runbooks using PowerShell unless you need checkpoints. Det finns flera skillnader i syntaxen när du redigerar PowerShell Workflow-Runbooks och dessa skillnader kräver lite mer arbete för att skriva effektiva arbets flöden.There are several syntax differences when authoring PowerShell Workflow runbooks and these differences require a bit more work to write effective workflows.

Ett arbetsflöde är en sekvens med programmerade, nätverksanslutna steg som utför tidskrävande uppgifter eller kräver samordning av flera steg i flera enheter eller hanterade noder.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. Fördelarna med ett arbetsflöde jämfört med ett vanligt skript är möjligheten att samtidigt kunna utföra en åtgärd på flera enheter och möjligheten att automatisk återställning vid fel.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. Ett Windows PowerShell-arbetsflöde är ett Windows PowerShell-skript som använder Windows Workflow Foundation.A Windows PowerShell Workflow is a Windows PowerShell script that uses Windows Workflow Foundation. När arbetsflödet skrivs med Windows PowerShell-syntax och startas också av Windows PowerShell, bearbetas det av Windows Workflow Foundation.While the workflow is written with Windows PowerShell syntax and launched by Windows PowerShell, it is processed by Windows Workflow Foundation.

Fullständig information om ämnena i den här artikeln finns komma igång med Windows PowerShell-arbetsflöde.For complete details on the topics in this article, see Getting Started with Windows PowerShell Workflow.

Grundläggande struktur för ett arbets flödeBasic structure of a workflow

Det första steget för att konvertera ett PowerShell-skript till ett PowerShell-arbetsflöde är att stänga det med nyckelordet arbets flöde .The first step to converting a PowerShell script to a PowerShell workflow is enclosing it with the Workflow keyword. Ett arbets flöde börjar med nyckelordet arbets flöde följt av bröd texten i skriptet inom klammerparenteser.A workflow starts with the Workflow keyword followed by the body of the script enclosed in braces. Namnet på arbets flödet följer arbets flödets nyckelord, som du ser i följande syntax:The name of the workflow follows the Workflow keyword as shown in the following syntax:

Workflow Test-Workflow
{
    <Commands>
}

Namnet på arbetsflödet måste matcha namnet på Automation-runbook.The name of the workflow must match the name of the Automation runbook. Om runbooken importeras måste fil namnet matcha arbets flödets namn och måste sluta med . ps1.If the runbook is being imported, then the filename must match the workflow name and must end in .ps1.

Om du vill lägga till parametrar i arbets flödet använder du nyckelordet param precis som du skulle göra med ett skript.To add parameters to the workflow, use the Param keyword just as you would to a script.

KodändringarCode changes

PowerShell-arbetsflödet ser nästan likadant ut som skript kod med PowerShell förutom några få betydande ändringar.PowerShell workflow code looks almost identical to PowerShell script code except for a few significant changes. I följande avsnitt beskrivs ändringar som du måste göra i ett PowerShell-skript för att det ska kunna köras i ett arbets flöde.The following sections describe changes that you need to make to a PowerShell script for it to run in a workflow.

AktiviteterActivities

En aktivitet är en viss uppgift i ett arbetsflöde.An activity is a specific task in a workflow. Precis som ett skript består av ett eller flera kommandon, består ett arbetsflöde av en eller flera aktiviteter som utförs i en sekvens.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. Windows PowerShell-arbetsflöde konverterar automatiskt många av Windows PowerShell-cmdlets för aktiviteter när ett arbetsflöde körs.Windows PowerShell Workflow automatically converts many of the Windows PowerShell cmdlets to activities when it runs a workflow. När du anger en av dessa cmdletar i din runbook körs motsvarande aktivitet med Windows Workflow Foundation.When you specify one of these cmdlets in your runbook, the corresponding activity is run by Windows Workflow Foundation. För cmdletar där en motsvarande aktivitet saknas, körs Windows PowerShell-arbetsflöde automatiskt cmdleten i en InlineScript aktivitet.For those cmdlets without a corresponding activity, Windows PowerShell Workflow automatically runs the cmdlet within an InlineScript activity. Det finns en uppsättning cmdletar som är undantagna och inte kan användas i ett arbetsflöde om de inte uttryckligen skrivs in i ett InlineScript-block.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. Mer information om de här koncepten finns med hjälp av aktiviteter i Skriptarbetsflöden.For further details on these concepts, see Using Activities in Script Workflows.

Arbetsflödesaktiviteter delar en uppsättning gemensamma parametrar för konfiguration av deras funktion.Workflow activities share a set of common parameters to configure their operation. Mer information om arbetsflödets gemensamma parametrar finns about_WorkflowCommonParameters.For details about the workflow common parameters, see about_WorkflowCommonParameters.

Positions parametrarPositional parameters

Du kan inte använda positions parametrar med aktiviteter och cmdlets i ett arbets flöde.You can't use positional parameters with activities and cmdlets in a workflow. Allt detta innebär att du måste använda parameter namn.All this means is that you must use parameter names.

Anta till exempel följande kod som hämtar alla tjänster som körs.For example, consider the following code that gets all running services.

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

Om du försöker köra samma kod i ett arbets flöde får du ett meddelande som "parameter uppsättningen kan inte lösas med de angivna namngivna parametrarna".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." Du korrigerar detta genom att ange parameter namnet enligt följande.To correct this, provide the parameter name as in the following.

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

Avserialiserade objektDeserialized objects

Objekt i arbets flöden avserialiseras.Objects in workflows are deserialized. Det innebär att deras egenskaper fortfarande är tillgängliga, men inte deras metoder.This means that their properties are still available, but not their methods. Överväg till exempel följande PowerShell-kod som stoppar en tjänst med hjälp av metoden STOP för serviceobjektet.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()

Om du försöker köra detta i ett arbets flöde får du ett fel meddelande om att "metod anropet inte stöds i ett Windows PowerShell-arbetsflöde".If you try to run this in a workflow, you receive an error saying "Method invocation is not supported in a Windows PowerShell Workflow."

Ett alternativ är att omsluta dessa två rader med kod i ett InlineScript -block där $service skulle vara ett tjänst objekt i blocket.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()
    }
}

Ett annat alternativ är att använda en annan cmdlet som utför samma funktion som metoden, om en sådan finns.Another option is to use another cmdlet that performs the same functionality as the method, if one is available. I vårt exempel tillhandahåller cmdleten stoppa-service samma funktioner som metoden stop och du kan använda följande för ett arbets flöde.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

InlineScript -aktiviteten är användbar när du behöver köra ett eller flera kommandon som traditionellt PowerShell-skript i stället för PowerShell-arbetsflöde.The InlineScript activity is useful when you need to run one or more commands as traditional PowerShell script instead of PowerShell workflow. Medan kommandon i ett arbetsflöde skickas till Windows Workflow Foundation för bearbetning, bearbetas kommandona i ett InlineScript-block av 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 använder följande syntax som visas nedan.InlineScript uses the following syntax shown below.

InlineScript
{
    <Script Block>
} <Common Parameters>

Du kan returnera utdata från en InlineScript genom att tilldela utdata till en variabel.You can return output from an InlineScript by assigning the output to a variable. I följande exempel stoppas en tjänst och sedan genereras tjänst namnet.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
}

Du kan skicka värden till ett InlineScript-block, men du måste använda $using omfångs modifierare.You can pass values into an InlineScript block, but you must use $Using scope modifier. Följande exempel är identiskt med föregående exempel, förutom att tjänst namnet tillhandahålls av en variabel.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
}

InlineScript-aktiviteter kan vara kritiska i vissa arbets flöden och de har inte stöd för arbets flödes konstruktioner och bör endast användas vid behov av följande orsaker: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:

  • Det går inte att använda kontroll punkter i ett InlineScript-block.You cannot use checkpoints inside an InlineScript block. Om ett fel inträffar i blocket måste det återupptas från början av blocket.If a failure occurs within the block, it must be resumed from the beginning of the block.
  • Du kan inte använda parallell körning i en InlineScriptBlock.You cannot use parallel execution inside an InlineScriptBlock.
  • InlineScript påverkar skalbarheten för arbets flödet eftersom den innehåller Windows PowerShell-sessionen för hela längden på InlineScript-blocket.InlineScript affects scalability of the workflow since it holds the Windows PowerShell session for the entire length of the InlineScript block.

Mer information om hur du använder InlineScript finns i köra Windows PowerShell-kommandon i ett arbets flöde och about_InlineScript.For more information on using InlineScript, see Running Windows PowerShell Commands in a Workflow and about_InlineScript.

ParallellbearbetningParallel processing

En fördel med Windows PowerShell-arbetsflöden är möjligheten att utföra en uppsättning kommandon parallellt i stället för sekventiellt som i ett vanligt skript.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.

Du kan använda det parallella nyckelordet för att skapa ett skript block med flera kommandon som körs samtidigt.You can use the Parallel keyword to create a script block with multiple commands that run concurrently. Följande syntax visas nedan.This uses the following syntax shown below. I det här fallet startar Activity1 och Activity2 på samma tidpunkt.In this case, Activity1 and Activity2 starts at the same time. Activity3 startar bara efter att både Activity1 och Activity2 har slutförts.Activity3 starts only after both Activity1 and Activity2 have completed.

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

Överväg till exempel följande PowerShell-kommandon som kopierar flera filer till ett nätverks mål.For example, consider the following PowerShell commands that copy multiple files to a network destination. Dessa kommandon körs i tur och ordning så att en fil måste slutföras innan nästa startas.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

Följande arbets flöde kör samma kommandon parallellt så att alla börjar kopieras samtidigt.The following workflow runs these same commands in parallel so that they all start copying at the same time. När alla har kopierats visas meddelandet slut för ande.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."
}

Du kan använda den ForEach-Parallel konstruktion kommandon bearbetas parallellt för varje objekt i en samling.You can use the ForEach -Parallel construct to process commands for each item in a collection concurrently. Objekt i samlingen bearbetas parallellt medan kommandona i skriptblocket körs sekventiellt.The items in the collection are processed in parallel while the commands in the script block run sequentially. Följande syntax visas nedan.This uses the following syntax shown below. I det här fallet startar Activity1 på samma tid för alla objekt i samlingen.In this case, Activity1 starts at the same time for all items in the collection. Activity2 startar när Activity1 har slutförts för varje objekt.For each item, Activity2 starts after Activity1 is complete. Activity3 startar bara efter att både Activity1 och Activity2 har slutförts för alla objekt.Activity3 starts only after both Activity1 and Activity2 have completed for all items. Vi använder parametern ThrottleLimit för att begränsa parallellitet.We use the ThrottleLimit parameter to limit the parallelism. För hög av en ThrottleLimit kan orsaka problem.Too high of a ThrottleLimit can cause problems. Det idealiska värdet för parametern ThrottleLimit är beroende av många faktorer i din miljö.The ideal value for the ThrottleLimit parameter depends on many factors in your environment. Du bör försöka starta med ett lågt värde och prova med olika ökande värden tills du hittar något som fungerar för dina speciella omständigheter.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>

Följande exempel liknar det tidigare exemplet som kopierar filer parallellt.The following example is similar to the previous example copying files in parallel. I det här fallet visas ett meddelande för varje fil efter att den har kopierats.In this case, a message is displayed for each file after it copies. Det slutliga slut för ande meddelandet visas bara när alla har kopierats fullständigt.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."
}

Anteckning

Vi rekommenderar inte att du kör underordnade Runbooks parallellt eftersom detta har visats för att ge otillförlitliga resultat.We do not recommend running child runbooks in parallel since this has been shown to give unreliable results. Utdata från den underordnade runbooken visas ibland inte, och inställningarna i en underordnad Runbook kan påverka de andra parallella underordnade Runbooks.The output from the child runbook sometimes does not show up, and settings in one child runbook can affect the other parallel child runbooks. Variabler som $VerbosePreference, $WarningPreference och andra kanske inte sprids till underordnade Runbooks.Variables such as $VerbosePreference, $WarningPreference, and others may not be propagated to the child runbooks. Och om den underordnade runbooken ändrar dessa värden kanske de inte återställs korrekt efter anrop.And if the child runbook changes these values, they may not be properly restored after invocation.

KontrollpunkterCheckpoints

En kontroll punkt är en ögonblicks bild av det aktuella läget för det arbets flöde som innehåller det aktuella värdet för variabler och alla utdata som genereras till den punkten.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. Om ett arbets flöde slutar fungera eller har pausats startar det igen från den senaste kontroll punkten i stället för arbets flödets start.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. Du kan ange en kontrollpunkt i ett arbetsflöde med den Checkpoint-Workflow aktivitet.You can set a checkpoint in a workflow with the Checkpoint-Workflow activity. Azure Automation har en funktion som kallas rättvis delning, där alla Runbook-flöden som körs i 3 timmar är inaktiverade för att tillåta andra Runbooks att köras.Azure Automation has a feature called fair share, where any runbook that runs for 3 hours is unloaded to allow other runbooks to run. Slutligen kommer den inaktiverade runbooken att läsas in igen och när den är det återupptar den körningen från den senaste kontroll punkten som tagits i runbooken.Eventually, the unloaded runbook will be reloaded, and when it is, it will resume execution from the last checkpoint taken in the runbook. För att garantera att runbooken slutligen kommer att slutföras, måste du lägga till kontroll punkter i intervall som körs i mindre än tre timmar.In order to guarantee that the runbook will eventually complete, you must add checkpoints at intervals that run for less than 3 hours. Om du lägger till en ny kontroll punkt under varje körning, och om runbooken tas bort efter tre timmar på grund av ett fel, kommer runbooken att återupptas oändligt.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.

I följande exempel kod inträffar ett undantag efter det att Activity2 orsakar att arbets flödet avslutas.In the following sample code, an exception occurs after Activity2 causing the workflow to end. När arbets flödet körs igen startar det genom att köra Activity2 eftersom det var precis efter den senaste kontroll punkts uppsättningen.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>

Du bör ange kontroll punkter i ett arbets flöde efter aktiviteter som kan vara känsliga för undantag och som inte bör upprepas om arbets flödet återupptas.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. Arbets flödet kan till exempel skapa en virtuell dator.For example, your workflow may create a virtual machine. Du kan ange en kontrollpunkt både före och efter kommandona för att skapa den virtuella datorn.You could set a checkpoint both before and after the commands to create the virtual machine. Om det inte går att skapa, upprepas kommandona om arbets flödet startas igen.If the creation fails, then the commands would be repeated if the workflow is started again. Om arbets flödet Miss lyckas när skapandet har slutförts skapas inte den virtuella datorn igen när arbets flödet återupptas.If the workflow fails after the creation succeeds, then the virtual machine will not be created again when the workflow is resumed.

I följande exempel kopieras flera filer till en nätverks plats och anger en kontroll punkt efter varje fil.The following example copies multiple files to a network location and sets a checkpoint after each file. Om nätverks platsen tappas bort slutar arbets flödet med fel.If the network location is lost, then the workflow ends in error. När den startas igen fortsätter den vid den senaste kontroll punkten, vilket innebär att endast de filer som redan har kopierats hoppas över.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."
}

Eftersom autentiseringsuppgifter för användar namn inte är sparade när du anropar aktiviteten pausa – arbets flöde eller efter den senaste kontroll punkten, måste du ange autentiseringsuppgifterna till null och sedan hämta dem igen från till gångs lagret efter att du har gjort uppehåll i arbets flödet eller kontroll punkten.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. Annars kan du få följande fel meddelande: det går inte att återuppta arbets flödes jobbet, antingen på grund av att beständiga data inte kunde sparas fullständigt eller att sparade beständiga data har skadats. Du måste starta om arbets flödet.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.

Följande kod visar hur du hanterar det här i dina PowerShell Workflow-Runbooks.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 "WestUs" -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 -Credential $Cred
        }
}

Viktigt

Add-AzureRmAccount är nu ett alias för Connect-AzureRmAccount.Add-AzureRmAccount is now an alias for Connect-AzureRMAccount. Om du inte ser Connect-AzureRMAccountnär du söker i biblioteks objekt kan du använda Add-AzureRMAccount, eller så kan du uppdatera dina moduler i ditt Automation-konto.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.

Detta krävs inte om du autentiserar med hjälp av ett Kör som-konto som kon figurer ATS med ett huvud namn för tjänsten.This is not required if you are authenticating using a Run As account configured with a service principal.

Mer information om kontrollpunkter finns att lägga till kontrollpunkter till ett arbetsflöde för skript.For more information about checkpoints, see Adding Checkpoints to a Script Workflow.

Nästa stegNext steps