XenDesktop 5 PowerShell SDK Primer – Part 2 – Creating Hypervisor Connections and Hosts

One of the new changes that you will see in XenDesktop 5 is the configuration of hypervisor connectionsand hosts. In order to create the “pooled”, “dedicated”, or “existing” catalog types in XenDesktop 5, XenDesktop needs to know details of the hypervisor that will be hosting the virtual desktops. Hypervisor connection details are also required in order to manage virtual desktops from within Desktop Studio, such as powering on and restarting virtual desktops. Hypervisor connections and hosts can be created manually within Desktop Studio or automated using the PowerShell SDK. The focus of this article will be on the automation of this configuration using PowerShell.

This is the second blog in a series on how to use the XenDesktop 5 PowerShell SDK. In the first blog, I provided info on how to get started with the SDK, some approaches you can take for learning the cmdlets, some reference web pages that you can bookmark, and the tools you can use for creating your own scripts. If you haven’t read that article yet, please visit that blog first. For a complete list of topics that I will be covering in this series, see the bottom of this article.

What are Hypervisor Connections and Hosts within XenDesktop 5?

Hypervisor connections and hosts are one of the first items that you typically configure in a XenDesktop 5 deployment. They are configured within the Hosts node of the Desktop Studio Console. If you were to configure this manually in the console, you would click Add Host and run through a short wizard to configure both at the same time (see screen shot below). In short…

• Connections represent a “connection” to a specific hypervisor type (XenServer, Hyper-V, etc). This connection contains the address, username, and password for communicating to that hypervisor. If you want to tie your XenDesktop deployment to multiple hypervisor types, you will have multiple connections defined.
• Hosts represent a “server” that leverages the hypervisor connection. A hypervisor connection can have one or several hosts tied to it, depending on whether the hypervisor deployment is a single server or a pool of servers. The host configuration consists of the name of the “hosting unit”, the “guest network” used by the virtual desktops on the host, and the “storage repository” used by the virtual desktops on the host.

  

PowerShell Script for creating Hypervisor Connections and Hosts

The sample script below demonstrates how to create a hypervisor connection and host within XenDesktop 5. This script references a XenServer host that has a storage repository called “Local Storage” and a guest network called “Internal”.

#***************************************************************
#Write debug message to signify start of script
#***************************************************************
$objDateTime = Get-Date
Write-Host ""
Write-Host "*****Script started at" $objDateTime "*****"

#***************************************************************
#Add Citrix snapins to PowerShell session if not already added
#***************************************************************
$snapins = Get-PSSnapin | where { $_.Name -like "Citrix*" }
if (($snapins -eq $null) -or ($snapins.Count -ne 8))
{
    Write-Host "Loading the XenDesktop cmdlets into this session..."
    Get-PSSnapin -Registered "Citrix*" | Add-PSSnapin
    Add-PSSnapin "PvsPsSnapin"
}
else
{
    Write-Host "XenDesktop cmdlets are already loaded into this session..."
}

#*****************************************************************************
#Global variables for entire script
#*****************************************************************************
$strXenServerHostname = "173.192.71.99"
$strXenServerUsername = "root"
$strXenServerPassword = "Password1"
$strHypervisorConnectionName = "XenServer Connection"
$strHypervisorType = "XenServer"
$strHypervisorAddress = "http://" + $strXenServerHostname
$strGuestNetworkName = "Internal"               #Use the "Internal" network defined on XenServer
$strStorageName = "Local Storage"               #Use the "Local Storage" SR defined on XenServer
$strDDCAddress = "ddc1.xendesktop.lab:80"

#*****************************************************************************
#Create hypervisor connection
#*****************************************************************************
$objHypConn = New-Item -Path 'xdhyp:\connections' -Name $strHypervisorConnectionName -HypervisorAddress $strHypervisorAddress -ConnectionType $strHypervisorType -Username $strXenServerUsername -Password $strXenServerPassword -Persist -AdminAddress $strDDCAddress
$objHypConnection = New-BrokerHypervisorConnection -HypHypervisorConnectionUid $objHypConn.HypervisorConnectionUid -AdminAddress $strDDCAddress
if ($objHypConnection -ne $null)
{
    #Write debug message
    Write-Host "Successfully created hypervisor connection to" $strHypervisorAddress
}
else
{
    #Write debug message
    Write-Host "ERROR: Could not create hypervisor connection to" $strHypervisorAddress
}

#*****************************************************************************
#Add host to the hypervisor connection
#*****************************************************************************
$strHostUnitName = $strXenServerHostname.Replace(".", "-")      #Periods are not accepted in the hosting unit name
$strRootPath = "xdhyp:\connections\" + $strHypervisorConnectionName
$strNetworkPath = $strRootPath + "\" + $strGuestNetworkName + ".network"
$strStoragePath = $strRootPath + "\" + $strStorageName + ".storage"
$objHostUnits = New-Item -Path 'xdhyp:\hostingunits' -Name $strHostUnitName -HypervisorConnectionName $objHypConnection.Name -RootPath $strRootPath -NetworkPath $strNetworkPath -StoragePath $strStoragePath -AdminAddress $strDDCAddress
if ($objHostUnits -ne $null)
{
    #Write debug message
    Write-Host "Successfully added host called" $strHostUnitName "to the hypervisor connection..."
}
else
{
    #Write debug message
    Write-Host "ERROR: Could not add host to the hypervisor connection..."
}

#***************************************************************
#Write debug message to signify end of script
#***************************************************************
$objDateTime = Get-Date
Write-Host "*****Script ended on" $objDateTime "*****"
Write-Host ""

Note: The sample script above performs some basic error handling to help you keep track of the automation status. It outputs the success or failure of key sections of the script to the PowerShell window. The expected output is shown below. If you run into any issues, you can use a PowerShell editor such asPowerGui.exe to step through each line of the script.

After the script is executed, you can open the Desktop Studio console to verify the hypervisor connection and host configuration are present (see screen shot below).

Analyzing the PowerShell Script

The top of the script has a section on loading the XenDesktop PowerShell snap-ins. This is needed to ensure we can call the XenDesktop cmdlets no matter how you choose to execute the script (Standard PowerShell window, PowerGui.exe, etc.). You’ll see this same code snippet at the top of all my XenDesktop 5 scripts.

Next, the Global Variables section defines the information specific to my environment. This is the information that you would have normally configured if you were to run through the wizard in Desktop Studio. This should be the only section that you need to touch to ensure that the script can run within your own environment. You’ll want to change the values here to reference your own hypervisor connection and host.

Once the global variables are defined, the good stuff really starts. Creating a hypervisor connection and host takes three cmdlet calls. You will reference the New-Item and New-BrokerHypervisorConnection cmdlets. If you want to experiment some more, you can also play with the Get-BrokerHypervisorConnection cmdlet to see the properties of an existing hypervisor connection.

#Get reference to an existing hypervisor connection with the specified name
$objHypConnection = Get-BrokerHypervisorConnection -Name "XenServer Connection"

A lot of the code within this script is for the error checking. To check for errors, I’m placing the output of the cmdlets into variables. The output of these particular cmdlets are all objects. I’m then checking if that object is null. If it’s not null, I know I have a valid reference to that object and that cmdlet executed successfully. If it’s null, I know some error occurred. You can enhance this error checking even more by preventing the script from proceeding further should an error come up.