So far in the blog series I’ve mainly focused on how to automate configurations for XenDesktop desktop groups. For example, how to create new desktop groups, how to add new virtual desktops to a desktop group, and how to update the idle pool settings for a desktop group. But what does the XenDesktop PowerShell SDK let us do with the virtual desktop sessions themselves? After all, isn’t the end-goal of XenDesktop to broker virtual desktops to end-users?

This blog will cover some of the capabilities of the XenDesktop PowerShell SDK in relation to the virtual desktop sessions. In particular, I will focus on how to retrieve the total number of active virtual desktop sessions in the farm, how to retrieve attributes about the sessions such as the endpoint device details, how to send messages to the virtual desktop sessions, and how to disconnect and shutdown a virtual desktop session.

This is the eigth 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. For a complete list of topics that I will be covering in this blog series, see the bottom of this article.

1 – PowerShell script for retrieving the total number of virtual desktop sessions within the farm
The sample script below demonstrates how to get the total number of virtual desktop sessions running within the XenDesktop farm.

#*****************************************************************
#Get the number of active virtual desktop sessions <span class="code-keyword">for</span> the farm
#*****************************************************************

#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
$strDDCAddress = <span class="code-quote">"10.10.10.56"</span>

#Get all sessions <span class="code-keyword">for</span> the XenDesktop farm
$xdsession = Get-XdSession -AdminAddress $strDDCAddress -SessionDetails

#Get the number of sessions <span class="code-keyword">for</span> the farm
<span class="code-keyword">if</span> ($xdsession)   #Were any sessions returned?
{
    <span class="code-keyword">if</span> ($xdsession.count)
    {
     #There are 2+ sessions
     echo $xdsession.count
    }  <span class="code-keyword">else</span>
    {
           #There is 1 session
           write-output 1
    }
}
<span class="code-keyword">else</span>
{
    #There are no sessions
    write-output 0
}

2 – PowerShell script for retrieving the properties of a virtual desktop session
The sample script below demonstrates how to retrieve the properties/attributes of a virtual desktop session. Attributes include the Desktop Delivery Controller (DDC) that brokered the request, the virtual desktop hostname, and details about the endpoint device that made the connection.

#************************************************************
#Retrieve the virtual desktop session properties
#************************************************************

#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
$strDDCAddress = <span class="code-quote">"10.10.10.56"</span>
$strUsername = <span class="code-quote">"CITRIXLAB\User1"</span>

#Get all active sessions <span class="code-keyword">for</span> the specified user
$xdsession = Get-XdSession -user $strUsername -AdminAddress $strDDCAddress -SessionDetails

#(Optional) List the properties/methods of the XdSession object
$xdsession | get-member

#Retrieve a selection of the virtual desktop session properties.
#Note:  The commands below assume $xdsession represents one session.
#       If $xdsession is an array of XdSession objects, use notation such as $xdsession[0], $xdsession[1]
#       to refer to a specific session with the array.
echo $xdsession.Controller           #DDC that brokered the request
echo $xdsession.DesktopName          #Active Directory machine name of the virtual desktop session
echo $xdsession.EncryptionLevel      #Encryption level <span class="code-keyword">for</span> the session
echo $xdsession.EndpointAddress      #IP address of the endpoint who launched the virtual desktop
echo $xdsession.EndpointName         #Hostname of the endponit who launched the virtual desktop
echo $xdsession.Protocol             #Protocol used <span class="code-keyword">for</span> the connection to the virtual desktop (e.g. ICA)
echo $xdsession.StartTime.DateTime   #Time the virtual desktop session was started
echo $xdsession.State                #Current state of the virtual desktop (e.g. Connected, Disconnected)
echo $xdsession.Username             #Active Directory username who launched the session

3 – PowerShell script for disconnecting a virtual desktop session
The sample script below demonstrates how to disconnect a virtual desktop session.

#************************************************************
#Disconnect a virtual desktop session
#************************************************************

#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
$strDDCAddress = <span class="code-quote">"10.10.10.56"</span>
$strUsername = <span class="code-quote">"CITRIXLAB\User1"</span>

#Get all active sessions <span class="code-keyword">for</span> the specified user
$xdsession = Get-XdSession -user $strUsername -AdminAddress $strDDCAddress -SessionDetails

#Disconnect the specified session(s)
Disconnect-XdSession -session $xdsession

4 – PowerShell script for shutting down a virtual desktop session after sending a warning message to the user
The sample script below demonstrates how to send messages to virtual desktop sessions and shut down the session.

#*************************************************************************************
#Shut down a virtual desktop session after sending a warning message to the user
#*************************************************************************************

#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
$strDDCAddress = <span class="code-quote">"10.10.10.56"</span>
$strUsername = <span class="code-quote">"CITRIXLAB\User1"</span>
$strMessageTitle = <span class="code-quote">"Citrix Admin"</span>
$strMessageText = <span class="code-quote">"Your session will shut down in 10 minutes <span class="code-keyword">for</span> scheduled maintenance.  Please save your work at <span class="code-keyword">this</span> time."</span>

#Get all active sessions <span class="code-keyword">for</span> the specified user
$xdsession = Get-XdSession -user $strUsername -AdminAddress $strDDCAddress -SessionDetails

#Send message to the specified session(s)
Send-XdSessionMessage -message $strMessageText -title $strMessageTitle -session $xdsession

#Pause 10 minutes (600 seconds)
Start-Sleep 600

#Stop the specified session(s)
Stop-XdSession -session $xdsession

When executing the above script, verify that the virtual desktop session received the warning message.

Analyzing the PowerShell Scripts
All of the scripts above use the Get-XdSession cmdlet for retrieving a reference to the virtual desktop sessions. This cmdlet supports the -User parameter for limiting the returned sessions for a particular user. It also supports a -Group parameter for limiting the returned sessions for a particular desktop group. An extra switch called -SessionDetails can be used to retrieve extra session information. Feel free to play with this switch to see what extra data is returned by including this in there.

The Get-XdSession cmdlet returns the XdSession object (or an array of them) depending on how many sessions were found with the specified parameters. Once you have a reference to the XdSession object, you are free to review its properties for determining the details about the session. You can also pass this object as a parameter to the Disconnect-XdSession and Stop-XdSession cmdlets for disconnecting and shutting down the virtual desktop sessions.

Finally, a cool feature of the XenDesktop PowerShell SDK is the ability to send messages to the virtual desktop sessions. The last script above demonstrates one possible use case for this, which is to warn users that their sessions will expire soon for planned maintenance. The Send-XdSessionMessage cmdlet is used to send the messages to the virtual desktop sessions with the specified window title and window text.

Wrap-up
This article explains how to interact with the XenDesktop virtual desktop sessions using PowerShell. We reviewed several sample scripts in this article such as how to retrieve the total number of active sessions across the farm, how to retrieve the properties of each session, and how to disconnect/shutdown the sessions.

We are getting close to the end on this blog series. In the next blog, I’ll wrap up this series and focus on a few final things regarding the XenDesktop PowerShell SDK. Be sure to also sign up for the TechTalk we are delivering next week where you can see several of these PowerShell scripts in action!

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. Feel free to also check out Mike’s blog on XenApp 6 PowerShell scripting here. We hope to see you at the TechTalk!

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