Using Windows PowerShell to manage Citrix XenDesktop 5

When Citrix created XenDesktop 5, the company added support for PowerShell in a big way. In fact, the XenDesktop 5 SDK includes well over 100 PowerShell cmdlets to help with countless administration tasks.

Let's take a look at a few cmdlets that are particularly helpful for managing your virtual desktop environment, including disconnecting virtual desktop sessions, adding administrators and creating virtual machine (VM) snapshots.

Creating a virtual machine snapshot
There are countless uses for VM snapshots, and in XenDesktop 5, it is possible to create snapshots using PowerShell. This proves handy if you are scripting an operation and want to create snapshots as the script runs. You can create snapshots using the New-HypVMSnapshot cmdlet. Here is the full command syntax:

New-HypVMSnapshot [-LiteralPath] <String> [-SnapshotName] <String> [-AdminAddress <String>] [[-SnapshotDescription] <String>] [<CommonParameters>]

Although this cmdlet looks intimidating, it is relatively easy to use. Here is an example of a command that creates a snapshot of a virtual machine called MyVM within a hypervisor called MyHV:

New-HypVMSnapshot -LiteralPath XDHyp:\Connections\MyHV\MyVm.vm -SnapshotName "New snapshot" -SnapshotDescription "Example snapshot"           XDHyp:\Connections\MyHV\MyVm.vm\New

Getting a list of administrator accounts
Sometimes it's helpful to retrieve a list of the administrator accounts that are configured for the host service. This can be accomplished using the Get-HypAdministrator cmdlet/. Like the previous cmdlet that I showed you, this cmdlet has a number of useful optional parameters. The full syntax is:

Get-HypAdministrator [-AccountSid <String>] [-ReadOnly] [-ReturnTotalRecordCount] [-MaxRecordCount <Int32>] [-Skip <Int32>] [-SortBy <String>] [-Filter <String>] [-AdminAddress <String>] [<CommonParameters>]

These parameters are also used to filter the list of administrators. For example, if you only want to see the administrators who have Read Only permission for the host service, you can use the Read Only parameter. However, if you are simply looking for a full list of the administrator accounts for the host service, you can use the Get-HypAdministrator cmdlet by itself without having to specify any parameters.

Retrieving the task history
You may also want to view the task history for the host service. This can be accomplished by using the Get-HypTask cmdlet. The cmdlet's full syntax is:

Get-HypTask [[-TaskId] <Guid>] [-Type <JobType>] [-Active <Boolean>] [-ReturnTotalRecordCount] [-MaxRecordCount <Int32>] [-Skip <Int32>] [-SortBy <String>] [-Filter <String>] [-AdminAddress <String>] [<CommonParameters>]

This cmdlet is similar to the previous one in that all of the parameters are optional. If you want to view the full task history, you can simply enter the Get-HypTask cmdlet by itself without any parameters. The parameters are used to filter the output or to cause additional information to be returned. For example, appending the ReturnTotalRecordCount parameter causes the cmdlet to display the total number of records that were returned.

Adding a configuration administrator
Another task that you can accomplish through PowerShell is adding an Active Directory user or group to the list of configuration administrators. For this, use the New-ConfigAdministrator cmdlet. The full syntax for this PowerShell cmdlet is as follows:

New-ConfigAdministrator [-Account] <String> [-ReadOnly] [-AdminAddress <String>] [<CommonParameters>]

Of the parameters that are listed, the only one that is required is the Account parameter, which must be followed by the name of your domain and the name of the user or group you want to give access to. It's also good to know that the Read Only parameter can be appended as a way of making the user or group a Read Only configuration administrator. Here is an example of how the cmdlet that assigns administrator rights to a user named User1 in a domain named Lab:

New-ConfigAdministrator –Account Lab\User1

Disconnecting a session
Every once in a while, you might have to disconnect a session that's in an active state. You can accomplish this using the Disconnect-BrokerSession cmdlet. The syntax for this cmdlet is:

Disconnect-BrokerSession [-InputObject] <Session[]> [-AdminAddress <String>] [<CommonParameters>]

The only required parameter is the InputObject, which must be followed by a numerical value. However, it is usually easier to use piped input instead of manually specifying an Input Object. For example, if you want to disconnect a user named User1 within the lab domain you can do so by entering this string of piped cmdlets (notice that the InputObject is not required, even though it is technically a required parameter):

Get-BrokerSession –UserName Lab\User1 | Disconnect-BrokerSession

These are just a few of the many PowerShell cmdlets that are available for XenDesktop 5. If you aren't comfortable with PowerShell scripting, there is help.

First, the Citrix Desktop Studio (the GUI for XenDesktop) shows you the PowerShell equivalent to many of the operations that you perform in the GUI. This means that when you perform a management task, you can sometimes see how to do the exact same thing with PowerShell.

Citrix also provides a command reference for all of the XenDesktop PowerShell cmdlets. You can find this reference on Citrix's support page.

Read more from Brien M. Posey

ABOUT THE AUTHOR:
Brien M. Posey, MCSE, is a Microsoft Most Valuable Professional for his work with Windows 2000 Server and IIS. He has served as CIO for a nationwide chain of hospitals and was once in charge of IT security for Fort Knox. As a freelance technical writer, he has written for Microsoft, TechTarget, CNET, ZDNet, MSD2D, Relevant Technologies and other technology companies.

Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.