Product Documentation

XenApp and XenDesktop Remote PowerShell SDK

Jun 14, 2016

The XenApp and XenDesktop PowerShell (PS) SDK automates complex and repetitive tasks. It provides the mechanism to set up and manage the XenApp and XenDesktop environment without having to use the Studio UI.

Customers run cmdlets and scripts in their traditional site containing both VDAs and Delivery Controllers within a common domain structure. The Citrix Cloud XenApp and XenDesktop Service splits the VDAs and Controllers into a Resource Location and Control Plane, respectively. This split means the original XenApp and XenDesktop PS SDK will not work because it cannot cross the secure Resource Location to Control Plane boundary.

The solution is the XenApp and XenDesktop Remote PS SDK. When run in the Resource Location, the Remote PS SDK can access the Control Plane as if it were local, providing the same functionality as a single XenApp and XenDesktop site. There is only the lowest non-visible communication layer, enhanced to work either in a single local site or in the cloud environment. The cmdlets arethe same, and most existing scripts will work unchanged.

The Get-XdAuthentication cmdlet provides authorization to cross the secure Resource Location to Control Plane boundary. By default, Get-XdAuthentication prompts users for CAS credentials, and must be done once per PowerShell session. Alternatively, the user can define an authentication profile using an API access Secure Client, created in the Citrix Cloud console. In both cases, the security information persists for use in subsequent PS SDK calls. If this cmdlet is not explicitly executed, it will be called by the first PS SDK cmdlet.

Install

Make sure PowerShell 3.0 or later is available on your system.

  1. Download the installer from: here; the package contains both x86 and x64 implementations.
  2. In the download folder, locate and run the installer.
  3. Follow the dialogs to complete the installation.

Installation logs are created in %TEMP%\CitrixLogs\CitrixPoshSdk. Logs can help resolve installation issues.

How to Use

Run the XenApp and XenDesktop Remote PS SDK from any computer in the customer’s Resource Location.

  • Open a PowerShell command prompt. You do not need to run as an administrator.
  • Add the Citrix snapins: asnp citrix*.
  • You can explicitly authenticate by using the Get-XdAuthentication cmdlet. Or, execute your first XenApp and XenDesktop PS SDK command, which will prompt you for the same authentication as Get-XdAuthentication.
  • To bypass the authentication prompt, you can use the Set-XdCredentials cmdlet to create a default authentication profile, using a Secure Client created in the Citrix Cloud console.
  • Continue executing PS SDK cmdlets or PS SDK automation scripts.

Citrix recommends that you do not run this on the Connectors; the SDK’s operation does not involve the Connectors.

Uninstall

From the Windows feature for removing or changing programs, select XenApp and XenDesktop Remote PowerShell SDK, then right-click and select Uninstall. Follow the dialog.

Example

Common activities include setting up catalogs, applications, and users. A sample script is shown below.

command Copy

$users = "xd.local\Domain Users"

$TSVDACatalogName = "TSVDA"

$TSVDADGName = "TSVDA"

$TSVDAMachineName = "xd\ds-tsvda2"

#Create TSVDA Catalog

$brokerUsers = New-BrokerUser -Name $users

$catalog = New-BrokerCatalog -Name $TSVDACatalogName -AllocationType "Random" -Description $TSVDACatalogName -PersistUserChanges "OnLocal" -ProvisioningType "Manual" -SessionSupport "MultiSession" -MachinesArePhysical $true

 

#Add TSVDA Machine to Catalog

$BrokeredMachine = New-BrokerMachine -MachineName $TSVDAMachineName -CatalogUid $catalog.uid

 

#Create new desktops & applications delivery group

$dg = New-BrokerDesktopGroup -Name $TSVDADGName -PublishedName $TSVDADGName -DesktopKind "Shared" -SessionSupport "MultiSession" -DeliveryType DesktopsAndApps -Description $TSVDADGName

 

#Create notepad application

New-BrokerApplication -ApplicationType HostedOnDesktop -Name "Notepad" -CommandLineExecutable "notepad.exe" -DesktopGroup $dg

 

#Assign users to desktops and applications

New-BrokerEntitlementPolicyRule -Name $TSVDADGName -DesktopGroupUid $dg.Uid -IncludedUsers $brokerUsers -description $TSVDADGName

New-BrokerAccessPolicyRule -Name $TSVDADGName -IncludedUserFilterEnabled $true -IncludedUsers $brokerUsers -DesktopGroupUid $dg.Uid -AllowedProtocols @("HDX","RDP")

New-BrokerAppEntitlementPolicyRule -Name $TSVDADGName -DesktopGroupUid $dg.Uid -IncludedUsers $brokerUsers -description $TSVDADGName

 

#Add machine to delivery group

Add-BrokerMachine -MachineName $TSVDAMachineName -DesktopGroup $dg

Limitations

The following XenApp and XenDesktop PowerShell snap-ins are supported in this release:

  • Broker
  • Active Directory (AD) Identity
  • Machine Creation
  • Configuration
  • Configuration Logging
  • Host
  • Delegated Administration
  • Analytics

Once authenticated, remote access remains valid in the current PowerShell session for 24 hours. After this time, you must enter your credentials.

The XenApp and XenDesktop Remote PS SDK must be run on a computer within the Resource Location.

The following cmdlets are disabled in remote operations to maintain the integrity and security of the Cloud control plane.

Snapin Cmdlets

Citrix.ADIdentity.Admin.V2

Acct:CopyIdentityPool

Acct:GetDBConnection

Acct:GetDBSchema

Acct:GetDBVersionChangeScript

Acct:GetInstalledDBVersion

Acct:RemoveServiceMetadata

Acct:ResetServiceGroupMembership

Acct:SetDBConnection

Acct:SetServiceMetadata

Acct:TestDBConnection

Citrix.Analytics.Admin.V1

Analytics:GetDBConnection

Analytics:GetDBSchema

Analytics:GetDBVersionChangeScript

Analytics:GetInstalledDBVersion

Analytics:ImportDataDefinition

Analytics:RemoveServiceMetadata

Analytics:ResetServiceGroupMembership

Analytics:SetDBConnection

Analytics:SetServiceMetadata

Analytics:SetSite

Analytics:TestDBConnection

Citrix.DelegatedAdmin.Admin.V1

Admin:AddPermission

Admin:AddRight

Admin:GetAdministrator

Admin:GetDBConnection

Admin:GetDBSchema

Admin:GetDBVersionChangeScript

Admin:GetInstalledDBVersion

Admin:ImportRoleConfiguration

Admin:NewAdministrator

Admin:NewRole

Admin:NewScope

Admin:RemoveAdministrator

Admin:RemoveAdministratorMetadata

Admin:RemovePermission

Admin:RemoveRight

Admin:RemoveRole

Admin:RemoveRoleMetadata

Admin:RemoveScope

Admin:RemoveScopeMetadata

Admin:RemoveServiceMetadata

Admin:ResetServiceGroupMembership

Admin:SetAdministrator

Admin:SetAdministratorMetadata

Admin:SetDBConnection

Admin:SetRole

Admin:SetRoleMetadata

Admin:SetScope

Admin:SetScopeMetadata

Admin:SetServiceMetadata

Admin:TestDBConnection

Citrix.Broker.Admin.V2

Broker:GetDBConnection

Broker:GetDBSchema

Broker:GetDBVersionChangeScript

Broker:GetInstalledDBVersion

Broker:GetLease

Broker:NewMachineConfiguration

Broker:RemoveControllerMetadata

Broker:RemoveLease

Broker:RemoveLeaseMetadata

Broker:RemoveMachineConfigurationMetadata

Broker:RemoveMachineConfiguration

Broker:RemoveSiteMetadata

Broker:RemoveUserFromApplication

Broker:ResetLicensingConnection

Broker:ResetServiceGroupMembership

Broker:SetControllerMetadata

Broker:SetDBConnection

Broker:SetLeaseMetadata

Broker:SetMachineConfiguration

Broker:SetMachineConfigurationMetadata

Broker:SetSite

Broker:SetSiteMetadata

Broker:TestDBConnection

Broker:TestLicenseServer

Broker:UpdateBrokerLocalLeaseCache

Citrix.Configuration.Admin.V2

Config:ExportFeatureTable

Config:GetDBConnection

Config:GetDBSchema

Config:GetDBVersionChangeScript

Config:GetInstalledDBVersion

Config:GetServiceGroup

Config:ImportFeatureTable

Config:RegisterServiceInstance

Config:RemoveRegisteredServiceInstanceMetadata

Config:RemoveServiceGroup

Config:RemoveServiceGroupMetadata

Config:RemoveServiceMetadata

Config:RemoveSiteMetadata

Config:ResetServiceGroupMembership

Config:SetDBConnection

Config:SetRegisteredServiceInstance

Config:SetRegisteredServiceInstanceMetadata

Config:SetServiceGroupMetadata

Config:SetServiceMetadata

Config:SetSite

Config:SetSiteMetadata

Config:TestDBConnection

Config:UnregisterRegisteredServiceInstance

Citrix.Host.Admin.V2

Hyp:GetDBConnection

Hyp:GetDBSchema

Hyp:GetDBVersionChangeScript

Hyp:GetInstalledDBVersion

Hyp:RemoveServiceMetadata

Hyp:ResetServiceGroupMembership

Hyp:SetDBConnection

Hyp:SetServiceMetadata

Hyp:TestDBConnection

Citrix.ConfigurationLogging.Admin.V1

Log:ExportReport

Log:GetDBConnection

Log:GetDBSchema

Log:GetDBVersionChangeScript

Log:GetHighLevelOperation

Log:GetInstalledDBVersion

Log:GetLowLevelOperation

Log:GetSummary

Log:RemoveOperation

Log:RemoveServiceMetadata

Log:RemoveSiteMetadata

Log:ResetDataStore

Log:ResetServiceGroupMembership

Log:SetDBConnection

Log:SetServiceMetadata

Log:SetSite

Log:SetSiteMetadata

Log:TestDBConnection

Citrix.MachineCreation.Admin.V2

Prov:GetDBConnection

Prov:GetDBSchema

Prov:GetDBVersionChangeScript

Prov:GetInstalledDBVersion

Prov:GetServiceConfigurationData

Prov:RemoveServiceConfigurationData

Prov:RemoveServiceMetadata

Prov:ResetServiceGroupMembership

Prov:SetDBConnection

Prov:SetServiceConfigurationData

Prov:SetServiceMetadata

Prov:TestDBConnection

Citrix.EnvTest.Admin.V1

EnvTest:GetDBConnection

EnvTest:GetDBSchema

EnvTest:GetDBVersionChangeScript

EnvTest:GetInstalledDBVersion

EnvTest:RemoveServiceMetadata

EnvTest:ResetServiceGroupMembership

EnvTest:SetDBConnection

EnvTest:SetServiceMetadata

EnvTest:TestDBConnection

Citrix.Monitor.Admin.V1

Monitor:GetConfiguration

Monitor:GetDBConnection

Monitor:GetDBSchema

Monitor:GetDBVersionChangeScript

Monitor:GetDataStore

Monitor:GetDataStore

Monitor:GetInstalledDBVersion

Monitor:RemoveServiceMetadata

Monitor:ResetDataStore

Monitor:ResetServiceGroupMembership

Monitor:SetConfiguration

Monitor:SetDBConnection

Monitor:SetServiceMetadata

Monitor:TestDBConnection

Citrix.Storefront.Admin.V1

Sf:BuildCluster

Sf:GetClusters

Sf:GetDBConnection

Sf:GetDBSchema

Sf:GetDBVersionChangeScript

Sf:GetInstalledDBVersion

Downloading the SDK

The XenApp and XenDesktop Remote PowerShell SDK can be downloaded from here.

Disclaimer

This software / sample code is provided to you “AS IS” with no representations, warranties or conditions of any kind. You may use, modify and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software / sample code may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software / sample code fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software / sample code. In no event should the software / code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE / SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.