Updating Citrix XenDesktop 5.5 desktop catalogs with PowerShell cmdlet

Those who have worked with Citrix XenDesktop pools would probably understand the pain of updating their desktop catalogs via the Update Machine option within Desktop Studio:

First of all, I find the Desktop Studio responsiveness / wait times with VMware sluggish at most times and when you have quite a few desktop pools to update with updated master images, waiting for the spinning ticker can seem like a life time:

Now when you have to go through 4 windows for the Update Machine wizard, updating your desktop pools can quickly become a tedious and annoying task:

As I’ve been recently building out 2 new Citrix XenDesktop environments, I found it extremely annoying to have to navigate through the GUI when I wanted to quickly update desktop pools.  I’m not usually a scripting person but when I run into situations like this where I feel the speed of my work is hindered by constant waiting, I immediately start thinking about ways to expedite and automate the process.

Citrix actually provides the cmdlet Publish-ProvMasterVmImage which more information can be found here: http://support.citrix.com/static/kc/CTX127254/help/Publish-ProvMasterVmImage.htm, which is available via PowerShell that allows you to update your desktop pools.  A detailed KB explaining the process and providing examples is also available here: http://support.citrix.com/article/CTX129205 to walk you through the process.

As nice as having this command in PowerShell is, I was a bit disappointed with the amount of detail the KB provided in regards to what the Rollout Strategy was when using the cmdlet.  The KB article doesn’t tell you and the page explaining the cmdlet doesn’t provide you with the option either.  I could be wrong but through my tests, it looks like the rollout strategy when using the cmdlet is set to None because regardless of whether I had active sessions with the virtual desktops or not, they were never rebooted after the update was completed.  My guess is that Citrix expects us to follow up with another command to reboot the desktops.

Whenever I need to learn something, I always go through the manual and dissect each line while taking notes so that when I need to use it again in the future, I can reference my notes to refresh my memory rather than going through the same process of dissecting the instructions again so the following are my notes on updating desktop pools with the Publish-ProvMasterVmImage PowerShell command.

Step #1 – Get the ProvisioningSchemeName and MasterImageVM of the desktop pool you want to update

The first step for updating a desktop pool is to obtain the following 2 values for the pool you want to update:

• ProvisioningSchemeName
• MasterImageVM

These 2 values can be obtained with the command Provscheme but if you were to simply execute that command, it will return all the information of your desktop catalogs which will most likely fill a few screens of your PowerShell window.  I’m not a big fan of scrolling and weeding through lines of code so to filter out only the information I want, I use the format-list command to list only the 2 variables I need:

provscheme | format-list ProvisioningSchemeName,MasterImageVM

Notice how there are 8 pools listed and it already pretty much fills up the command window but because we’re only listed 2 values for each pool, there is just enough information to prevent us from having to scroll.

With the output above, make a note of the 2 values for the pool you want to update.  For the purpose of this example, we’ll be updating the pool with the:

ProvisioningSchemeName: Internal Win7 Random – Windows 7 64-bit_Datacenter_01

… and …

MasterImageVM: XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1-X64_v1.vm

Note that the value I wrote above for the MasterImageVM is:

XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1-X64_v1.vm

… and not:

XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1-X64_v1.vm\Snappy Snap.snapshot

The reason why I did not include the snapshot path is because the next step will be to list the snapshots of this master image and omitting the snapshot details will give us a cleaner output.

Step #2 – Get the snapshots for the master VM

The next step is to list out the snapshots the master VM currently has and to do so, we need to execute the following:

Get-ChildItem -Recurse -Path 'XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1_x64_v1.vm'

Note that the above command is simply:

Get-ChildItem -Recurse -Path …

with the MasterImageVM value we retrieved in step 1 WITHOUT the snapshot at the end:

XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1-X64_v1.vm

Once we’ve executed this command, we’ll be provided with the following output:

The beginning value of each snapshot is the PSPath and as seen in the above output, we have 2 snapshots for this master image:

• Snappy Snap
• Snapperoo

The snapshots are listed in the oldest to newest order so Snappy Snap is the first snapshot and Snapperoo is the second snapshot.  Copy down the FullPath value of the snapshot you want to update your master image with into notepad.  For the purpose of this example, we’ll be using the following:

XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1_x64_v1.vm\Snappy Snap.snapshot\Snapperoo.snapshot

Step #3 – Update the pool with the master image snapshot

The final step is to proceed with updating your desktop catalog / pool with a snapshot that’s on the master image.  The Citrix KB states the following:

Publish-ProvMasterVmImage -ProvisioningSchemeName "%provisioningSchemeName%" - MasterImageVM "%templatePSPath%"

The notes I have to help myself understand this more is:

Publish-ProvMasterVmImage -ProvisioningSchemeName <provisioningSchemeName that we retrieved with Step #1> -MasterImageVM <the FullPath value you retrieved in Step #2>

For this example, the command would look as follows:

Publish-ProvMasterVmImage -ProvisioningSchemeName "Internal Win7 Random - Windows 7 64-bit_Datacenter_01" -MasterImageVM "XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1_x64_v1.vm\Snappy Snap.snapshot\Snapperoo.snapshot"

Once you execute this command, you’ll notice that you won’t get to type in the PowerShell command prompt and this is an indication that the update is in progress:

You can view the status of the update from within the Recent Tasks window of your vCenter:

Based on my tests, I did not see the status being listed within Desktop Studio’s Machines or Actions tab and I’m using XenDesktop 5.5.

Upon completion, you’ll see output similar to the following:

As I mentioned earlier, it looks like the Rollout Strategy from using this deployment defaults to none as I did not see any of my virtual desktops automatically reboot.  A quick way to check to see if your virtual desktops are still on the old master image’s snapshot or the current one is to execute the following:

Get-BrokerDesktop -DesktopGroupName <Desktop Group Name> | format-list MachineName,ImageOutOfDate

Note that the desktop group name is found in the Assignments node:

Or via the cmdlet:

Get-BrokerDesktopGroup | format-list Name

So for example, the cmdlet would look something like the following:

Get-BrokerDesktop -DesktopGroupName "Windows 7 64-bit Internal Static" | format-list MachineName,ImageOutOfDate

Note that all of the values for the variable ImageOutOfDate is listed as being True.  To complete the update, you can proceed with rebooting the virtual desktops either via the Desktop Studio GUI or PowerShell cmdlet which I haven’t looked into you but will update this post when I get the chance.

Shortening the process of updating the desktop pools with PowerShell

So rather than constantly repeating these steps, you can actually cut short the process by documenting the generic paths of your pools so that you can quickly execute step #3 without having to constantly go through steps #1 and #2.  By this I mean that if your desktop pools haven’t changed and your master image hasn’t changed, all that’s really going to change as you update your pools is the snapshot name.  So as an example, the following cmdlet we used to update our catalog:

Publish-ProvMasterVmImage -ProvisioningSchemeName "Internal Win7 Random - Windows 7 64-bit_Datacenter_01" -MasterImageVM "XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1_x64_v1.vm\Snappy Snap.snapshot\Snapperoo.snapshot"

… will only have the following changes:

Publish-ProvMasterVmImage -ProvisioningSchemeName "Internal Win7 Random - Windows 7 64-bit_Datacenter_01" -MasterImageVM "XDHyp:\HostingUnits\Datacenter_01\W7_PRO_SP1_x64_v1.vm\Snappy Snap.snapshot\Snapperoo.snapshot"

The snapshot information can easily be obtained via the vSphere Client.

I really wished there was a way to set the Rollout Strategy with this cmdlet but maybe there’s a way to do it that I don’t yet know of so please feel free to share this with me in the comments.  Hope this post has been helpful.