Summary: Learn how to troubleshoot a Windows PowerShell script within Orchestrator.

 Hey, Scripting Guy!

I’m having some trouble debugging my Windows PowerShell script in Orchestrator. Do you have any tips that might help us along?

—DM

 Hello DM,

Honorary Scripting Guy, Sean Kearney here. I continue to fill in for Ed this week while he “branches out” to new areas with his camera.

So one thing you will have discovered if you have used Windows PowerShell with Orchestrator is that the Runbook Tester cannot view the Windows PowerShell objects. In fact, if you get an error message with your Windows PowerShell script in Orchestrator, you may very well be staring at some obscure looking .NET error message from the Windows PowerShell engine like this:

Looking at that is not very helpful. It doesn’t tell me where in the script it failed, what it was doing, or the value of my objects. Only that it…well…FAILED.

But remember, we are never lost in the world of Windows PowerShell. First off, let’s think about how we built the script.

You probably built it within some type of ISE with sample values and data to ensure that it actually worked outside of Orchestrator. Then at some point you copied in the script.

So logically (if this is the exact script you started with), it must be something that is introduced by Orchestrator. Say for example a Variable or Published Data you subscribed to? Or possibly something your script is monitoring is coughing up a $Null value?

Within Windows PowerShell, we have many built-in options for debugging. Within Orchestrator, you can start with the simplest approach, which is get the data out of the script into somewhere that you can examine it.

The simplest method I have come across is to drop points in the script and have it export various variables by using Export-Clixml. That way if the script crashes, you’ll have values from the script outside of Orchestrator with Date/Time stamps.

In the following sample script in Orchestrator, I have some lines that I can uncomment for testing purposes:

By Using the Export-Clixml to pull the data out, we get the object (how little or how much exists), so we can at least determine if we are getting the data we were supposed to be getting by diving into Windows PowerShell and examining these files like so:

[xml]$Filename=GET-CONTENT C:\Debug\Filename.xml

$Filename | GET-MEMBER

We can examine the data and view it externally to see if we are receiving a Null, an array, or complete jibberish.

We can also pull out two more options. We can temporarily Exit the script earlier to determine where the error actually is by using the Exit command.

This can at least tell us where things are going bad. If we can get the Runbook Tester to stop throwing errors, we can identify where in the script things are running poorly.

The main trick, of course, is to ensure that the script works in the ISE. If your logic is broken before you plug it into Orchestrator, you’ll have a bigger mess on your hands.

Next time we’ll look at some caveats and things to look out for when leveraging the two technologies.

I invite you to follow the Scripting Guys on Twitter and Facebook. If you have any questions, send email to scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Sean Kearney, Honorary Scripting Guy
Windows PowerShell MVP