Carl Webster | The Accidental Citrix Admin

Documenting a Citrix XenDesktop 4 Farm with Microsoft PowerShell

March 12, 2012

A customer site I was at recently needed their XenDesktop 4 farm documented. Since I had already created PowerShell scripts to document the various versions of XenApp, I figured a XenDesktop script should be easy to create. This article and the script were written for “SR” at the customer site.

This article will focus only on XenDesktop 4. I am planning on writing articles and scripts for XenDesktop 5.x.

The prerequisites to follow along with this article are:

A computer, physical or virtual, running Microsoft Windows Server 2003, Server 2008, Server 2008 R2, or Microsoft Windows XP, Vista, or 7 for running the XenDesktop Desktop Delivery Controller SDK.
Citrix XenDesktop 4 Desktop Delivery Controller (DDC) installed with at least one Desktop Group created.

In this article, we will be installing the Citrix Delivery Controller SDK. You can install the SDK from either the XenDesktop 4 installation media or download it from citrix.com. Since I am at a customer site creating this script on a production network, I do not have access to the installation media. Therefore, I will be downloading the SDK.

My initial goal was to see if I could walk down the nodes in the Delivery Services Console (DSC) (Figure 1) and see if I could document every nook and cranny.

Note: For instructions on how to install the SDK from the XenDesktop 4 installation media, please see http://blogs.citrix.com/2010/08/11/xendesktop-4-powershell-sdk-primer-part-1-getting-started/.

Update 7-July-2021: Citrix, obviously, killed these old XD4 links.

For the SDK install, go to https://carlwebster.sharefile.com/d-s6239e1f90eb043d7a2642fbc61db997a

For the SDK Welcome, go to https://carlwebster.sharefile.com/d-s559804f9b3244ff58669263ab1e7dc06

Click Start, Run, type in C:\XD4SDK\XenDesktopControllerSDK.msi and press Enter.

Click Run (Figure 3).

Select I accept the terms in the License Agreement and click Next (Figure 5).

Click Install (Figure 7).

You now have new Start Menu items under All Programs, Citrix. Windows 7 is shown in Figure 9.

Everything is now set up for us to get started. The download page for the SDK says to get a listing of the available XenDesktop commands to enter the following command:

Get-Command -psSnapin XdCommands

Typing that line into the PowerShell session returns a list of Citrix XenDesktop PowerShell commands. A sample is shown in Figure 10.

To get a list of the Get commands, showing just the Name, where the noun starts with “Xd”, type the following in the PowerShell session (results are shown in Figure 11):

Get-Command –Noun Xd* -Verb Get | Select-Object Name

Of the eight Get-Xd* commands listed, only three are usable for documenting the Farm:

Get-XdFarm
Get-XdController
Get-XdDesktopGroup

One feature I like about the XenDesktop PowerShell commands is that you are not required to run them directly on a Controller. You can use the –AdminAddress parameter to give the name or IP address of a Controller to run the command against. Since I am developing this script on a production Farm, I am being safe and staying off the customer’s production Controllers.

Typing each of the commands into the PowerShell session gave me the results shown in Figure 12, Figure 13, and Figure 14.

Note: I am using a Formatted List (| fl) to see all the properties returned by each command.

My goal is to use the same wording as what is seen in the DSC for headings, captions, and text. In order to do that, I needed a way to format the output text. Michael B. Smith (MBS) developed a function for me to use called Line.

Function line
#function created by Michael B. Smith, Exchange MVP
#@essentialexchange on Twitter
#http://TheEssentialExchange.com

{
	Param( [int]$tabs = 0, [string]$name = ’’, [string]$value = ’’, [string]$newline = “`n”, [switch]$nonewline )

	While( $tabs –gt 0 ) { $global:output += “`t”; $tabs--; }

	If( $nonewline )
	{
		$global:output += $name + $value
	}
	Else
	{
		$global:output += $name + $value + $newline
	}
}

Another lesson MBS taught me is to check to see if each cmdlet used returned an error and how to tell the cmdlet how I wanted to proceed if there was an error. This is done by using –ErrorAction, or –EA. ErrorAction has four values (Table 1):

Table 1

Enumeration	Value	Description
SilentlyContinue	0	The Windows PowerShell runtime will continue processing without notifying the user that an action has occurred.
Stop	1	The Windows PowerShell runtime will stop processing when an action occurs.
Continue	2	The Windows PowerShell runtime will continue processing and notify the user that an action has occurred.
Inquire	3	The Windows PowerShell runtime will stop processing and ask the user how it should proceed.

For this documentation script, I always use 0. If an error occurs, I want the rest of the script to continue.

Next, I needed to know how to test to see if an action, like Get-XdFarm, succeeded or had an error. MBS said to use $? to test if the most recent action succeeded (True) or had an error (False). For example:

$farm = Get-XdFarm -EA 0
If( $? )
{
	#success
}
Else
{
	#error
}

Because this script does not have to run on a Controller, a parameter is created to allow a Controller name or IP address to be used.

Let’s get started. We will build the script node by node. Some of the lines may wrap.

The beginning of the script:

#Carl Webster, CTP and independent consultant
#webster@carlwebster.com
#@carlwebster on Twitter
#https://www.carlwebster.com
#This script written for "SR", March 9, 2012
#Thanks to Michael B. Smith, Joe Shock, Jarian Gibson and James Rankin
#for testing and fine-tuning tips

Param(
[string]$DDCAddress = ""
)

Function line
#function created by Michael B. Smith, Exchange MVP
#@essentialexchange on Twitter
#http://TheEssentialExchange.com

{
	Param( [int]$tabs = 0, [string]$name = ’’, [string]$value = ’’, [string]$newline = “`n”, [switch]$nonewline )

	While( $tabs –gt 0 ) { $global:output += “`t”; $tabs--; }

	If( $nonewline )
	{
		$global:output += $name + $value
	}
	Else
	{
		$global:output += $name + $value + $newline
	}
}

#script begins

The first node in the DSC is the Farm itself.

#get farm information
$global:output = ""

If($DDCAddress)
{
	$farm = Get-XdFarm -adminaddress $DDCAddress -EA 0
}
Else
{
	$farm = Get-XdFarm -EA 0
}

If( $? )
{
	line 0 "XenDesktop Farm Name: " $farm.Name
	line 1 "XenDesktop Edition: " -nonewline
	switch ($farm.edition)
	{
		"PLT"   {line 0 "Platinum"  }
		"STD"   {line 0 "VDI"       }
		"ADV"   {line 0 "Advanced"  }
		"ENT"   {line 0 "Enterprise"}
		default {line 0 "Farm Edition could not be determined: $($farm.edition)"}
	}

	line 1 "Base OU: " $farm.BaseOU
	line 1 "License server"
	line 2 "Name: " $farm.LicenseServerName
	line 2 "Port number: " $farm.LicenseServerPort
	line 1 "Session reliability"
	line 2 "Allow users to view sessions during broken connections: " $farm.EnableSessionReliability

	If($farm.EnableSessionReliability)
	{
		line 3 "Port number: " $farm.SessionReliabilityPort
		line 3 "Seconds to keep sessions active: " $farm.SessionReliabilityDurationSeconds
	}
} 
Else 
{
	line 0 "XenDesktop Farm information could not be retrieved"
}
write-output $global:output
$farm = $null
$global:output = $null

$global:output = ""

Sample script output:

XenDesktop Farm Name: SAMPLEXD4
        XenDesktop Edition: Platinum
        Base OU: XD4BaseOU
        License server
                Name: CTXLICENSE
                Port number: 0
        Session reliability
                Allow users to view sessions during broken connections: True
                        Port number: 2598
                        Seconds to keep sessions active: 60

Even though the license server port number is displayed as 27000 in the console, the Citrix cmdlet returns 0.

The next node in the DSC is Administrators, but Citrix does not provide a way to retrieve any information about the Administrators.

The next node is the Controllers. Even though Controllers can be in folders, Citrix does not provide a way to retrieve Folder information.

#get controller information
If($DDCAddress)
{
	$XDControllers = Get-XdController -adminaddress $DDCAddress -EA 0
}
Else
{
	$XDControllers = Get-XdController -EA 0
}

If( $? )
{
	line 0 "Desktop Delivery Controllers:"
	ForEach($XDController in $XDControllers)
	{
		line 1 "Controller: " $XDController.Name
		line 1 "Version: " $XDController.Version
		line 1 "Zone Election Preference: " $XDController.ZoneElectionPreference
		line 1 "License Server"
		If($XDController.UseFarmLicenseServerSettings)
		{
			line 2 "Using Farm Setting"
		}
		Else
		{
			Line 2 "License server"
			line 3 "Name: " $XDController.LicenseServerName
			line 3 "Port number: " $XDController.LicenseServerPort
		}
		line 1 ""
	}
} 
Else 
{
	line 0 "Desktop Delivery Controller information could not be retrieved"
}
write-output $global:output
$XDControllers = $null
$global:output = $null

Sample script output:

Desktop Delivery Controllers:
        Controller: DDC1
        Version: 4.0
        Zone Election Preference: Member
        License Server
                Using Farm Setting

        Controller: DDC2
        Version: 4.0
        Zone Election Preference: Member
        License Server
                Using Farm Setting

The last node is Desktop Groups. There are different options available depending on if the Desktop Group is Pooled or Assigned. Instead, I returned the AD Computer Account name as shown in the console, and the cmdlet returns the Machine SID. Also, not every user account returned a name, but the User SID was always returned. MBS showed me how to convert a Machine or User Account SID to the Machine or User Name.

$objSID = New-Object System.Security.Principal.SecurityIdentifier ($Desktop.MachineSid.Value)
$objComputer = $objSID.Translate([System.Security.Principal.NTAccount])
"AD Computer Account: " $objComputer.Value

And

$objSID = New-Object System.Security.Principal.SecurityIdentifier($Desktop.AssignedUserSid.Value)
$objUser = $objSID.Translate([System.Security.Principal.NTAccount])
“Assigned User: “ $objUser.Value

#get desktop group information
$global:output = ""

If($DDCAddress)
{
	$XDGroups = Get-XdDesktopGroup -adminaddress $DDCAddress -EA 0
}
Else
{
	$XDGroups = Get-XdDesktopGroup -EA 0
}

If( $? )
{
	line 0 "Desktop Groups:"
	ForEach($XDGroup in $XDGroups)
	{
		line 1 "Basic"
		line 2 "Desktop Group Name"
		line 3 "Display name: " $XDGroup.Name
		line 3 "Description: " $XDGroup.Description
		line 3 "Desktop Group name: " $XDGroup.InternalName
		line 3 "Disable desktop group: " -nonewline
		If($XDGroup.Enabled)
		{
			line 0 "group is enabled"
		}
		Else
		{
			line 0 "group is disabled"
		}

		line 2 "Assignment Type"
		line 3 "Assignment Behavior: " $XDGroup.AssignmentBehavior

		If($XDGroup.IsHosted)
		{
			line 2 "Hosting infrastructure: " $XDGroup.HostingSettings.HostingServer
		}


		line 2 "Users"
		line 3 "Configured users:"
		ForEach($User in $XDGroup.Users)
		{
			line 4 $User
			#line 4 "SID: " $User.Sid
			line 4 "Group or User: " -nonewline
			If($User.IsSecurityGroup)
			{
				line 0 "Group"
			}
			Else
			{
				line 0 "User"
			}
		}
		line 2 "Virtual Desktops"
		line 3 "Virtual desktops:"
		ForEach($Desktop in $XDGroup.Desktops)
		{
			line 4 "Folder: " $XDGroup.Folder
			line 4 "Virtual Machine: " $Desktop
			$objSID = New-Object System.Security.Principal.SecurityIdentifier ($Desktop.MachineSid.Value)
			$objComputer = $objSID.Translate([System.Security.Principal.NTAccount])
			line 4 "AD Computer Account: " $objComputer.Value
			line 4 "Desktop State: " $Desktop.State
			line 4 "Assigned User: " -nonewline
			If($Desktop.AssignUserName)
			{
				line 0 $Desktop.AssignUserName
			}
			ElseIf($Desktop.AssignedUserSid)
			{
				$objSID = New-Object System.Security.Principal.SecurityIdentifier ($Desktop.AssignedUserSid.Value)
				$objUser = $objSID.Translate([System.Security.Principal.NTAccount])
				line 0 $objUser.Value
			}
			Else
			{
				line 0 ""
			}
			line 4 "Maintenance Mode: " $Desktop.MaintenanceMode
			line 4 "Machine State: " $Desktop.PowerState
			line 4 "Controller: " $Desktop.Controller
			line 4 "Agent Version: " $Desktop.AgentVersion
			line 1 ""
		}
		line 1 "Advanced"
		line 2 "Access Control"

		$test = $XDGroup.AccessGatewayControl.ToString()
		$test1 = $test.replace(", ","`n`t`t")

		line 3 $test1
		line 2 "Access Gateway Conditions: "
		ForEach($Condition in $XDGroup.AccessGatewayConditions)
		{
			line 3 $Condition
		}
		line 2 "Client Options"
		line 3 "Appearance"
		line 4 "Colors: " -nonewline
		switch ($XDGroup.DefaultColorDepth)
		{
			"FourBit"       {line 0 "16 colors"          }
			"EightBit"      {line 0 "256 colors"         }
			"SixteenBit"    {line 0 "High color (16-bit)"}
			"TwentyFourBit" {line 0 "True color (24-bit)"}
			default         {line 0 "Color depth could not be determined: $($XDGroup.DefaultColorDepth)"}

		}
		line 3 "Connection"
		line 4 "Encryption: " -nonewline
		switch ($XDGroup.DefaultEncryptionLevel)
		{
			"Basic"               {line 0 "Basic"                    }
			"LogOnRC5Using128Bit" {line 0 "128-Bit Login Only (RC-5)"}
			"RC5Using40Bit"       {line 0 "40-Bit (RC-5)"            }
			"RC5Using56Bit"       {line 0 "56-Bit (RC-5)"            }
			"RC5Using128Bit"      {line 0 "128-Bit (RC-5)"           }
			default               {line 0 "Encryption level could not be determined: $($XDGroup.DefaultEncryptionLevel)"}

		}
		line 3 "Connection Protocols: "
		ForEach($Protocol in $XDGroup.Protocols)
		{
			line 4 "Name: " $Protocol.Protocol
			line 4 "Enabled: " $Protocol.Enabled
		}

		#only show the next section if the Desktop Group is Pooled
		If($XDGroup.AssignmentBehavior -eq "Pooled")
		{
			line 2 "Idle Pool Settings"
			line 3 "Business Hours"
			line 4 "Business days "
			ForEach($Day in $XDGroup.HostingSettings.BusinessDays)
			{
				line 5 $Day
			}
			line 4 "Time zone "  $XDGroup.HostingSettings.IdleTimesTimeZone
			IF($XDGroup.HostingSettings.PeakHoursStart)
			{
				line 4 "Day start "  $XDGroup.HostingSettings.PeakHoursStart.ToString()
			}
			If($XDGroup.HostingSettings.PeakHoursEnd)
			{
				line 4 "Peak end "  $XDGroup.HostingSettings.PeakHoursEnd.ToString()
			}
			If($XDGroup.HostingSettings.BusinessHoursEnd)
			{
				line 4 "Day end " $XDGroup.HostingSettings.BusinessHoursEnd.ToString()
			}
			line 3 "Idle Desktop Count"
			line 2 "Business hours " $XDGroup.HostingSettings.BusinessHoursIdleCount
			line 2 "Peak time " $XDGroup.HostingSettings.PeakHoursIdleCount
			line 2 "Out of hours " $XDGroup.HostingSettings.OutOfHoursIdleCount
		}
		
		# I can't find these settings in the console
		line 1 "Other settings"
		line 2 "Allow User Desktop Restart: " $XDGroup.AllowUserDesktopRestart
		line 2 "Tainted Machine Action: " $XDGroup.HostingSettings.TaintedMachineAction
		line 3 "Actions: "
		ForEach($Action in  $XDGroup.HostingSettings.Actions)
		{
			line 4 "Action point: " $Action.ActionPoint
			line 4 "Action: " $Action.Action
			line 4 "Delay: " $Action.Delay
			line 4 ""
		}


		line 1 ""
	}
} 
Else 
{
	line 0 "Desktop Group information could not be retrieved"
}
write-output $global:output
$XDGroups = $null
$test = $null
$test1 = $null
$global:output = $null

Sample script output:

Desktop Groups:
Basic
		Desktop Group Name
			Display name: WebstersLab
			Description: Used in Webster’s Lab for writing purposes
			Desktop Group name: WebstersLab
			Disable desktop group: group is enabled
		Assignment Type
			Assignment Behavior: Pooled
		Hosting infrastructure: http://msvirtualcenter.carls.com/sdk
		Users
			Configured users:
				CARLS\TS_XD_Lab
				Group or User: Group
				CARLS\TS_XD_Lab_Admin
				Group or User: Group
		Virtual Desktops
			Virtual desktops:
				Folder: \
				Virtual Machine: CARLS\COMPUTER01$
				AD Computer Account: CARLS\COMPUTER01$
				Desktop State: Available
				Assigned User: 
				Maintenance Mode: False
				Machine State: On
				Controller: DDC1
				Agent Version: 4.0.4522
	
				Folder: \
				Virtual Machine: CARLS\COMPUTER06$
				AD Computer Account: CARLS\COMPUTER06$
				Desktop State: NotRegistered
				Assigned User: 
				Maintenance Mode: False
				Machine State: On
				Controller: 
				Agent Version: 

	Advanced
		Access Control
			AllowGatewayNoConditionsDefined
		AllowGatewayAnyCondition
		Access Gateway Conditions: 
		Client Options
			Appearance
				Colors: High color (16-bit)
			Connection
				Encryption: Basic
			Connection Protocols: 
				Name: ICA30
				Enabled: True
		Idle Pool Settings
			Business Hours
				Business days 
					Sunday
					Monday
					Tuesday
					Wednesday
					Thursday
					Friday
					Saturday
				Time zone (UTC-05:00) Eastern Time (US &amp;amp; Canada)
				Day start 01:00:00
				Peak end 20:30:00
				Day end 23:30:00
			Idle Desktop Count
		Business hours 7
		Peak time 7
		Out of hours 7
	Other settings
		Allow User Desktop Restart: False
		Tainted Machine Action: Restart
			Actions: 
				Action point: Disconnect
				Action: DoNothing
				Delay: 300
				
				Action point: LogOff
				Action: Shutdown
				Delay: 420

How to use this script?

I saved the script as XD4_Inventory.ps1 in the Z:\ folder. From the PowerShell prompt, change to the Z:\ folder or the folder where you saved the script. From the PowerShell prompt, type in:

.\XD4_Inventory.ps1 |out-file Z:\XD4Farm.txt and press Enter, or

.\XD4_Inventory.ps1 DDCName|out-file Z:\XD4Farm.txt and press Enter, or

.\XD4_Inventory.ps1 DDCIPAddress|out-file Z:\XD4Farm.txt and press Enter.

Open XD4Farm.txt in either WordPad or Microsoft Word (Figure 15).

You can always find the most current script by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

Thanks

Webster

powershell, xendesktop, xendesktop 4

About Carl Webster

Webster is a Sr. Solutions Architect for Choice Solutions, LLC and specializes in Citrix, Active Directory and Technical Documentation. Webster has been working with Citrix products for many years starting with Multi-User OS/2 in 1990.

View all posts by Carl Webster →

2 Responses to “Documenting a Citrix XenDesktop 4 Farm with Microsoft PowerShell”

Yvan Scigala Says:
July 25, 2012 at 8:45 am
Hi Carl,

Thanks for your articles, always brilliant and detailled ! They really help us, we, poor quarks lost in the Citrix Known Universe 😉

Do you know when an XD56 version of the documentation scripts will be released ?

May the force be with you

Cheers

e-Van

Reply
- Carl Webster Says:
  July 26, 2012 at 7:25 am
  as soon as I can get access to a XD5.6 environment I can write the script. None of my customers use XD and I am too busy with paid work to have the time to build up a XD lab.
  
  Thanks
  
  Webster
  
  Reply