Troubleshooting a XenDesktop Environment Using the PowerShell SDK

Shaun Wendland, Senior Escalation Engineer

© 2013 Citrix© 2013 Citrix

Roadmap for the session

• The PowerShell SDK – what is it and how can I use it?

• Cmdlet usage and scripting fundamentals

• Advanced troubleshooting/configuring sites using scripts

• Citrix tools using the PowerShell SDK

• Resources discussed, Q&A

© 2013 Citrix2

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

© 2013 Citrix© 2013 Citrix4

• 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:

© 2013 Citrix© 2013 Citrix

Windows PowerShell

Windows PowerShell is Microsoft’s task automation framework

• Replacement for the command prompt

• Releases:

v1.0 v3.0v2.0

5

© 2013 Citrix© 2013 Citrix

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

6

© 2013 Citrix© 2013 Citrix

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

7

© 2013 Citrix© 2013 Citrix

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”

8

© 2013 Citrix© 2013 Citrix

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-

9

XenDesktop ScriptingCommon PowerShell SDK cmdlets and scripts

© 2013 Citrix© 2013 Citrix

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!

11

© 2013 Citrix© 2013 Citrix

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.

12

© 2013 Citrix© 2013 Citrix

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

13

© 2013 Citrix© 2013 Citrix

XenDesktop CmdletsCommon Desktop Cmdlets

DesktopDesktop Delivery

Controller

14

© 2013 Citrix© 2013 Citrix

Common Desktop Cmdlets

• Get-BrokerDesktop

• Get-BrokerDesktopGroup / Set-BrokerDesktopGroup

Desktop

15

© 2013 Citrix© 2013 Citrix

Common Controller Cmdlets

• Get-ServiceServiceStatus

• Get-ConfigRegisteredServiceInstance | Test-ConfigServiceInstanceAvailability

• Get-BrokerSite / Set-BrokerSite

AD Identity ServiceBroker Service

Configuration ServiceHost Service

Machine Creation ServiceMachine Identity ServiceDesktop Delivery

Controller

– Get-ConfigServiceStatus

– Get-AcctServiceStatus

– Get-HypServiceStatus– Get-ProvServiceStatus– Get-PvsVmServiceStatus

– Get-BrokerServiceStatus– Instances3

– Instance1

– Instances2

– Instances3

– Instance1

– Instances2

16

Advanced XenDesktop Troubleshooting / ConfiguringUsing PowerShell SDK cmdlets to troubleshoot complex issues and automate tasks

© 2013 Citrix© 2013 Citrix

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

18

© 2013 Citrix© 2013 Citrix

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

19

© 2013 Citrix© 2013 Citrix

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

20

© 2013 Citrix© 2013 Citrix

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 or user groupᵒ New-BrokerUser

• Create an Entitlement Policy Rule to grant the users accessᵒ New-BrokerEntitlementPolicyRule

Desktops

Entitlement Policy Rule

Access Policy Rule

Power Time SchemeDesktop Group

21

© 2013 Citrix© 2013 Citrix

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

22

© 2013 Citrix© 2013 Citrix

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

23

© 2013 Citrix© 2013 Citrix

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

24

© 2013 Citrix© 2013 Citrix

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

25

© 2013 Citrix© 2013 Citrix

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

26

XenDesktopSite Checker & WorkerDiagCitrix tools that leverage the PowerShell SDK

© 2013 Citrix© 2013 Citrix

Site Checker

• 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

XenDesktop Diagnostic Tool

28

© 2013 Citrix© 2013 Citrix

Site Checker

• 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

XenDesktop Diagnostic Tool

29

© 2013 Citrix© 2013 Citrix

WorkerDiagExtension 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

30

Wrap-upTroubleshooting a XenDesktop Environment Using the PowerShell SDK

© 2013 Citrix© 2013 Citrix

Resources Discussed

• ShareFile Download for the Presentation Example Scripts• https://citrix.sharefile.com/d/sf33d6a504d747f0b

• XenDesktop PowerShell SDK Help • http://support.citrix.com/CTX127254

• XenDesktop Site Checker• http://support.citrix.com/article/CTX133767

• XenDesktop WorkerDiag• http://blogs.citrix.com/2012/11/23/xendesktop-workerdiag

• Microsoft PowerShell Script Center• http://technet.microsoft.com/en-us/scriptcenter/powershell.aspx

• PowerShell v2.0 Download• http://support.microsoft.com/kb/968929

• PowerShell v3.0 Download• http://www.microsoft.com/en-us/download/details.aspx?id=34595

32

Q&ATroubleshooting a XenDesktop Environment Using the PowerShell SDK

© 2013 Citrix© 2013 Citrix

Next Webinar: October• Title: Using NetScaler Insight to Troubleshoot network and server performance

issues

• Description: During this session we will cover NetScaler Insight, which gives you visibility across your network AND allows you to see the end user experience. In this session, Ronan will install and configure Insight, and demonstrate how to use it to drill down and pinpoint network or performance issues.

• When: Oct 31st

• Registration Now!

Work better. Live better.Work better. Live better.