Debugging PowerShell & Automation Machine

Automation Machine has the feature to run self written PowerShell scripts. Troubleshooting the more complex scripts if they don’t work as expected can be pretty annoying. So for that Automation Machine has a built in debugging mode you can use within PowerShell. In this blogpost I’ll walk you through debugging mode and get you started on the inner workings.

This debugging mode is a so called step through debugger. Something well known if you’ve done some programming on more serious languages. You can set a “breakpoint” within a script at which point the PowerShell script will pause and will start debugging mode and give you options to troubleshoot your script.

Scenario

So you’ve got an error in a script. In this case it’s the script that handles adding a Citrix machine to a machine catalog (and creating it if it doesn’t exist).

Error

So you’ll want to troubleshoot this script and know why it fails. The script fails at line 21. But it would be nice to completely walk through the script to see if anything might be going wrong in an earlier stage. So we’ll add the following variable to the first line of the script. This will start debugging mode directly when the script is executed.

 

After that’s done we can start the client module on the affected machine. You can use the below 2 lines to import the module and trigger the start event in deployment without having the machine reboot afterwards:

 

As soon as AM triggers the scripts you’ll be presented with a prompt that you entered debug mode. If you enter “h” or “?” you’ll get the following information.

Debugging mode info

 

Let’s go through the different options and provide some more information about the workings of debug mode.

 

StepInto

As simple as it sounds. Simply executes the next statement in the script. Probably the most used option in debug mode.

s

 

StepOver

Skips the current command and brings you to the next statement in the script.

v

 

StepOut

Stops execution of the current script or function. In our case it’ll bring us back to the Automation Machine framework.

o

 

Continue

Obviously this continues the script and presents us with the error we’re trying to troubleshoot

c

 

Quit

Similar to stepout. Only this quits powershell execution completely. Pretty much the same as hitting Ctrl+C.

quit

 

Get-PSCallStack

This is one of the more interesting ones if you want to get an overview of the situation. It shows you the scripts that are currently running and with which arguments they’ve been started. At the top you see the Create-Catalog.ps1 script we’re trying to troubleshoot. At the bottom you see the initial command we run within the AM PoSh module, Invoke-AMEvent.

k

 

List

List shows you the code of the script you’re running right now. Which I personally don’t use to often. This form of troubleshooting is a last resort most of the time so by then I’ve already opened the script, any script related to it and any administration console which could be usefull. So reading scripts from within a PowerShell window doesn’t have my preference.

List can show you the upcoming lines, which it does by default

list

Or you can get it to show lines from a certain point onward

list 10

And finally you can get it to stretch the amount of lines you want to show by defining a start and end point

list 10 30

Solving the issue using debugging mode

Ok, now you know how the debugging mode works but we haven’t actually solved our issue. So let’s get back to the error and see if we can solve it.

The problem occurs at line 21 when it checks to see if an broker has been selected. In the code block before in a foreach loop each broker is checked for 2 active Citrix related services. I’ve already checked that both services are active so a Citrix related issue has been ruled out. Before that there’s only a single line of code which splits a environment variable (from the Automation Machine package in this case) into an array using the “Split” method (more info on split here). Let’s start using debug mode to see if we can find the issue.

Without doing anything. Let’s check the content of the xa_vda_ddc environment variable.

01

It’s filled with a comma separated list of machine (CTX-INFRA.lab.local,CTX-INFRA2.lab.local.

Ok, that doesn’t sound bad. Let’s continue by stepping into the script and then executing the actual first line of code (besides the line we’ve inserted to start debug mode). After we’ve done that let’s continue by checking the output of the split method used by checking the $broker variable.

02

Ok, so that’s not really what we wanted and we’ve probably already found the issue. The split method was invoked to get the variable, which was a simple string, changed to an array which we use in the next code block which was a foreach loop.

So to get this fixed. we either need to provide the split method with something it can split into an array or we need to change the split method to be able to split something that’s comma separated. The latter is pretty simple, we’d need to change the first line from this:

$Brokers = $env:xa_vda_ddc.Split()

Into this:

$Brokers = $env:xa_vda_ddc.Split(",")

 

That would work, but isn’t really the “nicest” solution. These packages were created by the Automation Machine team. So they should work without having to change the code. So the preferred method of fixing this would be in information that is fed to the split method. Which is an environment variable injected by the AM package. Looking at the private variables of the package and the tooltip of the variable the problem is revealed.

03

So instead of separating multiple DDC’s using a comma, you should separate the DDC’s with spaces. Which is something that Citrix requires on a couple of their cmdlets so Automation Machine has adopted that to keep things standardized.

So that concludes our debugging session in Automation Machine & PowerShell.

Leave a Reply