Windows PowerShell: When to Choose Workflow Versus Script Functions
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Windows PowerShell gives systems administrators so many options for solving our network management problems, it can sometimes be challenging to decide which method is most effective. Take workflows, for instance. In my experience, not many Windows sysadmins have a realistic understanding of how the PowerShell workflow, well, works.
A workflow in general terms is a predefined business process. The process, whatever it is, consists of a series of steps (activities) that accomplish a given result.
Microsoft added the Windows Workflow Foundation (WF) engine to version 3.0 of the .NET Framework. This means that when you run a PowerShell-defined workflow, the PowerShell runtime (a) compiles the script into Extensible Application Markup Language (XAML); and (b) submits the XAML data to the local computer's WF engine for processing.
Let's imagine that you need to perform the following tasks on a fleet of 12 new servers:
- Set hostname (and reboot).
- Join Active Directory (AD) domain (and reboot).
- Enumerate all installed .dll files and copy an output file to a network share.
Those three configuration tasks involve some aspects that may cause some "speed bumps":
- How can we ensure that the hostname change occurs before the AD join step?
- What happens if one of the target computers gets "stuck"?
- When and how can we verify that the long-running .dll enumeration step completed successfully for all 12 servers?
One of the cool things about Windows PowerShell is that you can write advanced functions by using PowerShell itself. You don't need to be a .NET developer and code your functions in C#.
We'll start by examining the similarities between PowerShell functions and workflow. Then we'll tease apart the differences, which should make it clear which approach is best for our case study example.
Workflow Versus Functions: Initial Similarities and Differences
If we write "Hello world" samples, we see that the general syntax of PowerShell functions is practically identical to that of PowerShell workflows. Here's the workflow:
workflow Start-ConfigWF {
Param ([string]$param1)
Write-Output "Hello $param1"
}
And here's an equivalent function:
function Start-ConfigFunc {
Param ([string]$param1)
Write-Output "Hello $param1"
}
You call workflows and functions in the same way:
Start-ConfigWF -param1 'world' Hello world Start-ConfigFunc -param1 'world' Hello world
This is a contrived example, but you get the idea: The PowerShell team designed the workflow syntax to mimic that of traditional PowerShell functions.
Never forget, however, that a PowerShell workflow is XAML under the hood. You can see the underlying Start-ConfigWF XAML by running the following command:
Get-Command -Name Start-ConfigWF | Format-List *
Although you certainly can (and will) include PowerShell commands in your workflow definitions, the built-in workflow activities aren't PowerShell at all, but rather PowerShell abstractions of WF activities. To wit, some key workflow activities are as follows:
- InlineScript: For running ad hoc PowerShell commands.
- Parallel: For running workflow tasks in a "fan out" fashion (multiple computers working simultaneously).
- Sequence: For running workflow tasks in a serial fashion (one computer at a time).
- Checkpoint-Workflow: For setting a rollback/resume location in a workflow.
- Suspend-Workflow: For gracefully pausing and resuming a workflow.
For my money, Invoke-Command goes a long way in PowerShell functions. With it, you can perform parallel command execution on up to 32 computers at once by default. You can apply the -ThrottleLimit parameter to scale the "fan out" in either direction.
But can Invoke-Command, PowerShell remoting, and advanced functions make a configuration script resume after a system restart? What about configuration tasks that need to be performed in a specific sequence?
Workflow-Only Feature: Sequencing
Let's say you write a PowerShell script that performs the following actions:
Function Start-ConfigFunc2 {
Param ([string[]]$computername)
Get-CimInstance -ClassName Win32_BIOS -PSComputerName $computername
Get-Service -Name *svchost* -PSComputerName $computername
}
Do you have any assurance whether the WMI call or the process call will happen first, and on which hosts? No, you don't. But what about situations when sequence does matter? That's a perfect use case for PowerShell workflow.
Look at this sample workflow:
workflow Start-ConfigWF2 {
param ([string[]]$computername)
foreach -Parallel ($computer in $computername) {
sequence {
Get-CimInstance -ClassName Win32_BIOS -PSComputerName $computer
Get-Service -Name *svchost* -PSComputerName $computer
}
}
}
Start-ConfigWF2 -computername 'dc1','mem1'
In this case, the foreach -Parallel construction specifies that we'll hit all target computers simultaneously. However, the sequence keyword ensures that the Get-CimInstance fires first, and then the Get-Service.
This is powerful stuff, especially when we consider certain operations that must complete before others to fulfill dependencies.
Workflow-Only Features: Checkpointing, Persistence, and Resumability
In my experience, PowerShell function scripts that use remoting to target multiple systems can run into all kinds of snags. For example, it's annoying when my script bombs out halfway through execution. What are you left with in terms of picking up the proverbial pieces?
The ability to checkpoint and suspend/resume workflows is probably the most important reason for you to consider using them in your production configuration-management work.
You set checkpoints at potentially volatile parts of your workflow. One easy way to add them to your workflow scripts is by adding the -PSPersist parameter to the activity you want to complete just before the checkpoint:
workflow Start-ConfigWF3 {
param ([string[]]$computername)
foreach -Parallel ($computer in $computername) {
sequence {
Get-CimInstance -ClassName Win32_BIOS -PSComputerName $computer -PSPersist $true
Restart-Computer -Wait -Force -PSComputerName $computer
Get-Service -Name *svchost* -PSComputerName $computer
}
}
}
Start-ConfigWF3 -computername 'mem1'
I know I keep repeating this, but it's important: You're writing a sort of pseudo-PowerShell script when you write a workflow script. The Restart-Computer activity call above isn't the same Restart-Computer cmdlet that you've used in traditional PowerShell.
The -Wait switch keeps the workflow running on the management computer throughout the target computers' restart process.
If the computer running this workflow crashed, we'd be able to resume the workflow from the checkpoint. By the way, to resume a crashed workflow from a checkpoint, you simply run the workflow again. The WF engine on the management computer will figure out where it needs to resume, based on the last checkpoint defined in the script.
Finally, we can suspend and resume workflows. Here's a quick test:
workflow Test-Suspend {
$d = Get-Date
Suspend-Workflow
(Get-Date) - $d
}
Test-Suspend
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
7 Job7 PSWorkflowJob Suspended True localhost Test-S...
Do you see what happened? Suspending a job creates a persistent PSWorkflowJob on the management computer. You can then connect to and resume the job from the local host or a remote computer:
Resume-Job -Id 7
Final Thoughts
I hope that you now have a better idea of when to use PowerShell workflows versus traditional functions. In short, unless you have long-running tasks that need to survive restarts and may require persistence, you're safe using both simple and advanced functions.
This article wouldn't have been possible without the direct and indirect assistance of my mentor, PowerShell MVP Don Jones. I'll leave you with some of his workflow-related writings to move you further along your learning curve:
- Windows PowerShell: What Is Windows PowerShell Workflow?
- PowerShell Workflow: When Should You Use It?
- Windows PowerShell: PowerShell Scripts vs. PowerShell Workflows
Happy PowerShelling!