SDK StoreFront
Citrix StoreFront fournit un kit de développement logiciel (SDK) basé sur un certain nombre de modules Microsoft Windows PowerShell version 3.0. Avec le kit de développement, vous pouvez effectuer les mêmes tâches qu’avec la console MMC StoreFront, ainsi que les tâches que vous ne pouvez pas effectuer avec la console uniquement.
Pour la référence SDK, consultez SDK StoreFront.
Différences clés entre le kit de développement StoreFront 3.0 et celui de la version actuelle de StoreFront
- Exemples de SDK haut niveau : cette version propose des scripts SDK de haut niveau qui vous permettent de créer un script et d’automatiser les déploiements StoreFront rapidement et facilement. Vous pouvez personnaliser les exemples de haut niveau selon vos besoins spécifiques, ce qui vous permet de créer un nouveau déploiement simplement par l’exécution d’un script.
- Nouveau SDK de bas niveau : Citrix offre un SDK StoreFront de bas niveau documenté permettant la configuration de déploiements, notamment des magasins, des méthodes d’authentification, des sites Citrix Receiver pour Web et Citrix Receiver unifié ainsi que l’accès distant avec Citrix Gateway.
- Rétrocompatibilité : StoreFront 3.6 contient toujours les API de StoreFront 3.0 et versions antérieures, par conséquent les scripts existants peuvent être progressivement transférés vers le nouveau SDK.
Important :
La rétrocompatibilité avec StoreFront 3.0 a été maintenue dans la mesure du possible. Toutefois, lors de l’écriture de scripts, Citrix recommande d’utiliser les nouveaux modules Citrix.StoreFront.*, car le kit de développement logiciel (SDK) StoreFront 3.0 est obsolète et sera supprimé.
Utilisez le Kit de développement logiciel (SDK)
Le kit de développement logiciel comprend un certain nombre de composants logiciels enfichables PowerShell installés automatiquement par l’assistant d’installation lorsque vous installez différents composants StoreFront.
Pour accéder aux applets de commande et les exécuter :
-
Démarrez un shell dans PowerShell 3.0.
Vous devez exécuter le Shell ou le script en tant que membre du groupe d’administrateurs locaux sur le serveur StoreFront.
-
Pour utiliser les applets de commande du kit de développement dans des scripts, définissez la stratégie d’exécution dans PowerShell.
Pour plus d’informations sur la stratégie d’exécution PowerShell, veuillez consulter votre documentation Microsoft.
-
Ajoutez les modules dont vous avez besoin à l’environnement PowerShell en utilisant la commande Add -Module dans la console Windows PowerShell. Par exemple, entrez :
Import-Module Citrix.StoreFront
Pour importer toutes les applets de commande, entrez :
Get-Module -ListAvailable | Where-Object { $_.Name.StartsWith("Citrix.StoreFront") } | Import-Module
Après importation, vous avez accès aux applets de commande et à l’aide associée.
Démarrage avec SDK
Pour créer un script, réalisez les étapes suivantes :
- Utilisez un des exemples SDK fournis et installés par StoreFront dans le dossier %ProgramFiles%\Citrix\Receiver StoreFront\PowerShellSDK\Examples.
- Pour vous aider à personnaliser votre propre script, consultez l’exemple de script pour comprendre la fonction de chaque partie. Pour plus d’informations, consultez l’exemple de cas d’utilisation qui décrit en détail les actions du script.
- Convertissez et adaptez les exemples de script pour les changer en un script plus lisible. Pour ce faire :
- Utilisez PowerShell ISE ou un outil similaire pour modifier le script.
- Utilisez des variables pour affecter les valeurs à réutiliser ou modifier.
- Supprimez toute commande qui n’est pas requise.
- Notez que les applets de commande StoreFront peuvent être identifiées par le préfixe STF.
- Utilisez l’applet de commande Get-Help en fournissant le nom de la commande et le paramètre -Full pour de plus amples informations sur la commande.
Exemples
Remarque :
Lors de la création d’un script, pour vous assurer que vous obtiendrez toujours les dernières améliorations et derniers correctifs, Citrix vous recommande de suivre la procédure décrite ci-dessus, plutôt que de copier et de coller les scripts exemples.
Exemples | Description |
---|---|
Créer un déploiement simple | Script : crée un déploiement simple avec un contrôleur StoreFront configuré avec un seul serveur XenDesktop. |
Créer un déploiement avec accès à distance | Script : basé sur le script précédent, ajoute l’accès à distance au déploiement. |
Créer un déploiement avec accès à distance et passerelle de lancement optimale | Script : basé sur le script précédent, ajoute des passerelles de lancement optimales pour une meilleure expérience utilisateur. |
Exemple : Créer un déploiement simple
L’exemple suivant illustre comment créer un déploiement simple configuré avec un Controller XenDesktop.
Avant de commencer, suivez les étapes détaillées dans Démarrage avec SDK. Cet exemple peut être personnalisé à l’aide des méthodes décrites pour produire un script qui automatise le déploiement StoreFront.
Remarque :
Pour vous assurer que vous obtiendrez toujours les dernières améliorations et correctifs, Citrix vous recommande de suivre la procédure décrite dans ce document, plutôt que de copier et de coller le script exemple.
Compréhension du script
Cette section décrit la fonction de chaque partie du script généré par StoreFront. Ceci vous aidera à la personnalisation de votre propre script.
-
Définit la gestion des erreurs et importe les modules StoreFront requis. Les importations ne sont pas nécessaires dans des versions plus récentes de 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-->
-
Automatise le chemin d’accès virtuel de l’authentification et des services Citrix Receiver pour Web basé sur le paramètre $StoreIISPath fourni. $StoreVirtualPath est équivalent à $StoreIISpath car les chemins virtuels sont toujours le chemin dans IIS. Par conséquent, dans Powershell, ils ont une valeur telle que « /Citrix/Store », « /Citrix/StoreWeb », ou « /Citrix/StoreAuth ».
# Determine the Authentication and Receiver virtual path to use based of the Store $authenticationVirtualPath = "$($StoreIISPath.TrimEnd('/'))Auth" $receiverVirtualPath = "$($StoreVirtualPath.TrimEnd('/'))Web" <!--NeedCopy-->
-
Crée un nouveau déploiement, si ce n’est pas déjà fait, pour préparer l’ajout des services StoreFront requis. -Confirm:$false supprime le besoin de confirmer que le déploiement peut se poursuivre.
# 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-->
-
Crée un nouveau service d’authentification s’il n’en n’existe aucun dans le chemin d’accès virtuel spécifié. La méthode d’authentification par défaut, nom d’utilisateur et mot de passe, est activée.
# 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-->
-
Crée le nouveau service de magasin configuré avec un Controller XenDesktop avec les serveurs définis dans le tableau $XenDesktopServers dans le chemin d’accès virtuel spécifié s’il n’en n’existe aucun.
# 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-->
-
Ajoute un service Citrix Receiver pour Web au chemin d’accès virtuel IIS spécifié pour accéder aux applications publiées dans le magasin créé ci-dessus.
# 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-->
-
Active les services XenApp pour le magasin de sorte que les anciennes versions des clients de Citrix Receiver ou de l’application Citrix Workspace puissent se connecter aux applications publiées.
# 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-->
Créer un déploiement avec accès à distance
L’exemple suivant est basé sur le script précédent et ajoute un déploiement avec accès à distance.
Avant de commencer, suivez les étapes détaillées dans Démarrage avec SDK. Cet exemple peut être personnalisé à l’aide des méthodes décrites pour produire un script qui automatise le déploiement StoreFront.
Remarque :
Pour vous assurer que vous obtiendrez toujours les dernières améliorations et correctifs, Citrix vous recommande de suivre la procédure décrite dans ce document, plutôt que de copier et de coller le script exemple.
Compréhension du script
Cette section décrit la fonction de chaque partie du script généré par StoreFront. Ceci vous aidera à la personnalisation de votre propre script.
-
Définit la gestion des erreurs et importe les modules StoreFront requis. Les importations ne sont pas nécessaires dans des versions plus récentes de 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-->
-
Créez un déploiement StoreFront avec accès en interne en appelant les exemples précédents de script. Le déploiement de base sera étendu pour prendre en charge l’accès distant.
# 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-->
-
Obtient les services créés dans le déploiement simple car ils doivent être mis à jour pour prendre en charge le scénario d’accès à distance.
# 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-->
-
Active CitrixAGBasic sur le service Citrix Receiver pour Web requis pour l’accès à distance à l’aide de Citrix Gateway. Obtenir la méthode d’authentification ExplicitForms et CitrixAGBasic de Citrix Receiver pour Web à partir des protocoles pris en charge.
# 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-->
-
Active CitrixAGBasic sur le service d’authentification. Requis pour l’accès distant.
# 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-->
-
Ajoute une passerelle d’accès à distance, en ajoutant l’adresse IP de sous-réseau facultative qui est fournie et en l’enregistrant auprès du magasin auquel accéder à distance.
# 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-->
Exemple : Créer un déploiement avec accès à distance et passerelle de lancement optimale
L’exemple suivant est basé sur le script précédent et ajoute un déploiement avec accès à distance et passerelle de lancement optimale.
Avant de commencer, suivez les étapes détaillées dans Démarrage avec SDK. Cet exemple peut être personnalisé à l’aide des méthodes décrites pour produire un script qui automatise le déploiement StoreFront.
Remarque :
Pour vous assurer que vous obtiendrez toujours les dernières améliorations et correctifs, Citrix vous recommande de suivre la procédure décrite dans ce document, plutôt que de copier et de coller le script exemple.
Compréhension du script
Cette section décrit la fonction de chaque partie du script généré par StoreFront. Ceci vous aidera à la personnalisation de votre propre script.
-
Définit la gestion des erreurs et importe les modules StoreFront requis. Les importations ne sont pas nécessaires dans des versions plus récentes de 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-->
-
Appels dans le script de déploiement avec accès à distance pour configurer le déploiement de base et ajouter l’accès à distance.
# 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-->
-
Ajoute la passerelle de lancement optimale préférée à partir de la liste de passerelles configurées.
# 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-->
-
Oblige le service de magasin à utiliser la passerelle optimale, l’enregistrer, et l’attribuer aux lancements depuis la batterie désignée.
# 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-->
Exemple : échange des métadonnées entre le fournisseur d’identité et le fournisseur de services (StoreFront) pour l’authentification SAML
L’authentification SAML peut être configurée dans la console de gestion StoreFront (consultez Configurer le service d’authentification) ou à l’aide des applets de commande PowerShell suivantes :
- Export-STFSamlEncryptionCertificate
- Export-STFSamlSigningCertificate
- Import-STFSamlEncryptionCertificate
- Import-STFSamlSigningCertificate
- New-STFSamlEncryptionCertificate
- Nouveau-STFSamlIdPCertificate
- New-STFSamlSigningCertificate
Vous pouvez utiliser l’applet de commande, Update-STFSamlIdPFromMetadata, pour échanger des métadonnées (identificateurs, certificats, points de terminaison et autres configurations) entre le fournisseur d’identité et le fournisseur de services, qui est StoreFront dans ce cas.
Pour un magasin StoreFront, appelé « Store », avec son propre service d’authentification, le point de terminaison de métadonnées sera :
https://<storefront host>/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata
Si votre fournisseur d’identité prend en charge l’importation de métadonnées, vous pouvez également le pointer sur l’adresse URL ci-dessus. Remarque : cette opération doit être effectuée sur HTTPS.
Pour que StoreFront utilise les métadonnées d’un fournisseur d’identité, vous pouvez utiliser le PowerShell suivant :
Get-Module "Citrix.StoreFront*" -ListAvailable | Import-Module
# Remember to change this with the virtual path of your Store.
$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
# To read the metadata directly from the Identity Provider, use the following:
# Note again this is only allowed for https endpoints
Update-STFSamlIdPFromMetadata -AuthenticationService $auth -Url https://example.com/FederationMetadata/2007-06/FederationMetadata.xml
# If the metadata has already been download, use the following:
# Note: Ensure that the file is encoded as UTF-8
Update-STFSamlIdPFromMetadata -AuthenticationService $auth -FilePath "C:\Users\exampleusername\Downloads\FederationMetadata.xml"
<!--NeedCopy-->
Exemple : répertorier les métadonnées et les points de terminaison ACS d’un magasin spécifié pour l’authentification SAML
Vous pouvez utiliser le script suivant pour répertorier les métadonnées et les points de terminaison ACS (service consommateur d’assertion) pour un magasin spécifié.
# Change this value for your Store
$storeVirtualPath = "/Citrix/Store"
$auth = Get-STFAuthenticationService -Store (Get-STFStoreService -VirtualPath $storeVirtualPath)
$spId = $auth.AuthenticationSettings["samlForms"].SamlSettings.ServiceProvider.Uri.AbsoluteUri
$acs = New-Object System.Uri $auth.Routing.HostbaseUrl, ($auth.VirtualPath + "/SamlForms/AssertionConsumerService")
$md = New-Object System.Uri $auth.Routing.HostbaseUrl, ($auth.VirtualPath + "/SamlForms/ServiceProvider/Metadata")
$samlTest = New-Object System.Uri $auth.Routing.HostbaseUrl, ($auth.VirtualPath + "/SamlTest")
Write-Host "SAML Service Provider information:
Service Provider ID: $spId
Assertion Consumer Service: $acs
Metadata: $md
Test Page: $samlTest"
<!--NeedCopy-->
Exemple de sortie :
SAML Service Provider information:
Service Provider ID: https://storefront.example.com/Citrix/StoreAuth
Assertion Consumer Service: https://storefront.example.com/Citrix/StoreAuth/SamlForms/AssertionConsumerService
Metadata: https://storefront.example.com/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata
Test Page: https://storefront.example.com/Citrix/StoreAuth/SamlTest
<!--NeedCopy-->