Citrix Virtual Apps and Desktops SDK

Creating and configuring a hosting connection

The following example shows how to create and configure a hosting connection.

Before you begin, make sure you follow the steps detailed in the Getting started guide, which tells you how to use Studio to perform the operation you want to script (in this case, to create a host) and collect the log of SDK operations that Studio made to perform the task. This output can then be customized to produce a script for automating host creation.

Note:

To ensure you always get the latest enhancements and fixes, Citrix recommends you follow the procedure described in this document, rather than copying and pasting the example script. Line numbers and line breaks have been added to the script for readability.

Understand the script

The following section explains what each part of the script produced by Studio is doing. This will help you with the customization of your own script. Line breaks have been added for readability.

Get-LogSite -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Queries the configuration logging service to retrieve information about the site configuration.

Start-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' `
    -Source 'Studio' -StartTime 14/08/2013 14:30:28 -Text 'Create Connection `'Example Citrix Hypervisor`''
<!--NeedCopy-->

Starts a high-level logging operation with the configuration logging operation within which the rest of the commands will exist. Returns a log ID which is supplied to subsequent operations.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the location of the Host Service that will be used by the configuration cmdlets. Because the Host Service exposes a PowerShell provider, not all of the cmdlets can take an address for the service so this cmdlet sets a default location.

New-Item -ConnectionType 'XenServer' -HypervisorAddress @('http://hypervisorhost1.example.com') `
    -LoggingId e355ce51-8cbb-400a-ae81-1fdc567239cb -Path @('XDHyp:\Connections\Example Citrix Hypervisor') `
    -Scope @() -Password ******** -UserName 'root'
<!--NeedCopy-->

Creates a connection to a Citrix Hypervisor host (hypervisorhost1.example.com). This is a non-persistent connection and is available only to this PowerShell runspace.

Stop-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' -EndTime 14/08/2013 14:30:29 `
    -HighLevelOperationId 'e355ce51-8cbb-400a-ae81-1fdc567239cb' -IsSuccessful $True
<!--NeedCopy-->

Stops the logged operation begun previously and indicates it was successful.

Get-LogSite -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Queries the configuration logging service to retrieve information about the site configuration.

Start-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' -Source 'Studio' -StartTime 14/08/2013 14:30:30 `
    -Text 'Update Connection `'Example Citrix Hypervisor`''
<!--NeedCopy-->

Starts a new high-level logging operation.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the Host Service address details again (note that this repetition is removed in the optimized script below).

Set-Item -HypervisorAddress @('http://hypervisorhost1.example.com','http://hypervisorhost2.example.com') `
    -LoggingId 44e15629-6906-4840-a36c-984aaf67be6d -PassThru -Path @('XDHyp:\\Connections\\Example Citrix Hypervisor') `
    -Password ******** -UserName 'root'
<!--NeedCopy-->

Updates the connection previously created. As there is more than one Citrix Hypervisor server in the pool, it supplies all the addresses to enable High Availability.

Stop-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' -EndTime 14/08/2013 14:30:31 `
    -HighLevelOperationId '44e15629-6906-4840-a36c-984aaf67be6d' -IsSuccessful \$True
<!--NeedCopy-->

Stops the logging operation.

Get-LogSite -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Queries the configuration logging service to retrieve information about the site configuration.

Start-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' -Source 'Studio' `
    -StartTime 14/08/2013 14:31:03 `
    -Text 'Create Resources `'Example Resources`' and Persist Connection `'Example Citrix Hypervisor`''
<!--NeedCopy-->

Starts a new logging operation.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the Host Service address details again.

Get-ChildItem -Path @('XDHyp:\Connections')
<!--NeedCopy-->

Gets the contents of the host connection to populate the wizard dialogs.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the Host Service address details again.

Remove-Item -LoggingId 76caa3f4-df93-4cb2-b78d-6a8824766314 -Path @('XDHyp:\Connections\Example Citrix Hypervisor')
<!--NeedCopy-->

Removes the temporary connection created in the wizard.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the Host Service address details again.

New-Item -ConnectionType 'XenServer' -HypervisorAddress @('http://hypervisorhost1.example.com','http://hypervisorhost2.example.com') `
    -LoggingId 76caa3f4-df93-4cb2-b78d-6a8824766314 -Path @('XDHyp:\\Connections\\Example Citrix Hypervisor') -Persist `
    -Scope @() -Password ******** -UserName 'root'
<!--NeedCopy-->

Recreates the connection as a persistent connection which is written to the database and available to other PowerShell runspaces.

New-BrokerHypervisorConnection -AdminAddress 'mycontroller.example.com:80' `
    -HypHypervisorConnectionUid a14096ba-5074-44ff-b596-371e345c0449 `
    -LoggingId 76caa3f4-df93-4cb2-b78d-6a8824766314
<!--NeedCopy-->

Adds the host connection to the Broker Service.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the Host Service address details again.

New-Item -HypervisorConnectionName 'Example Citrix Hypervisor' -LoggingId 76caa3f4-df93-4cb2-b78d-6a8824766314 `
    -NetworkPath @('XDHyp:\Connections\Example Citrix Hypervisor\Network0.network') `
    -Path @('XDHyp:\HostingUnits\Example Resources') `
    -RootPath 'XDHyp:\Connections\Example Citrix Hypervisor' `
    -StoragePath @('XDHyp:\Connections\Example Citrix Hypervisor\Primary OS.storage')
<!--NeedCopy-->

Creates the HostingUnit (referred to as Resources in Studio) using the information gathered in step 14.

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'
<!--NeedCopy-->

Sets the Host Service address details again.

Get-Item -Path @('XDHyp:\Connections\Example Citrix Hypervisor')
<!--NeedCopy-->

Retrieves the newly created object.

Stop-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' -EndTime 14/08/2013 14:31:07 `
    -HighLevelOperationId '76caa3f4-df93-4cb2-b78d-6a8824766314' -IsSuccessful $True
<!--NeedCopy-->

Stops the logged operation begun previously and indicates if it was successful.

Customize the script

The following section shows how to convert and adapt the Studio output into a script that is more consumable. The following script has been simplified so that, instead of creating a temporary host connection in the process of acquiring information in the wizards as in the Studio script above, a persistent connection is created. Information is then queried from within this to create the HostingUnit (Resources). Note that the LoggingId and HypHyperConnectionUid details are different.

Line breaks have been added for readability.

$loggingOp = Start-LogHighLevelOperation -AdminAddress $adminAddress -Source 'Scripted' -Text "Create Connection '$connectionName'"
$loggingId = $loggingOp.Id

Set-HypAdminConnection -AdminAddress 'mycontroller.example.com:80'

New-Item -ConnectionType 'XenServer' -HypervisorAddress @('http://hypervisorhost1.example.com','http://hypervisorhost2.example.com')`
    -LoggingId $loggingId -Path @('XDHyp:\\Connections\\Example Citrix Hypervisor') -Persist -Scope @() `
    -Password 'XenServerPassword' -UserName 'root'

Get-ChildItem -Path @('XDHyp:\Connections')

New-BrokerHypervisorConnection -AdminAddress 'mycontroller.example.com:80' `
    -HypHypervisorConnectionUid a14096ba-5074-44ff-b596-371e345c0449 `
    -LoggingId $loggingId 

New-Item -HypervisorConnectionName 'Example Citrix Hypervisor' -LoggingId $loggingId `
    -NetworkPath @('XDHyp:\Connections\Example Citrix Hypervisor\Network0.network') `
    -Path @('XDHyp:\HostingUnits\Example Resources') `
    -RootPath 'XDHyp:\Connections\Example Citrix Hypervisor' `
    -StoragePath @('XDHyp:\Connections\Example Citrix Hypervisor\PrimaryOS.storage')

Stop-LogHighLevelOperation -AdminAddress 'mycontroller.example.com:80' -HighLevelOperationId $loggingId -IsSuccessful $True
<!--NeedCopy-->
Creating and configuring a hosting connection