SDKs and APIs

Citrix Virtual Apps and Desktops Remote PowerShell SDK

The Remote PowerShell (PS) SDK automates complex and repetitive tasks. It provides the mechanism to set up and manage the Citrix Virtual Apps and Desktops (formerly XenApp and XenDesktop) environment without having to use the Studio user interface.

The supported snap-ins are listed in Limitations. That section also lists the cmdlets that are disabled.

How this SDK differs from the Citrix Virtual Apps and Desktops Delivery Controller SDK

In a Citrix Virtual Apps and Desktops deployment that is fully installed and managed by customer administrators, those administrators run cmdlets and scripts in a Site containing both VDAs and Delivery Controllers within a common domain structure. In contrast, the Citrix Virtual Apps and Desktops service splits the VDAs and Controllers into a resource location and the control plane, respectively. This split means the original Citrix Virtual Apps and Desktops PS SDK will not work in a Citrix Virtual Apps and Desktops service environment, because it cannot cross the secure resource location to control plane boundary.

The solution is the Citrix Virtual Apps and Desktops Remote PS SDK. When run in the resource location, the Remote PS SDK accesses the control plane as if it were local, providing the same functionality as a single Citrix Virtual Apps and Desktops 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 the 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 is called by the first PS SDK cmdlet.

Install and use the Remote PowerShell SDK

Requirements:

  • Ensure that PowerShell 3.0 or later is available on the machine.
  • If the machine has the Citrix Virtual Apps and Desktops Delivery Controller SDK installed, remove that SDK (from Windows Programs and Features) before installing the Remote PowerShell SDK.

To install the Remote PowerShell SDK:

  1. Download the installer: https://download.apps.cloud.com/CitrixPoshSdk.exe. The package contains both x86 and x64 implementations.
  2. In the downloaded 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.

Run the Citrix Virtual Apps and Desktops Remote PS SDK on a domain-joined computer within that 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 Citrix Virtual Apps and Desktops 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. See an example below.

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

Uninstall:

From the Windows feature for removing or changing programs, select Citrix Virtual Apps and Desktops Remote PowerShell SDK. Right-click and select Uninstall. Follow the dialog.

Example activities

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

    $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 Citrix Virtual Apps and Desktops PowerShell snap-ins are supported in this release:

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

For details about cmdlets in those snap-ins, see Citrix Virtual Apps and Desktops SDK.

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

The 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.

Citrix.ADIdentity.Admin.V2:

  • Copy-AcctIdentityPool
  • Get-AcctDBConnection
  • Get-AcctDBSchema
  • Get-AcctDBVersionChangeScript
  • Get-AcctInstalledDBVersion
  • Remove-AcctServiceMetadata
  • Reset-AcctServiceGroupMembership
  • Set-AcctDBConnection
  • Set-AcctServiceMetadata
  • Test-AcctDBConnection

Citrix.Analytics.Admin.V1:

  • Get-AnalyticsDBConnection
  • Get-AnalyticsDBSchema
  • Get-AnalyticsDBVersionChangeScript
  • Get-AnalyticsInstalledDBVersion
  • Import-AnalyticsDataDefinition
  • Remove-AnalyticsServiceMetadata
  • Reset-AnalyticsServiceGroupMembership
  • Set-AnalyticsDBConnection
  • Set-AnalyticsServiceMetadata
  • Set-AnalyticsSite
  • Set-AnalyticsDBConnection

Citrix.DelegatedAdmin.Admin.V1:

  • Add-AdminRight
  • Get-AdminDBConnection
  • Get-AdminDBSchema
  • Get-AdminDBVersionChangeScript
  • Get-AdminInstalledDBVersion
  • Import-AdminRoleConfiguration
  • New-AdminAdministrator
  • Remove-AdminAdministrator
  • Remove-AdminAdministratorMetadata
  • Remove-AdminRight
  • Remove-AdminServiceMetadata
  • Reset-AdminServiceGroupMembership
  • Set-AdminAdministrator
  • Set-AdminAdministratorMetadata
  • Set-AdminDBConnection
  • Set-AdminServiceMetadata
  • Test-AdminDBConnection

Citrix.Broker.Admin.V2:

  • Get-BrokerDBConnection
  • Get-BrokerDBSchema
  • Get-BrokerDBVersionChangeScript
  • Get-BrokerInstalledDBVersion
  • Get-BrokerLease
  • New-BrokerMachineConfiguration
  • Remove-BrokerControllerMetadata
  • Remove-BrokerLease
  • Remove-BrokerLeaseMetadata
  • Remove-BrokerMachineConfigurationMetadata
  • Remove-BrokerMachineConfiguration
  • Remove-BrokerSiteMetadata
  • Remove-BrokerUserFromApplication
  • Reset-BrokerLicensingConnection
  • Reset-BrokerServiceGroupMembership
  • Set-BrokerControllerMetadata
  • Set-BrokerDBConnection
  • Set-BrokerLeaseMetadata
  • Set-BrokerMachineConfiguration
  • Set-BrokerMachineConfigurationMetadata
  • Set-BrokerSite
  • Set-BrokerSiteMetadata
  • Test-BrokerDBConnection
  • Test-BrokerLicenseServer
  • Update-BrokerBrokerLocalLeaseCache

Citrix.Configuration.Admin.V2:

  • Export-ConfigFeatureTable
  • Get-ConfigDBConnection
  • Get-ConfigDBSchema
  • Get-ConfigDBVersionChangeScript
  • Get-ConfigInstalledDBVersion
  • Get-ConfigServiceGroup
  • Import-ConfigFeatureTable
  • Register-ConfigServiceInstance
  • Remove-ConfigRegisteredServiceInstanceMetadata
  • Remove-ConfigServiceGroup
  • Remove-ConfigServiceGroupMetadata
  • Remove-ConfigServiceMetadata
  • Remove-ConfigSiteMetadata
  • Reset-ConfigServiceGroupMembership
  • Set-ConfigDBConnection
  • Set-ConfigRegisteredServiceInstance
  • Set-ConfigRegisteredServiceInstanceMetadata
  • Set-ConfigServiceGroupMetadata
  • Set-ConfigServiceMetadata
  • Set-ConfigSite
  • Set-ConfigSiteMetadata
  • Test-ConfigDBConnection
  • Unregister-ConfigRegisteredServiceInstance

Citrix.Host.Admin.V2:

  • Get-HypDBConnection
  • Get-HypDBSchema
  • Get-HypDBVersionChangeScript
  • Get-HypInstalledDBVersion
  • Remove-HypServiceMetadata
  • Reset-HypServiceGroupMembership
  • Set-HypDBConnection
  • Set-HypServiceMetadata
  • Test-HypDBConnection

Citrix.ConfigurationLogging.Admin.V1:

  • Get-LogDBConnection
  • Get-LogDBSchema
  • Get-LogDBVersionChangeScript
  • Get-LogInstalledDBVersion
  • Remove-LogOperation
  • Remove-LogServiceMetadata
  • Remove-LogSiteMetadata
  • Reset-LogDataStore
  • Reset-LogServiceGroupMembership
  • Set-LogDBConnection
  • Set-LogServiceMetadata
  • Set-LogSite
  • Set-LogSiteMetadata
  • Test-LogDBConnection

Citrix.MachineCreation.Admin.V2:

  • Get-ProvDBConnection
  • Get-ProvDBSchema
  • Get-ProvDBVersionChangeScript
  • Get-ProvInstalledDBVersion
  • Get-ProvServiceConfigurationData
  • Remove-ProvServiceConfigurationData
  • Remove-ProvServiceMetadata
  • Reset-ProvServiceGroupMembership
  • Set-ProvDBConnection
  • Set-ProvServiceConfigurationData
  • Set-ProvServiceMetadata
  • Test-ProvDBConnection

Citrix.EnvTest.Admin.V1:

  • Get-EnvTestDBConnection
  • Get-EnvTestDBSchema
  • Get-EnvTestDBVersionChangeScript
  • Get-EnvTestInstalledDBVersion
  • Remove-EnvTestServiceMetadata
  • Reset-EnvTestServiceGroupMembership
  • Set-EnvTestDBConnection
  • Set-EnvTestServiceMetadata
  • Test-EnvTestDBConnection

Citrix.Monitor.Admin.V1:

  • Get-MonitorConfiguration
  • Get-MonitorDBConnection
  • Get-MonitorDBSchema
  • Get-MonitorDBVersionChangeScript
  • Get-MonitorDataStore
  • Get-MonitorDataStore
  • Get-MonitorInstalledDBVersion
  • Remove-MonitorServiceMetadata
  • Reset-MonitorDataStore
  • Reset-MonitorServiceGroupMembership
  • Set-MonitorConfiguration
  • Set-MonitorDBConnection
  • Set-MonitorServiceMetadata
  • Test-MonitorDBConnection

Citrix.Storefront.Admin.V1:

  • Build-SfCluster
  • Get-SfClusters
  • Get-SfDBConnection
  • Get-SfDBSchema
  • Get-SfDBVersionChangeScript
  • Get-SfInstalledDBVersion

Citrix Virtual Apps and Desktops discovery module for App-V packages

The Citrix Virtual Apps and Desktop service can deliver applications contained in App-V packages to your end points using the single admin management method. The process of registering App-V packages with the App Library using the Citrix Virtual Apps and Desktop service is slightly different to registering packages using an on-premises deployment. However, the process of assigning applications to users and launching them on a user’s end point is identical.

The service management console in Citrix Cloud cannot see files in a resource location, and it cannot discover App-V packages on your infrastructure directly. The discovery module contains PowerShell functions you can run on a machine in your resource location to discover App-V packages, and the apps they contain, and push that information to the Citrix Virtual Apps and Desktop Service.

Install and use the discovery module for App-V packages

Requirements:

  • Ensure that PowerShell 3.0 or later is available on the machine.
  • Ensure that the Citrix Virtual Apps and Desktops Remote PowerShell SDK is installed on the machine.

To install the discovery module for App-V packages:

Download the signed PowerShell module file Citrix.Cloud.AppLibrary.Admin.v1.psm1: Citrix Virtual Apps and Desktops download page. (This file is also provided on the Citrix Virtual Apps and Desktops ISO in Support\Tools\Scripts where it can be copied locally or referenced directly from the CD drive.)

The module contains the following high level functions which you can call from your own PowerShell script:

  • Import-AppVPackageToCloud -PackagePath <Full UNC path to App-V package>
    • Discovers and uploads to the Citrix Virtual Apps and Desktop service all the information necessary to publish applications from a single App-V Package.
  • Import-AppVPackagesFromManagementServerToCloud -ManagementSrvFQDN <FQDN of a Microsoft App-V Management Server>
    • Discovers the UNC paths of packages published by the Management Server and calls Import-AppVPackageToCloud** for each one in turn.

      Note:

      Packages discovered in this way are loaded to the Citrix Virtual Apps and Desktops Service using the single admin management method. The Citrix Virtual Apps and Desktops Service cannot deliver packages using the dual admin management method.

Run the discovery module for App-V packages on a domain-joined computer within that resource location:

  • Open a PowerShell command prompt. You do not need to run as an administrator.
  • Add the Citrix snap-ins: asnp citrix.*.
  • You can explicitly authenticate by using the Get-XdAuthentication cmdlet. Or, execute your first discovery module for App-V PS SDK command, which prompts 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. See the following examples.

Example activities

Import the Virtual Apps and Desktops service App-V package discovery module

import-module "D:\Support\Tools\Scripts\Citrix.Cloud.AppLibrary.Admin.v1.psm1"

Loop through the App-V Package store directory and upload each package

Get-ChildItem -Path "\\FileServer.domain.net\App-V Packages" -Filter *.appv |
Foreach-Object{
    Import-AppVPackageToCloud -PackagePath $_.FullName
}

Discover and upload packages registered with a Microsoft App-V management server

Import-AppVPackagesFromManagementServerToCloud -ManagementSrvFQDN AppVManagementServer.domain.net

Read PowerShell help documentation included in the module

Get-Help Import-AppVPackageToCloud

Limitations

  • You cannot discover App-V packages on your resource location infrastructure directly from the service management console in Citrix Cloud.
  • Packages discovered by this module cannot be loaded to the Citrix Virtual Apps and Desktops Service using the dual admin management method.

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.

Monitor Service OData API

In addition to using the Monitor funtions to display historical data, you can query data using the Monitor Service’s API. You can use the API to:

  • Analyze historical trends for future planning
  • Perform detailed troubleshooting of connection and machine failures
  • Extract information for feeding into other tools and processes; for example, using Microsoft Excel’s PowerPivot tables to display the data in different ways
  • Build a custom user interface on top of the data that the API provides

For details, see Monitor Service OData API. For instructions to access the Monitor Service API, see Access Monitor Service data using the OData v4 endpoint in Citrix Cloud.

Citrix Virtual Apps and Desktops service APIs

The Virtual Apps and Desktops service APIs are available at https://developerv1.cloud.com/_virtual_apps_and_desktops_service/virtual_apps_and_desktops_service.html.