When you configure a XenDesktop environment, the primary configuration you are going to make is to create new desktop groups. Desktop Groups define the virtual desktops that you want to make available to users, who can access them, how they are assigned to users, and how many are kept active at any given time. Whenever I’m working within the Delivery Services Console, I spend most of my time looking at the desktop groups and the virtual machines contained within them.

So when you look at automating a XenDesktop environment, being able to automate the creation of a desktop group is typically one of the first things you want to try to do. This article will provide a sample PowerShell script on how to create a new VM-based desktop group for a XenDesktop farm. A VM-based desktop group just means that the virtual desktops (VDAs) are hosted on a hypervisor such as XenServer or Hyper-V. The alternative is a PC-based desktop group where the virtual desktops are hosted on PC appliances.

This is the third blog in a series on how to use the XenDesktop 4 PowerShell SDK. In the first blog, I provided info on how to set up your XenDesktop PowerShell environment so that you could run these scripts. If you haven’t done that yet, please visit that article first. In the second blog, I discussed the XenDesktop PowerShell objects and how you can use them for retrieving the XenDesktop farm properties and other configurations. For a complete list of topics that I will be covering in this blog series, see the bottom of this article.

Environment Overview and Script Goals
Before we look at the PowerShell script, it’ll be good to get some information about my environment so you can understand what the script will be doing.

I’m using XenServer as my host infrastructure. My XenServer IP address is All the virtual machines for my XenDesktop environment are hosted on this XenServer. The VM details are as follows:

Role OS VM Name AD Machine Name IP Address
Domain Controller Windows Server 2003 W2K3_DC1 dc1
Desktop Delivery Controller Windows Server 2003 W2K3_XD4_DDC ddc
Virtual Desktops Windows XP (all) WINXP_XD4_VDA1

The virtual desktop machines already have the virtual desktop agent software installed, they just need to be added into a desktop group on the Desktop Deliver Controller. I want to create a new desktop group with this configuration:

Setting Value
Desktop Group Name Windows XP
Desktop Group Description New desktop group created by PowerShell
Assignment Type Pooled
Assigned Users/Groups CITRIXLAB\Domain Users
Assigned virtual desktops WINXP_XD4_VDA1
Peak Idle Count 5 virtual desktops
Business Hours Idle Count 3 virtual desktops
Out of hours Idle Count 1 virtual desktop
Peak Hours Start 8am
Peak Hours End 10am
Business Hours End 8pm
Time Zone Central Standard Time
Business Days Every day of the week, including Saturday and Sunday

PowerShell script for creating a new desktop group
The sample script below demonstrates how to create a new VM-based desktop group within XenDesktop using the configurations I outlined in the previous section.

#Create a <span class="code-keyword">new</span> VM-based desktop group

#Add the XenDesktop snap-in to the current Powershell session
Add-PSSnapin <span class="code-quote">"XdCommands"</span>

#Set up variables <span class="code-keyword">for</span> the script
$strXenServerAddress = <span class="code-quote">""</span>
$strXenServerUsername = <span class="code-quote">"root"</span>
$strXenServerPassword = <span class="code-quote">"Password1"</span>
$strDDCAddress = <span class="code-quote">""</span>
$strDesktopGroupName = <span class="code-quote">"Windows XP"</span>
$strDesktopGroupDescription = <span class="code-quote">"New desktop group created by PowerShell"</span>
$strDesktopGroupAssignmentType = <span class="code-quote">"Pooled"</span>
$strADGroup = <span class="code-quote">"CITRIXLAB\Domain Users"</span>
$machinenames = <span class="code-quote">"WINXP_XD4_VDA1"</span>, <span class="code-quote">"WINXP_XD4_VDA2"</span>, <span class="code-quote">"WINXP_XD4_VDA3"</span>, <span class="code-quote">"WINXP_XD4_VDA4"</span>, <span class="code-quote">"WINXP_XD4_VDA5"</span>

#Connect to the hypervisor (XenServer) hosting the XenDesktop environment using the supplied username/password
$securepwd = ConvertTo-SecureString $strXenServerPassword -AsPlainText -Force
$xenserver = New-XdHostingServer -Address $strXenServerAddress -User $strXenServerUsername -Password $securepwd -AdminAddress $strDDCAddress

#Get the VMs (virtual desktops) that we want to add to the desktop group
$vms = Get-XdHostedMachine -HostingServer $xenserver | where  { $machinenames -contains $_.HostingName }

#Get the AD group that we want to add to the desktop group
$xdusers = New-XdUser -Name $strADGroup -Group

#Define the hosting infrastructure and idle pool settings <span class="code-keyword">for</span> the desktop group
$hgs = New-XdGroupHostingSettings -HostingServer $xenserver
$hgs.OutOfHoursIdleCount = 1
$hgs.BusinessHoursIdleCount = 3
$hgs.PeakHoursIdleCount = 5
$hgs.PeakHoursStart = [Timespan] <span class="code-quote">"8:00:00"</span>
$hgs.PeakHoursEnd = [Timespan] <span class="code-quote">"10:00:00"</span>
$hgs.BusinessHoursEnd = [Timespan] <span class="code-quote">"20:00:00"</span>
$hgs.IdleTimesTimeZone = [<span class="code-object">System</span>.TimeZoneInfo]::GetSystemTimeZones() | where { $_.StandardName -like <span class="code-quote">"Central Standard Time"</span> }
$hgs.BusinessDays.Add(<span class="code-quote">"Saturday"</span>)
$hgs.BusinessDays.Add(<span class="code-quote">"Sunday"</span>)
$hgs.TaintedMachineAction = <span class="code-quote">"DoNothing"</span> #Can also have value <span class="code-quote">"Restart"</span>

#Create the desktop group with the above settings using a <span class="code-quote">"Pooled"</span> assignment type
$xdgroup = New-XdDesktopGroup -Publish $strDesktopGroupName -Description $strDesktopGroupDescription -Desktops $vms -User $xdusers -HostingSettings $hgs -AssignmentBehavior $strDesktopGroupAssignmentType -AdminAddress $strDDCAddress

#Verify the desktop group was created (can also look in the Delivery Services Console)
echo $xdgroup

After you run the script, check out the Delivery Services Console to make sure the desktop group was added.

Also check out the idle pool settings for the desktop group to make sure those settings were applied properly:

Analyzing the PowerShell Script
The New-XdDesktopGroup cmdlet is used to create the desktop group within XenDesktop. Typically the way that you want to write a script such as this is to look at what parameters are required by New-XdDesktopGroup and then work backwards to ensure you have all the required parameters covered.

The New-XdDesktopGroup cmdlet needs the following parameters to execute. It supports more parameters than this, but this is what I’m supplying in the script above.

Parameter Description
-Publish Name to assign to the desktop group
-Description Description of the desktop group
-Desktops The virtual desktops to assign to this desktop group
-User The Active Directory users/groups to assign to this desktop group
-HostingSettings The idle pool settings to use for this desktop group
-AssignmentBehavior How desktops within the group are assigned to users (e.g. “Pooled”)
-AdminAddress The address of the Desktop Delivery Controller to connect to for making this update

The top part of the PowerShell script is used gather and store the above items into variables so we can pass them into the New-XdDesktopGroup cmdlet. Several of these parameters are just strings and are pretty easy to figure out (-Publish, -Description, -AssignmentBehavior, -AdminAddress). The other parameters are actually looking for particular XenDesktop objects (-Desktops, -User, -HostingSettings).

The -Desktops parameter is looking for a XdHostedMachine object. We are using the Get-XdHostedMachine cmdlet to create that object. The -User parameter is looking for a XdUser object. We are using the New-XdUser cmdlet to create that object. The -HostingSettings parameter is looking for a XdGroupHostingSettings object. We are using the New-XdGroupHostingSettings cmdlet to create that object.

In order to use the Get-XdHostedMachine cmdlet, this cmdlet requires a connection to the XenServer itself. The New-XdHostingServer cmdlet is used to create a connection to XenServer using a supplied XenServer username and password. This “xenserver” object is then passed into the Get-XdHostedMachine cmdlet.

This article explains how to automate the creation of a new desktop group in XenDesktop via PowerShell. As you test this script, I would recommend executing the statements line-by-line to understand what the script is doing. Don’t forget to echo out the value of the variables to see what data they contain. When you create the XenDesktop objects using New-XdUser, Get-XdHostedMachine, New-XdHostingServer, etc., I recommend using get-member to undestand all of the properties and methods that object supports. For example:

#Get the AD group that we want to add to the desktop group
$xdusers = New-XdUser -Name $strADGroup -Group

#List all the properties and methods supported by the XdUser object
$xdusers | get-member

If you have any questions or comments about this script, or if you found new ways of using it, feel free to post a comment below. In the next article, I will discuss how to enable and disable a desktop group via PowerShell. Stay tuned!

Upcoming TechTalk
I will be leading a TechTalk with Mike Bogobowicz on Essentials for using Windows PowerShell with XenApp and XenDesktop on Tuesday, August 24 from 2pm to 3pm EST. If you interesting in learning more about these SDKs first hand and want to see the demos in action, you can sign up here. We hope to see you there!

Blogs in this series

Ed York – Senior Architect – Worldwide Technical Readiness
Ask-the-Architect Site: http://community.citrix.com/p/product-automation#home
Follow Me on twitter: http://twitter.com/citrixedy