StoreFront PowerShell modules

Citrix StoreFront provides a number of Microsoft Windows PowerShell version 2.0 modules that are included when you install StoreFront. With the modules, you can perform the same tasks as you would with the StoreFront management console, together with tasks you cannot do with the console alone.

Note:

The StoreFront PowerShell modules are not compatible with PowerShell 6 or higher.

For the PowerShell modules reference, see StoreFront developer documentation.

Get started

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 cmdlets within scripts, set the execution policy in PowerShell to RemoteSigned. For more information about PowerShell execution policy, see Microsoft documentation.

4. You can use the Example scripts as a starting point.

5. Use the Get-Help cmdlet supplying the cmdlet name and -Full parameter for more information on a specific command.

Virtual Path

Cmdlets to get or create a store, website or authentication services take a VirtualPath parameter. This is the path to where the application is hosted within IIS. The store and website path can also be found in StoreFront management console. Typically, by convention the auth path is the same as the store path with suffix Auth and the website is the same as the store path with the suffix Web. E.g. for store virtual path /Citrix/Store, the auth service has path /Citrix/StoreAuth and the website has path /Citrix/StoreWeb.

E.g. to get a store service whose path is /Citrix/Store, run command:

Get-STFStoreService -VirtualPath '/Citrix/Store'
<!--NeedCopy-->

If you omit the VirtualPath then it returns all services. If there is only one service, then PowerShell treats this as a single object.

Site ID

Some cmdlets include a SiteId parameter. If you have multiple deployments on the same server on different IIS sites then you must specify the SiteId. If you only have one site then the parameter is not required.

Example scripts

StoreFront includes a few example scripts which can be found in the %ProgramFiles%\Citrix\Receiver StoreFront\PowerShellSDK\Examples folder. You can use these as templates for creating your own scripts.

-  Use the PowerShell ISE, Visual Studio Code 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.

Create a simple deployment

The following example shows how to create a simple deployment configured with one CVAD site.

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

This section explains what each part of the script 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 modern 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 in 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 site (also known as a farm) 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 website 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. This example can be customized using the methods described to produce a script for automating StoreFront deployment.

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 modern 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. This example can be customized using the methods described to produce a script for automating StoreFront deployment.

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 modern 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 site 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-->