StoreFront SDK

Citrix StoreFront provides an SDK based on a number of Microsoft Windows PowerShell version 2.0 modules. With the SDK, you can perform the same tasks as you would with the StoreFront MMC console, together with tasks you cannot do with the console alone.

Note:

The PowerShell SDK is not compatible with PowerShell 6 or higher.

For the SDK Reference, see StoreFront SDK.

Use the SDK

The SDK comprises of a number of PowerShell snap-ins installed automatically by the installation wizard when you install and configure various StoreFront components.

To access and run the cmdlets:

1. Ensure that the StoreFront management console is closed.

2. Start a PowerShell command line prompt or Windows PowerShell ISE as administrator.

   You must run the shell or script using a member of the local administrators group on the StoreFront server.

3. To use SDK cmdlets within scripts, set the execution policy in PowerShell to RemoteSigned. For more information about PowerShell execution policy, see Microsoft documentation.

Get started with the SDK

To create a script, perform the following steps:

1. Take one of the provided SDK examples installed by StoreFront into the %ProgramFiles%\Citrix\Receiver StoreFront\PowerShellSDK\Examples folder.
2. To help you customize your own script. review the example script to understand what each part is doing. For more information, see the example use case, which explains in detail the script’s actions.
3. Convert and adapt the example scripts to turn them into a script that is more consumable. To do this:
   • Use the PowerShell ISE or a similar tool to edit the script.
   • Use variables to assign values that are to be reused or modified.
   • Remove any commands that are not required.
   • Note that StoreFront cmdlets can be identified by the prefix STF.
   • Use the Get-Help cmdlet supplying the cmdlet name and -Full parameter for more information on a specific command.

Examples

Note:

When creating a script, to ensure you always get the latest enhancements and fixes, Citrix recommends you follow the procedure described above rather than copying and pasting the example scripts.

Example: Create a simple deployment

The following example shows how to create a simple deployment configured with one XenDesktop controller.

Before you begin, make sure you follow the steps detailed in Get Started with the SDK. This example can be customized using the methods described to produce a script for automating StoreFront deployment.

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.

Understand the script

This section explains what each part of the script produced by StoreFront is doing. This will help you with the customization of your own script.

• Sets the error handling requirements and imports the required StoreFront modules. Imports are not required in newer versions of PowerShell.

   Param(
       [Parameter(Mandatory=$true)]
       [Uri]$HostbaseUrl,
       [long]$SiteId = 1,
       [ValidateSet("XenDesktop","XenApp","AppController","VDIinaBox")]
       [string]$Farmtype = "XenDesktop",
       [Parameter(Mandatory=$true)]
       [string[]]$FarmServers,
       [string]$StoreVirtualPath = "/Citrix/Store",
       [bool]$LoadbalanceServers = $false,
       [int]$Port = 80,
       [int]$SSLRelayPort = 443,
       [ValidateSet("HTTP","HTTPS","SSL")]
       [string]$TransportType = "HTTP"
       )
       \# Import StoreFront modules. Required for versions of PowerShell earlier than 3.0 that do not support autoloading
       Import-Module Citrix.StoreFront
       Import-Module Citrix.StoreFront.Stores
       Import-Module Citrix.StoreFront.Authentication
       Import-Module Citrix.StoreFront.WebReceiver
   <!--NeedCopy-->
  

• Automates the virtual path of the authentication and Citrix Receiver for Web services based on the $StoreVirtualPath supplied. $StoreVirtualPath is equivalent to $StoreIISpath because Virtual paths are always the path in IIS. Therefore in Powershell they have a value such as “/Citrix/Store”, “/Citrix/StoreWeb”, or “/Citrix/StoreAuth”.

   \# Determine the Authentication and Receiver virtual path to use based of the Store
   $authenticationVirtualPath = "$($StoreIISPath.TrimEnd('/'))Auth"
   $receiverVirtualPath = "$($StoreVirtualPath.TrimEnd('/'))Web"
   <!--NeedCopy-->
  

• Creates a new deployment if one is not already present iin preparation for adding the required StoreFront services. -Confirm:$false suppresses the requirement to confirm the deployment can proceed.

   \# Determine if the deployment already exists
   $existingDeployment = Get-STFDeployment
   if(-not $existingDeployment)
   {
       \# Install the required StoreFront components
       Add-STFDeployment -HostBaseUrl $HostbaseUrl -SiteId $SiteId -Confirm:$false
   }
   elseif($existingDeployment.HostbaseUrl -eq $HostbaseUrl)
   {
       \# The deployment exists but it is configured to the desired hostbase url
       Write-Output "A deployment has already been created with the specified hostbase url on this server and will be used."
   }
   else
   {
       Write-Error "A deployment has already been created on this server with a different host base url."
   }
   <!--NeedCopy-->
  

• Creates a new authentication service if one does not exist at the specified virtual path. The default authentication method of username and password is enabled.

   \# Determine if the authentication service at the specified virtual path exists
   $authentication = Get-STFAuthenticationService -VirtualPath $authenticationVirtualPath
   if(-not $authentication)
   {
       \# Add an Authentication service using the IIS path of the Store appended with Auth
       $authentication = Add-STFAuthenticationService $authenticationVirtualPath
   }
   else
   {
       Write-Output "An Authentication service already exists at the specified virtual path and will be used."
   }
   <!--NeedCopy-->
  

• Creates the new store service configured with one XenDesktop controller with the servers defined in the array $XenDesktopServers at the specified virtual path if one does not already exist.

   \# Determine if the store service at the specified virtual path exists
   $store = Get-STFStoreService -VirtualPath $StoreVirtualPath
   if(-not $store)
   {
   \# Add a Store that uses the new Authentication service configured to publish resources from the supplied servers
   $store = Add-STFStoreService -VirtualPath $StoreVirtualPath -AuthenticationService $authentication -FarmName $Farmtype -FarmType $Farmtype -Servers $FarmServers -LoadBalance $LoadbalanceServers \`
           -Port $Port -SSLRelayPort $SSLRelayPort -TransportType $TransportType
   }
   else
   {
       Write-Output "A Store service already exists at the specified virtual path and will be used. Farm and servers will be appended to this store."
       \# Get the number of farms configured in the store
       $farmCount = (Get-STFStoreFarmConfiguration $store).Farms.Count
       \# Append the farm to the store with a unique name
       Add-STFStoreFarm -StoreService $store -FarmName "Controller$($farmCount + 1)" -FarmType $Farmtype -Servers $FarmServers -LoadBalance $LoadbalanceServers -Port $Port \`
           -SSLRelayPort $SSLRelayPort -TransportType $TransportType
   }
   <!--NeedCopy-->
  

• Adds a Citrix Receiver for Web service at the specified IIS virtual path to access applications published in the store created above.

   \# Determine if the receiver service at the specified virtual path exists
   $receiver = Get-STFWebReceiverService -VirtualPath $receiverVirtualPath
   if(-not $receiver)
   {
       \# Add a Receiver for Web site so users can access the applications and desktops in the published in the Store
       $receiver = Add-STFWebReceiverService -VirtualPath $receiverVirtualPath -StoreService $store
   }
   else
   {
       Write-Output "A Web Receiver service already exists at the specified virtual path and will be used."
   }
   <!--NeedCopy-->
  

• Enables XenApp services for the store so older Citrix Receiver or Citrix Workspace app clients can connect to published applications.

   \# Determine if PNA is configured for the Store service
   $storePnaSettings = Get-STFStorePna -StoreService $store
   if(-not $storePnaSettings.PnaEnabled)
   {
   \# Enable XenApp services on the store and make it the default for this server
   Enable-STFStorePna -StoreService $store -AllowUserPasswordChange -DefaultPnaService
   }
   <!--NeedCopy-->
  

Example: Create a remote access deployment

The following example builds on the previous script to add a deployment with remote access.

Before you begin, make sure you follow the steps detailed in Get Started with the SDK. This example can be customized using the methods described to produce a script for automating StoreFront deployment.

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.

Understand the script

This section explains what each part of the script produced by StoreFront is doing. This will help you with the customization of your own script.

• Sets the error handling requirements and import the required StoreFront modules. Imports are not required in newer versions of PowerShell.

   Param(
       [Parameter(Mandatory=$true)]
       [Uri]$HostbaseUrl,
       [Parameter(Mandatory=$true)]
       [long]$SiteId = 1,
       [string]$Farmtype = "XenDesktop",
       [Parameter(Mandatory=$true)]
       [string[]]$FarmServers,
       [string]$StoreVirtualPath = "/Citrix/Store",
       [bool]$LoadbalanceServers = $false,
       [int]$Port = 80,
       [int]$SSLRelayPort = 443,
       [ValidateSet("HTTP","HTTPS","SSL")]
       [string]$TransportType = "HTTP",
       [Parameter(Mandatory=$true)]
       [Uri]$GatewayUrl,
       [Parameter(Mandatory=$true)]
       [Uri]$GatewayCallbackUrl,
       [Parameter(Mandatory=$true)]
       [string[]]$GatewaySTAUrls,
       [string]$GatewaySubnetIP,
       [Parameter(Mandatory=$true)]
       [string]$GatewayName
   )
   Set-StrictMode -Version 2.0
  
   \# Any failure is a terminating failure.
   $ErrorActionPreference = 'Stop'
   $ReportErrorShowStackTrace = $true
   $ReportErrorShowInnerException = $true
   \# Import StoreFront modules. Required for versions of PowerShell earlier than 3.0 that do not support autoloading
   Import-Module Citrix.StoreFront
   Import-Module Citrix.StoreFront.Stores
   Import-Module Citrix.StoreFront.Roaming
   <!--NeedCopy-->
  

• Create an internal access StoreFront deployment by calling the previous examples script. The base deployment will be extended to support remote access.

   \# Create a simple deployment by invoking the SimpleDeployment example
   $scriptDirectory = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent
   $scriptPath = Join-Path $scriptDirectory "SimpleDeployment.ps1"
   & $scriptPath -HostbaseUrl $HostbaseUrl -SiteId $SiteId -FarmServers $FarmServers -StoreVirtualPath $StoreVirtualPath -Farmtype $Farmtype \`
       -LoadbalanceServers $LoadbalanceServers -Port $Port  -SSLRelayPort $SSLRelayPort -TransportType $TransportType
   <!--NeedCopy-->
  

• Gets services created in the simple deployment as they need to be updated to support the remote access scenario.

   \# Determine the Authentication and Receiver sites based on the Store
   $store = Get-STFStoreService -VirtualPath $StoreVirtualPath
   $authentication = Get-STFAuthenticationService -StoreService $store
   $receiverForWeb = Get-STFWebReceiverService -StoreService $store
   <!--NeedCopy-->
  

• Enables CitrixAGBasic on the Citrix Receiver for Web service required for remote access using Citrix Gateway. Get the Citrix Receiver for Web CitrixAGBasic and ExplicitForms authentication method from the supported protocols.

   \# Get the Citrix Receiver for Web CitrixAGBasic and ExplicitForms authentication method from the supported protocols
   \# Included for demonstration purposes as the protocol name can be used directly if known
   $receiverMethods = Get-STFWebReceiverAuthenticationMethodsAvailable | Where-Object { $_ -match "Explicit" -or $_ -match "CitrixAG" }
   \# Enable CitrixAGBasic in Receiver for Web (required for remote access)
   Set-STFWebReceiverService $receiverForWeb -AuthenticationMethods $receiverMethods
   <!--NeedCopy-->
  

• Enables CitrixAGBasic on the authentication service. This is required for remote access.

   \# Get the CitrixAGBasic authentication method from the protocols installed.
   \# Included for demonstration purposes as the protocol name can be used directly if known
   $citrixAGBasic = Get-STFAuthenticationProtocolsAvailable | Where-Object { $_ -match "CitrixAGBasic" }
   \# Enable CitrixAGBasic in the Authentication service (required for remote access)
   Enable-STFAuthenticationServiceProtocol -AuthenticationService $authentication -Name $citrixAGBasic
   <!--NeedCopy-->
  

• Adds a new remote access Gateway, adding the optional subnet ipaddress is supplied and registers it with the store to be accessed remotely.

   \# Add a new Gateway used to access the new store remotely
   Add-STFRoamingGateway -Name "NetScaler10x" -LogonType Domain -Version Version10_0_69_4 -GatewayUrl $GatewayUrl '
   \-CallbackUrl $GatewayCallbackUrl -SecureTicketAuthorityUrls $GatewaySTAUrls
   \# Get the new Gateway from the configuration (Add-STFRoamingGateway will return the new Gateway if -PassThru is supplied as a parameter)
   $gateway = Get-STFRoamingGateway -Name $GatewayName
   \# If the gateway subnet was provided then set it on the gateway object
   if($GatewaySubnetIP)
   {
       Set-STFRoamingGateway -Gateway $gateway -SubnetIPAddress $GatewaySubnetIP
   }
   \# Register the Gateway with the new Store
   Register-STFStoreGateway -Gateway $gateway -StoreService $store -DefaultGateway
   <!--NeedCopy-->
  

Example: Create a remote access deployment with optimal launch Gateway

The following example builds on the previous script to add a deployment with optimal launch Gateway remote access.

Before you begin, make sure you follow the steps detailed in Get Started with the SDK. This example can be customized using the methods described to produce a script for automating StoreFront deployment.

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.

Understand the script

This section explains what each part of the script produced by StoreFront is doing. This will help you with the customization of your own script.

• Sets the error handling requirements and imports the required StoreFront modules. Imports are not required in newer versions of PowerShell.

   Param(
       [Parameter(Mandatory=$true)]
       [Uri]$HostbaseUrl,
       [long]$SiteId = 1,
       [string]$Farmtype = "XenDesktop",
       [Parameter(Mandatory=$true)]
       [string[]]$FarmServers,
       [string]$StoreVirtualPath = "/Citrix/Store",
       [bool]$LoadbalanceServers = $false,
       [int]$Port = 80,
       [int]$SSLRelayPort = 443,
       [ValidateSet("HTTP","HTTPS","SSL")]
       [string]$TransportType = "HTTP",
       [Parameter(Mandatory=$true)]
       [Uri]$GatewayUrl,
       [Parameter(Mandatory=$true)]
       [Uri]$GatewayCallbackUrl,
       [Parameter(Mandatory=$true)]
       [string[]]$GatewaySTAUrls,
       [string]$GatewaySubnetIP,
       [Parameter(Mandatory=$true)]
       [string]$GatewayName,
       [Parameter(Mandatory=$true)]
       [Uri]$OptimalGatewayUrl,
       [Parameter(Mandatory=$true)]
       [string[]]$OptimalGatewaySTAUrls,
       [Parameter(Mandatory=$true)]
       [string]$OptimalGatewayName
   )
   Set-StrictMode -Version 2.0
   \# Any failure is a terminating failure.
   $ErrorActionPreference = 'Stop'
   $ReportErrorShowStackTrace = $true
   $ReportErrorShowInnerException = $true
   \# Import StoreFront modules. Required for versions of PowerShell earlier than 3.0 that do not support autoloading
   Import-Module Citrix.StoreFront
   Import-Module Citrix.StoreFront.Stores
   Import-Module Citrix.StoreFront.Roaming
   <!--NeedCopy-->
  

• Calls into the remote access deployment script to configure the basic deployment and add remote access.

   \# Create a remote access deployment
   $scriptDirectory = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent
   $scriptPath = Join-Path $scriptDirectory "RemoteAccessDeployment.ps1"
   & $scriptPath -HostbaseUrl $HostbaseUrl -SiteId $SiteId -FarmServers $FarmServers -StoreVirtualPath $StoreVirtualPath -Farmtype $Farmtype \`
       -LoadbalanceServers $LoadbalanceServers -Port $Port  -SSLRelayPort $SSLRelayPort -TransportType $TransportType \`
       -GatewayUrl $GatewayUrl -GatewayCallbackUrl $GatewayCallbackUrl -GatewaySTAUrls $GatewaySTAUrls -GatewayName $GatewayName
   <!--NeedCopy-->
  

• Adds the preferred optimal launch gateway and get it from the list of configured gateways.

   \# Add a new Gateway used for remote HDX access to desktops and apps
   $gateway = Add-STFRoamingGateway -Name $OptimalGatewayName -LogonType UsedForHDXOnly -GatewayUrl $OptimalGatewayUrl -SecureTicketAuthorityUrls $OptimalGatewaySTAUrls -PassThru
   <!--NeedCopy-->
  

• Gets the store service to use the optimal gateway, register it assigning it to launches from the farm named.

   \# Get the Store configured by SimpleDeployment.ps1
   $store = Get-STFStoreService -VirtualPath $StoreVirtualPath
   \# Register the Gateway with the new Store for launch against all of the farms (currently just one)
   $farmNames = @($store.FarmsConfiguration.Farms | foreach { $_.FarmName })
   Register-STFStoreOptimalLaunchGateway -Gateway $gateway -StoreService $store -FarmName $farmNames
   <!--NeedCopy-->