{"id":4317,"date":"2013-01-16T00:01:00","date_gmt":"2013-01-16T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/01\/16\/powershell-workflows-job-engine\/"},"modified":"2013-01-16T00:01:00","modified_gmt":"2013-01-16T00:01:00","slug":"powershell-workflows-job-engine","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/powershell-workflows-job-engine\/","title":{"rendered":"PowerShell Workflows: Job Engine"},"content":{"rendered":"

Summary:<\/strong> Windows PowerShell MVP Richard Siddaway continues his workflow series by talking about the job engine.<\/span>\nMicrosoft Scripting Guy, Ed Wilson, is here. Today, we have the fourth in a series of guest blog posts written by Windows PowerShell MVP and Honorary Scripting Guy<\/a> Richard Siddaway dealing with Windows PowerShell workflow.<\/p>\n

Note<\/strong>   The first article, PowerShell Workflows: The Basics<\/a>, <\/em>introduced the basic concepts of Windows PowerShell workflow. The second article, PowerShell Workflows: Restrictions<\/a>, <\/em>discussed the restrictions encountered with working with Windows PowerShell workflows. The third article, PowerShell Workflows: Nesting<\/a>, talks about nesting workflows. You should read those articles prior to reading today’s article.\nRichard has written a number of guest Hey, Scripting Guy! Blog posts<\/a>, and he has also written two books on Windows PowerShell. His most recent book, PowerShell in Depth<\/a>, is co-written with fellow MVPs Don Jones and Jeffrey Hicks.\nNow, take it away, Richard …\nRemember the first workflow you saw in this series—it was a simple “Hello World.”<\/p>\n

workflow hello {<\/p>\n

 “Hello World”<\/p>\n

}\nYou could run it like this:<\/p>\n

PS> hello<\/p>\n

Hello World<\/p>\n

Running a workflow as a job<\/h2>\n

All workflows have the ability to run as a Windows PowerShell Job:<\/p>\n

PS> hello -AsJob -JobName w1<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

9      w1              PSWorkflowJob   NotStarted    True            localhost\nYou get the –AsJob<\/strong> parameter, which starts the workflow as a Job, and you also get the –JobName<\/strong> parameter, which allows you to give your own name to workflow’s Job. Contrast that with other situations where you only get the ability to run a cmdlet as a Job, for example, with the WMI cmdlets you don’t get the ability to give the Job a name.\nThe other important point to note is the PSJobTypeName<\/strong>—it’s PSWorkflowJob<\/strong>. This is a new Job category introduced in Windows PowerShell 3.0, just for workflows.\nAfter you’ve started your workflow as a Job, it is handled as any other Job:<\/p>\n

PS> Get-Job<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

9      w1              PSWorkflowJob   Completed     True            localhost<\/p>\n

 <\/p>\n

PS> Receive-Job -Name w1<\/p>\n

Hello World\n \nBy definition, workflows are long-running tasks for which you don’t expect to provide interactive input. They are ideally suited for running as Windows PowerShell Jobs.\nThere’s a bit more to workflows and the way they work with the Windows PowerShell Job engine, which is just as well as otherwise I wouldn’t have enough to write about.<\/p>\n

Stopping and starting workflows<\/h2>\n

Windows PowerShell workflows are built on top of the Windows PowerShell Job engine. One of the capabilities this gives you is the ability to suspend and resume the workflow. Let’s simulate a long-running workflow:<\/p>\n

workflow test-wfsuspension {<\/p>\n

 Start-Sleep -seconds 10<\/p>\n

 Suspend-Workflow<\/p>\n

 Get-ChildItem<\/p>\n

}<\/p>\n

 \nThe workflow will sleep for 10 seconds and then suspend itself through the call to Suspend-Workflow<\/strong>.\nOnce the workflow has suspended, you will see a display similar to this:<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

7      Job7            PSWorkflowJob   Suspended     True            localhost \n \nNotice that the State is set to Suspended. The data and state of the workflow have been saved to disk.\nYou can restart the Job by using the Resume-Job<\/strong> cmdlet:<\/p>\n

PS> Resume-Job -Id 7<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

7      Job7            PSWorkflowJob   Suspended     True            localhost\n <\/p>\n

PS> Get-Job<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

7      Job7            PSWorkflowJob   Completed     True            localhost \nThe data returned from the Resume-Job<\/strong> cmdlet may mislead you. It states that the job is Suspended<\/em>! The cmdlet reports the state of the Job before<\/em> it tells it to restart. After it is restarted, the Job completes and the data is available as usual.\nThis is useful but what is more useful is the ability to suspend a workflow Job, and then restart it in a different Windows PowerShell session! If you remove the old jobs and rerun the test-wfsuspension<\/strong> workflow, you’ll get something like this:<\/p>\n

PS> test-wfsuspension<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

9      Job9            PSWorkflowJob   Suspended     True            localhost \nI’m running these demonstrations in ISE, but this still works if you are using the Windows PowerShell console.\nShut down your PowerShell session and you don’t need to save any files<\/em>. That’s right. Just click the little close button at the top-right corner of the Windows PowerShell or ISE window. This is safe to try at home—honest.\nNow open up a new session (you need to run it with elevated privileges). I’m going to use ISE again, but feel free to use the console if you want to.\nNow try Get-Job<\/strong>, and you’ll see … nothing!\nOK, don’t panic. Import the Windows PowerShell workflow module again, and you’ll see your job:<\/p>\n

PS> Get-Job<\/p>\n

PS> Import-Module PSWorkflow<\/p>\n

PS> Get-Job<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

8      Job9            PSWorkflowJob   Suspended     True            localhost \nYou can then resume the job and retrieve the data when appropriate:<\/p>\n

PS> Get-Job<\/p>\n

PS> Import-Module PSWorkflow<\/p>\n

PS> Get-Job<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

8      Job9            PSWorkflowJob   Suspended     True            localhost \nNotice that the job ID may change between sessions although the job name will remain constant.<\/p>\n

Suspending a workflow job<\/h2>\n

There is another way to suspend workflow jobs—that’s by using the Suspend-Job<\/strong> cmdlet. Start with a workflow:<\/p>\n

workflow test-wfsr {<\/p>\n

 Start-Sleep -seconds 30<\/p>\n

 Checkpoint-Workflow<\/p>\n

 Get-ChildItem <\/p>\n

}\nStart the workflow as a Job:<\/p>\n

PS> test-wfsr -AsJob<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

11     Job11           PSWorkflowJob   Running       True            localhost<\/p>\n

 <\/p>\n

PS> Suspend-Job -Id 11<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

11     Job11           PSWorkflowJob   Suspending    True            localhost \nYou can then use Suspend-Job<\/strong> to suspend the job. The job will show a State of Suspending until the Job reaches the CheckPoint-Workflow<\/strong> statement. At this point, the Job enters a Suspended state:<\/p>\n

PS> Get-Job<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

11     Job11           PSWorkflowJob   Suspended     True            localhost \nYou can then resume the job when appropriate:<\/p>\n

PS> Resume-Job -id 11<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

11     Job11           PSWorkflowJob   Suspended     True            localhost\n <\/p>\n

PS> Get-Job<\/p>\n

Id     Name            PSJobTypeName   State         HasMoreData     Location <\/p>\n

—     —-            ————-   —–         ———–     ——– <\/p>\n

11     Job11           PSWorkflowJob   Completed     True            localhost\n \nIn this case, I’ve resumed the Job in the same session.\nA very important point to remember is that the Suspend-Job<\/strong> and Resume-Job<\/strong> cmdlets only work on workflow jobs. You will get an error if you try to suspend other job types!\nIn the last example, you need to use the Checkpoint-Workflow<\/strong> activity. This writes a copy of the workflows data and state to disk so that the job can be resumed. In other words, it takes a snapshot. If you don’t take that snapshot, the workflow has nowhere to suspend and it will effectively ignore the suspension.\nHere is a summary of the two suspension techniques:<\/p>\n