Creating an MCS-based XenDesktop Machine Catalog with PowerShell

Driving XenDesktop with PowerShell is a challenge to say the least. While documentation for the XenDesktop PowerShell modules is OK and Citrix Studio outputs PowerShell code after you’ve completed a task in the console, there’s still plenty of work to get that code into something usable.

As part of an ongoing series of articles themed around automating virtual desktop deployment, I’ve written some PowerShell code to automate the creation of an non-persistent, MCS-based Machine Catalog based on a specific Windows image, that we’ve already automated with a solution such as MDT.

Don’t expect to copy and paste the PowerShell output in Citrix Studio and have a complete script. The code is missing a number of lines that link tasks together. I found this article on the Citrix Blogs quite useful - Using PowerShell to Create a Catalog of Machine Creations Services Machines; however I’ve taken my script a few steps further.

Linking the Code to the UI

While the Create Machine Catalog wizard doesn’t expose everything that goes on behind the scenes when a machine catalog is created, I think it’s still worth showing how specific functions relate to choices that the administrator makes in the wizard.

The screenshots below show just a snippet of the functions required to automate the catalog creation using PowerShell. These walkthrough the same environment that the full code listing at the end of this article is creating. See the image captions for example code that applies to each step.

New-BrokerCataog is used to create the machine catalog and set a number of properties. You’ll see New-BrokerCatalog across a number of these screen shots. First up is setting the broker type – in this instance, I’m deploying a Windows 8 image, so need to choose ‘Windows Desktop OS’:

Selecting the Machine Catalog type - New-BrokerCatalog SessionSupport SingleSession

Selecting the Machine Catalog type – New-BrokerCatalog -SessionSupport SingleSession

Because were using MCS, I’m going to specify that I’m using virtual machines and choose the storage on which to deploy those VMs and use the ProvisioningType parameter on New-BrokerCatalog to specify MCS. This is done in PowerShell via a number of commands – see around line 45 where we specify the hypervisor management and storage resource to use.

Selecting the provisioning type - New-BrokerCatalog -ProvisioningType $provType

Selecting the provisioning type – New-BrokerCatalog -ProvisioningType MCS

Also on the New-BrokerCatalog, we can specify that this is a set of randomly assigned desktops.

Selecting Random or Static desktops - New-BrokerCatalog -AllocationType Random

Selecting Random or Static desktops – New-BrokerCatalog -AllocationType Random

To find the image to use, I’ve obtained the path to the master image and its snapshot via the Get-ChildItem command (on the path XDHyp:\HostingUnits\<Storage Resource>) and passed that to New-ProvScheme.

Selecting the master image and snapshot to use - New-ProvScheme -ProvisioningSchemeName "Windows 8" -HostingUnitName "HV1-LocalStorage -MasterImageVM "XDHyp:\HostingUnits\HV1-LocalStorage\WIN81.vm\MasterImage.snapshot"

Selecting the master image and snapshot to use – New-ProvScheme -ProvisioningSchemeName “Windows 8″ -HostingUnitName “HV1-LocalStorage” -MasterImageVM “XDHyp:\HostingUnits\HV1-LocalStorage\WIN81.vm\MasterImage.snapshot”

Also with New-ProvScheme we can set the number of virtual CPUs and the amount of RAM to assign to each virtual desktop. To specify the number of desktops to create, we’re actually first specifying the number of AD machine accounts to create via New-AcctADAccount and then creating the same number of desktops to assign to those accounts.

Selecting the virtual machine configurations - New-ProvScheme -VMCpuCount 2 -VMMemoryMB 2048

Selecting the virtual machine configurations – New-ProvScheme -VMCpuCount 2 -VMMemoryMB 2048

New-AcctIdentityPool is used to create an identity pool that stores the machine accounts by specifying the naming convention and where the accounts will be stored.

Setting machine account names and location - New-AcctIdentityPool -Domain 'home.stealthpuppy.com' -NamingScheme 'W8-MCS-###'-NamingSchemeType Numeric -OU 'OU=MCS Pooled,OU=Workstations,DC=home,DC=stealthpuppy,DC=com'

Setting machine account names and location – New-AcctIdentityPool -Domain ‘home.stealthpuppy.com’ -NamingScheme ‘W8-MCS-###’-NamingSchemeType Numeric -OU ‘OU=MCS Pooled,OU=Workstations,DC=home,DC=stealthpuppy,DC=com’

Again we can see where New-BrokerCataog is used to specify the catalog name and description.

Setting the machine catalog name and description - New-BrokerCatalog  -Name "Windows 8 x86" -Description "Windows 8.1 x86 SP1 with Office 2013"

Setting the machine catalog name and description – New-BrokerCatalog -Name “Windows 8 x86″ -Description “Windows 8.1 x86 SP1 with Office 2013″

There’s plenty that the wizard does to hide the complexity of setting up a catalog from the administrator. If you attempt the same via PowerShell, what goes on under the hood is laid bare.

The Code

Below is the full code listing with comments inline that should provide some detail on the process the code follows. At this point the code provides some error checking for the most important steps. There are still some additional steps and error checking that could be integrated:

  • This code should find the last snapshot of the target master image; it would be simple enough to specify a particular snapshot if required
  • Checking whether provisioning schemes are already available or exist before attempting to create a new provisioning scheme
  • Additional checking that some tasks have completed successfully before continuing

Comments or feedback on bugs, better ways to do things or additional steps is welcome.

Retrieving a VM’s UUID from Hyper-V

I’ve previously posted about retrieving the UUID from a virtual machine hosted on vSphere. UUIDs are useful if you want to uniquely identify a target machine for OS deployment task sequences and the like (e.g. MDT). Here’s how to obtain the UUID from a virtual machine hosted on Hyper-V.

Just like with vSphere, the UUID isn’t a property of the virtual machine that can be queried directly. We need to go via WMI to query the target virtual machine. Note that in this function, I’m using version 2 of the Root\Virtualization WMI namespace (root\virtualization\v2. This means the function as written, will only work on Windows 8 and Windows Server 2012 (and above). If you want to use this function on earlier versions of Hyper-V, remove the “\v2″ from the namespace.

As an example, here’s how to retrieve the UUIDs from a set of VMs on a target Hyper-V host named hv1:

Here’s the full function code listing. Please let me know if you find any bugs: