Recently I began experimenting in earnest with Powershell runspaces as an alternative to background jobs. My interest was mostly keyed by an excellent blog post on the subject by Boe Prox (blog | twitter). I’ve found that, in general, runspaces work really well for multi-threaded workloads, and, once you get past some initial hiccups, are easier to use than background jobs.
During my experimentation I had a bit of a realization around how runspaces are generally used. I found that I was generally doing the same things over and over again:
- Creating a script block to do the background work, which had one or more parameters.
- Creating a series of parameter sets containing the information about the individual “entities” to be processed.
- Instantiating various objects and settings for the runspace configuration, such as the number of concurrent runspaces.
- Starting the background threads and waiting for them to finish.
- Getting the data back from the runspaces, and returning warnings for any errors that occurred during processing.
After copying and slightly modifying code a few times, I said to myself, “Self! This is not good practice copying and pasting code all over the place. Why not write a reusable and generic function implementing this work and simply re-use it?” Thus Execute-RunspaceJob was born.
The function basically encapsulates and makes generic the work required to setup and execute a parameterized script block within background runspaces. It also handles tricky items such as error handling and parsing return data. Let’s look at a quick example of how to use it.
Let’s say that you have a function called Get-DiskspaceInfo, which retrieves, well, information about disk space on remote machines using WMI calls. You have a series of servers, say, twenty, that you want to collect this information from. You could certainly simply get this list of servers and pipe them into the function (because you are writing functions that accept pipeline input, right?), but that approach would not scale very well since it operates in a one-at-a-time mode. Instead, using Execute-RunspaceJob, you could have any number (up to overwhelming your computer, naturally) of concurrent background threads collecting this information, then have it return the resulting data to you after it was finished.
First, you need to construct the script block which actually executes the work:
|
|
$scriptBlock = { param ( $ServerName ) # Set the error action preference to ensure that any errors cause execution to immediately halt $ErrorActionPreference = 'Stop' # Load the function . C:\Powershell\Functions\Get-DiskspaceInfo.ps1 # Get the information Get-DiskspaceInfo -ComputerName $ServerName } |
Next, we need to construct a hashtable of parameter values. The function expects a hashtable where the key is some unique identifier for the row to be processed (like a server name, database name, file name, etc), and the value is a nested hashtable of “parameter name”=”parameter value” pairs.
|
|
$parameters = @{} $servers = Get-Content $env:temp\servers.txt foreach ($server in $servers) { $paramValue = @{ 'ServerName' = $_ } $parameters.Add($_,$paramValue) } |
Finally, we execute the function, letting the results be placed into an array variable. We use the “-ThrottleLimit” parameter to specify the number of concurrent operations that are allowed.
|
|
$data = @() $data = Execute-RunspaceJob -ScriptBlock $scriptBlock -ArgumentList $parameters -ThrottleLimit 12 |
If any of the background operations fail, a warning message will be printed out on the screen. Once all the data is collected you can treat the array just like you would the set of data returned by a normal pipleine-style operation.
I’ve started using this all over the place, and found that it greatly increases performance of most “collect and return” type operations. For example, it will be used in my forthcoming adaptation of Alan Renouf’s excellent vCheck framework for SQL Server.
To download the latest version of the function, go here. And please, tell me if you see something wrong or have suggestions for enhancements!
