1. Troubleshooting a XenDesktop Environment Using the PowerShell SDK
SUM406
Shaun Wendland, Senior Escalation Engineer
May 21, 2013

2. Roadmap for the session
The PowerShell SDK – what is it and how can I use it?
Cmdlet usage and scripting fundamentals
Advanced configuring/troubleshooting sites using scripts
Citrix tools using the PowerShell SDK
Resources discussed, Q&A
© 2013 Citrix

3. What is the PowerShell SDK?
Working with the XenDesktop PowerShell SDK

4. Powered By: PowerShell SDK Drives .NET interactions for:
Desktop Studio
Administrator Actions
Installed by default
Required for advanced configurations
Automates common tasks
Provides a foundation for troubleshooting issues
Powered By:
PowerShell SDK:
- the “engine” underneath the hood of Desktop Studio
- administrative changes are performed by the SDK interacting with the Desktop Delivery Controller services

5. Windows PowerShell
Windows PowerShell is Microsoft’s task automation framework
Replacement for the command prompt
Releases:
v1.0
v2.0
v3.0
- Subsequent releases as part of the contemporary Windows OS releases
- The first release was in 2006 for installation on XP/2003
PowerShell releases:

6. Windows PowerShell
Windows PowerShell is Microsoft’s task automation framework
Extensible snap-in architecture provides a .NET “bridge” to virtually any aspect of a Windows machine
Snap-Ins consist of cmdlets, and provide a common scripting environment for both administrators and applications
Cmdlets represent instances of .NET Framework classes; they are not stand- alone executables
Each cmdlet is designed to perform a specific task or set of tasks.
Execution of a cmdlet is handled by the PowerShell runtime.

7. The XenDesktop PowerShell SDK at a Glance
7 Snap-Ins with nearly 300 cmdlets in the XenDesktop 5.6 PowerShell SDK
XenDesktop PowerShell cmdlets perform an action with the XenDesktop environment
Two “types” of cmdlets – configuring and polling
Most cmdlets return a Microsoft .NET Framework object
Parameters allow filtered data to be returned
Cmdlets can be executed from a remote PowerShell session with the SDK installed
Actual cmdlet count: 299
Example configuration actions – adding, removing, renaming, setting properties
Objects returned by cmdlets can be echoed to the display or passed to the next command in the pipeline.

8. Working with the XenDesktop PowerShell SDK
The XenDesktop PowerShell SDK is split into separate snap-ins for each service on a Desktop Delivery Controller
Installable on any Windows computer that supports PowerShell v2.0
Separate installers for each snap-in
Located on XenDesktop install disc
\[x86/x64]\Citrix Desktop Delivery Controller
Citrix.Common.Commands
6 x “PowerShellSnapIn”

9. Working with the XenDesktop PowerShell SDK
Cmdlets follow the standard “Verb-Item” syntax
Get-BrokerSite – Gets the Broker Site
Get-BrokerDesktop – Gets a Broker Desktop
Each cmdlet has extensive help text with syntax examples
Get-Help Get-BrokerSite -Full
Use Add-PSSnapin to load the snap-in
Add-PSSnapin Citrix.Broker.Admin.V1
Add-PSSnapin Citrix.Broker*
Add-PSSnapin Citrix.*
Alias: asnp
Executing remotely
Parameter -AdminAddress $ddcAddress
‘ddc01.domain.com:80’
Get- Rename-
Set- Update-
Add- Reset-
Remove-
Examples:
- Get-BrokerSite – returns a .NET object containing all the top-level information about a site.
- Get-BrokerDesktop – returns the details for every desktop in the site when used without parameters.
If -AdminAddress is not specified, the cmdlet attempts to execute the command locally.

10. XenDesktop Scripting
Common PowerShell SDK cmdlets and scripts

11. Scripting Essentials Integrated Scripting Environments (ISE)
Script Editor
Multi-line editing
Syntax coloring
Tab completion
Variables and Console panes
Live Debugging
Breakpoints and step-in/out
Intelli-sense!

12. Intelli-sense Provides context-specific assistance that:
Speeds up the process of coding by reducing typo's and other common syntax errors
Uses auto-completion popups, populated by querying parameters of cmdlets, as well as each parameter’s possible value.
Provides documentation and disambiguation for variable names, functions and methods.

13. Scripting Essentials Integrated Scripting Environments (ISE)
Free Script Editing Software:
Windows® PowerShell ISE
Jive PowerGUI
Idera® PowerShell+
Paid Script Editing Software:
Sapien PowerShell Studio
Sapien PrimalScript
Windows PowerShell ISE –
Jive PowerGUI –
Idera PowerShell+ –
Sapien PowerShell Studio –
Sapien PrimalScript –

14. Common Desktop Cmdlets XenDesktop Cmdlets
Desktop Delivery
Controller
The good percentage of the XenDesktop PowerShell SDK cmdlets focus on the viewing or configuring of settings for the VDA – or desktop – or for the controller.
All desktop settings are inherited from the Desktop Group, so most desktop management cmdlets are desktop group cmdlets.

15. Common Desktop Cmdlets
Get-BrokerDesktop
Get-BrokerDesktopGroup / Set-BrokerDesktopGroup
Examples of a few of the desktop object properties that are distinct to that specific desktop (and not inherited from the parent desktop group): - the last time a connection was made and error
- the last deregistration event occurred and the reason
- the last error the VDA experienced
These can be of value in helping to determine patterns in when an issue started or the error(s) associated with an issue.
“ShutdownAfterUse” Get-BrokerDesktop query
- Pulls the list of VDAs that the DDC shows as:
- PowerActionPending $false – not having a pending power action
- PowerState On – powered on
- SummaryState Available – available
- WillShutdownAfterUse $true – set to shutdown after use
- | Format-List MachineName – then sort (format) the list by machine name
The reason this helped with determining a failure executing VDA shutdowns after use:
- Desktops in a desktop group with ‘’ShutdownAfterUse” enabled have their WillShutdownAfterUse property set to true when a session is started.
- As there were results returned by this query, it verified:
1) the desktop group was correctly configured to shutdown after use
2) the DDC was correctly setting that the flag that would shutdown the VDA after the session finished
Setting the protocol priority to RDP=$true enforces all connections in that desktop group will use RDP first to connect.

16. Common Controller Cmdlets
Desktop Delivery
Controller
AD Identity Service
– Get-AcctServiceStatus
– Instances 3
Get-ServiceServiceStatus
Broker Service
– Get-BrokerServiceStatus
– Instance 1
Get-ConfigRegisteredServiceInstance | Test-ConfigServiceInstanceAvailability
Configuration Service
– Get-ConfigServiceStatus
– Instances 2
Host Service
– Get-HypServiceStatus
– Instances 3
Get-BrokerSite / Set-BrokerSite
Machine Creation Service
– Get-ProvServiceStatus
– Instance 1
Machine Identity Service
– Get-PvsVmServiceStatus
– Instances 2
If Get-(service name)ServiceStatus does not reply OK, then there’s an issue with the service.
Each of the six DDC services has at least one service instance associate with it. There are twelve total, not counting a singular licensing instance.
Enforcing secure ICA: Set the SecureIcaRequired BrokerSite property to $true

17. Advanced XenDesktop Configuring / Troubleshooting
Using PowerShell SDK cmdlets to troubleshoot complex issues and automate tasks
27:15
Let’s go through a couple of ways the PowerShell SDK can be used to configure and troubleshoot a XenDesktop site.

18. Troubleshooting service instance registrations
Broken or “Missing” service instance registrations
Clear all service instance registrations but the licensing service before re-registering
$instance | Unregister-ConfigRegisteredServiceinstance
Re-register the DDCs to the site
Get-ServiceServiceInstance -AdminAddress $ddcAddress | Register-ConfigServiceInstance
Get-ConfigRegisteredServiceInstance -AdminAddress $ddcAddress | Reset-ServiceServiceGroupMembership
Re-register Config service instances first.

19. Joining a Controller to a Site
Confirm the DDC isn’t already part of a site
Get-ItemProperty -Path 'HKLM:\SOFTWARE\Citrix\DesktopServer\DataStore\ Connections\Controller' -Name ConnectionString
Generate the T-SQL join script for each service
Get-ServiceDBSchema -DatabaseName $dbName -ScriptType Instance -ServiceGroupName $siteName
Get-(service name)DBSchema : Run once for each of the 6 DDC services (Acct, Broker, Config, Hyp, Prov, PvsVm)
$dbName is a string for your database name
$siteName is a string for the name of the site.

20. Joining a Controller to a Site
Set database connection strings for each service
Set-ServiceDBConnection -DBConnection $cs
Register service instances to the site
Get-ServiceServiceInstance | Register-ConfigServiceInstance
Get-ConfigRegisteredServiceInstance | Reset-ServiceServiceGroupMembership
Set-(service name)DBConnection: Run once for each of the 6 DDC services (Acct, Broker, Config, Hyp, Prov, PvsVm)
$cs is the connection string to the database.
Service registrations are the same as that for repairing the service instances (see Troubleshooting Service Instance Registrations slide).

21. Creating and Configuring a Desktop Group
Create the new Desktop Group and configuring its settings
New-BrokerDesktopGroup
Add the desktop machines to the Desktop Group
Add-BrokerMachinesToDesktopGroup
Create a new Broker User for each user
New-BrokerUser
Create an Entitlement Policy Rule to grant the users access
New-BrokerEntitlementPolicyRule
Desktop Group
Desktops
Entitlement Policy Rule
Access Policy Rule
Power Time Scheme

22. Creating and Configuring a Desktop Group
Create an Access Policy Rule for the Desktop Group
New-BrokerAccessPolicyRule
Create a Power Time Scheme for the Desktop Group
New-BrokerPowerTimeScheme

23. Removing Desktops & Deleting Desktop Groups
Remove desktops from the Desktop Group
Removing a single desktop from a Desktop Group
Remove-BrokerMachine -MachineName $machineSamName -DesktopGroup $desktopGroupName
Removing all desktops from a Desktop Group
Get a collection of the desktops in the Desktop Group
$desktops = Get-BrokerDesktop -DesktopGroupName $desktopGroupName
Get the machine UIDs for each desktop
$machineUids = $desktops | ForEach {$_.MachineUid}
Use the collection of machine UIDs to remove them from the Desktop Group
Remove-BrokerMachine -InputObject $machineUids -DesktopGroupName $desktopGroupName

24. Removing Desktops & Deleting Desktop Groups
Remove the Entitlement Policy Rule
Remove-BrokerEntitlementPolicyRule -Name $entitlementPolicyName
Remove the Access Policy Rule
Remove-BrokerAccessPolicyRule -Name $accessPolicyName
Remove the Power Time Scheme
Remove-BrokerPowerTimeScheme -Name $powerTimeSchemeName
Remove the Desktop Group
Remove-BrokerDesktopGroup -Name $desktopGroupName

25. Monitoring and Managing Desktops
Loop through desktops to check power, registration, and summary states of virtual desktops
Get-BrokerDesktop | Select MachineName, PowerState, RegistrationState, SummaryState
Use XenDesktop power actions to manage desktop power states
New-BrokerHostingPowerAction
Sends power actions through XenDesktop

26. Monitoring and Managing Desktops
Use WMI to check Windows vitals (services, CPU, Memory, Disk, etc.)
E.g. Get-WMIObject win32_service -ComputerName $name | Select Name, State
Use methods on WMI objects to perform actions against them
Find methods of an object
$object | Get-Member -MemberType Methods
E.g. Restarting the VDA service

27. XenDesktop Site Checker & WorkerDiag
Citrix tools that leverage the PowerShell SDK

28. Site Checker XenDesktop Diagnostic Tool
Provides the ability to perform various administrative tasks that aren’t available in Desktop Studio
Checks that all services are running on all Controllers and manages services to correct problems
Checks service instance registrations and notifies of registration issues found and can correct them using the PowerShell SDK

29. Site Checker XenDesktop Diagnostic Tool
Builds a treenode view of the site
Provides properties for the active node
All PowerShell scripts are logged in the log viewer pane
Scripts can easily be copied/pasted into a script editor for reuse

30. WorkerDiag Extension of Site Checker
Provides reporting of desktops that combines XenDesktop PowerShell SDK with Windows Management Instrumentation
Checks workers for common issues
VDA services
ListOfDDCs registry value
Last Deregistration time, Last Power Action Reason
Right-click context allows quick management of VMs
Sorting and color coding make it easy to identify problematic VMs
Allows export to CSV for reporting

31. Resources Discussed
ShareFile Download for the Presentation Example Scripts
XenDesktop PowerShell SDK Help
Microsoft PowerShell Script Center
PowerShell v2.0 Download
PowerShell v3.0 Download
XenDesktop Site Checker
XenDesktop WorkerDiag

32. Q&A
Troubleshooting a XenDesktop Environment Using the PowerShell SDK

33. Before you leave…
Conference surveys are available online at starting Friday, May 24 at 9:00 a.m. PT
Provide your feedback by 4:00 p.m. PT that day and you’ll receive a $30 Amazon.com gift card via
Download presentations starting Monday, June 3, from your My Conference Planning tool located within the My Account section