Product Documentation

StoreFront SDK

Sep 22, 2016

Citrix StoreFront provides an SDK based on a number of Microsoft Windows PowerShell version 3.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.

Key differences between the StoreFront 3.0 and current StoreFront SDK

  • High-level SDK Examples - This version provides high-level SDK scripts that enable you to script and automate StoreFront deployments quickly and easily. You can tailor the high-level examples to your particular requirements enabling you to create a new deployment simply by running one script.
  • New low-level SDK - Citrix provides a documented low-level StoreFront SDK enabling the configuration of deployments including stores, authentication methods, Citrix Receiver for Web and Unified Citrix Receiver sites, as well as remote access with NetScaler Gateway.
  • Backwards Compatibility - StoreFront 3.6 still contains the StoreFront 3.0 and earlier APIs so existing scripts can be gradually transitioned to the new SDK.

Important

Backwards compatibility with StoreFront 3.0 has been maintained where possible and practicable. However, Citrix recommends when writing new scripts, use the new Citrix.StoreFront.* modules, as the StoreFront 3.0 SDK is deprecated and will  eventually be removed.. 

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. Start a shell in PowerShell 3.0.

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

  2. To use SDK cmdlets within scripts, set the execution policy in PowerShell.

    For more information about PowerShell execution policy, see your Microsoft documentation.

  3. Add the modules you require into the PowerShell environment using the Add -Module command in the Windows PowerShell console. For example, type:
    Import-Module Citrix.StoreFront
    

    To import all the cmdlets, type:

    Get-Module -ListAvailable | Where-Object { $_.Name.StartsWith("Citrix.StoreFront") } | Import-Module

After importing, you have access to the cmdlets and their associated help.

For an example of a typical use case, see Get started with the SDK.

Tip: For a complete listing of all help text for the cmdlets, see PowerShell cmdlet help at  https://www.citrix.com/downloads/storefront-web-interface/betas-and-tech-previews/.

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.

Examples

Description

<Example: Create a Simple Deployment>

Script: creates a simple deployment with a StoreFront controller configured with a single XenDesktop server.

<Example: Create a Remote Access Deployment>

Script: builds on the previous script to add remote access to the deployment.

<Example: Create a Remote Access Deployment with Optimal Launch Gateway>

Script: builds on the previous script to add preferred optimal launch gateways for a better user experience.

<Example: Create a Deployment with a Desktop Appliance Site>

Script: creates a simple deployment configured with a Desktop Appliance site.

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 Stared 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

  • Automates the virtual path of the authentication and Citrix Receiver for Web services based on the $StoreVirtualPath supplied.

# Determine the Authentication and Receiver virtual path to use based of the Store

$authenticationVirtualPath = "$($StoreIISPath.TrimEnd('/'))Auth"

$receiverVirtualPath = "$($StoreVirtualPath.TrimEnd('/'))Web"

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

# 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."

}

  • 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."

}

  • 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."

}

  • 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

}

  • 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."

}

  • Enables XenApp services for the store so older Citrix Receiver 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

}

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 Stared 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

  • 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

  • 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

  • Enables CitrixAGBasic on the Citrix Receiver for Web service required for remote access using NetScaler 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

  • 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

  • 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

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 Stared 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

  • 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

  • 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

  • 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

Example: Create a deployment with a Desktop Appliance site

TThe following example builds on the simple deployment example to add a deployment with Desktop Appliance site.

Before you begin, make sure you follow the steps detailed in  Get Stared 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,

    [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

  • Automate a desktop appliance path based on that of the $StoreVirtualPath.

$desktopApplianceVirtualPath = "$($StoreIISPath.TrimEnd('/'))Appliance"

  • Calls into the simple deployment script to configure a default deployment with the required services.

# 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

  • Gets the store service to use for the Desktop Appliance site. Use the Add-STFDesktopApplianceService cmdlet to add the new site with MultiDesktop and Explicit username and password authentication.

$store = Get-STFStoreService -VirtualPath $StoreVirtualPath

# Create a new Desktop Appliance site using the desktops published by the Store Service

Add-STFDesktopApplianceService -VirtualPath $desktopApplianceVirtualPath -StoreService $store -EnableExplicit