Guide du kit SDK autonome PowerShell Durable Functions

  • Article

Le kit SDK PowerShell Durable Functions (DF) est désormais disponible en préversion sous la forme d’un package autonome dans PowerShell Gallery : AzureFunctions.PowerShell.Durable.SDK. Une fois que ce package SDK sera mis en disponibilité générale, il s’agira de la méthode recommandée pour créer des applications Durable Functions avec PowerShell. Dans cet article, nous vous expliquons les avantages de ce changement et ce à quoi vous pouvez vous attendre en adoptant ce nouveau package.

Notes

Ce package est actuellement en préversion.

Arguments en faveur du kit SDK autonome

Le SDK DF précédent était intégré au Worker du langage PowerShell. Cette approche présentait l’avantage de permettre aux utilisateurs PowerShell sur Azure Functions de créer des applications Durable Functions clé en main. Or, elle s’accompagnait aussi de diverses lacunes, à savoir :

  • Les nouvelles fonctionnalités, les correctifs de bogues et autres modifications dépendaient de la cadence de publication du Worker PowerShell.
  • Compte tenu du fait que la mise à niveau du Worker PowerShell est automatique, le kit SDK DF devait obéir à une posture prudente quant à la résolution des bogues, car tout changement de comportement pouvait constituer un changement cassant.
  • L’algorithme de relecture utilisé par le SDK DF intégré était obsolète : d’autres SDK DF utilisaient déjà une implémentation plus rapide et plus fiable.

En créant un package SDK PowerShell DF autonome, nous pouvons combler ces lacunes. Voici les avantages conférés par l’utilisation de ce nouveau package SDK autonome :

  • Ce kit SDK propose de nombreuses améliorations très demandées, notamment une meilleure gestion des exceptions et des valeurs null, ainsi que des correctifs de sérialisation.
  • Le package est versionné indépendamment du Worker PowerShell. Cela permet aux utilisateurs d’incorporer les nouvelles fonctionnalités et les nouveaux correctifs dès qu’ils sont disponibles, tout en évitant les changements cassants des mises à niveau automatiques.
  • La logique de relecture est plus rapide et plus fiable : elle utilise le même moteur de relecture que le SDK DF isolé pour C#.

Plan de dépréciation du kit SDK PowerShell DF intégré

Le kit de développement logiciel (SDK) DF intégré au Worker PowerShell restera disponible pour PowerShell 7.4, 7.2 et les versions antérieures.

Nous prévoyons de publier à terme une nouvelle version majeure du Worker PowerShell sans le kit de développement logiciel (SDK) intégré. À ce moment-là, les utilisateurs devront installer le kit de développement logiciel (SDK) séparément en utilisant ce package autonome ; les étapes d’installation sont décrites ci-dessous.

Installer et activer le SDK

Consultez cette section pour savoir comment installer et activer le nouveau SDK autonome dans votre application existante.

Prérequis

Le kit SDK PowerShell autonome nécessite les versions minimales suivantes :

Accepter le SDK DF autonome

Le paramétrage d’application suivant est nécessaire pour exécuter le kit de développement logiciel (SDK) PowerShell autonome :

  • Nom : ExternalDurablePowerShellSDK
  • Valeur: "true"

Ce paramétrage d’application désactive le kit de développement logiciel (SDK) Durable intégré pour les versions 7.2 et ultérieures de PowerShell, forçant le Worker à utiliser le kit de développement logiciel (SDK) externe.

Si vous exécutez localement à l’aide de Azure Functions Core Tools, vous devez ajouter ce paramètre à votre fichier local.settings.json. Si vous exécutez dans Azure, procédez comme suit avec l’outil de votre choix :

Remplacez <FUNCTION_APP_NAME> et <RESOURCE_GROUP_NAME> par le nom de votre application de fonction et du groupe de ressources, respectivement.

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings ExternalDurablePowerShellSDK="true"

Installer et importer le SDK

Deux options s’offrent à vous pour installer le package SDK : vous pouvez l’installer en tant que dépendance managée ou en tant que module personnalisé. Dans cette section, nous décrivons les deux options, mais une seule d’entre elles est nécessaire.

Option d’installation 1 : Utiliser des dépendances managées

Pour installer le SDK en tant que dépendance managée, vous devez suivre les recommandations concernant les dépendances managées. Pour plus d’informations, passez en revue les recommandations. En résumé, vous devez d’abord vérifier que votre host.json contient une section managedDependency avec une propriété enabled définie sur true. Voici un exemple de host.json qui satisfait à cette exigence :

{
  "version": "2.0",
  "managedDependency": {
    "enabled": true
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  },
}

Il vous suffit ensuite de spécifier une entrée pour le SDK DF dans votre fichier requirements.psd1, comme dans l’exemple ci-dessous :

# This file enables modules to be automatically managed by the Functions service.
# See https://aka.ms/functionsmanageddependency for additional information.
#
@{
    # For latest supported version, go to 'https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK/'.
    'AzureFunctions.PowerShell.Durable.SDK' = '1.*'
}

Option d’installation 2 : Utiliser des modules personnalisés

Pour installer le SDK DF autonome en tant que module personnalisé, vous devez suivre les recommandations relatives à la création d’un dossier modules au niveau de l’application. Pour plus d’informations, veillez à consulter la documentation susmentionnée. En résumé, vous devez placer le package SDK dans un répertoire ".\Modules" situé à la racine de votre application.

Par exemple, depuis la racine de votre application, et après avoir créé un répertoire ".\Modules", vous pouvez télécharger le SDK autonome dans le répertoire modules comme suit :

Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"

Importation du SDK

La dernière étape consiste à importer le SDK dans la session de votre code. Pour ce faire, importez le SDK PowerShell via Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop dans votre fichier profile.ps1. Par exemple, si votre application a été créée via des modèles, votre fichier profile.ps1 finalisé peut présenter comme suit :

# Azure Functions profile.ps1
#
# This profile.ps1 will get executed every "cold start" of your Function App.
# "cold start" occurs when:
#
# * A Function App starts up for the very first time
# * A Function App starts up after being de-allocated due to inactivity
#
# You can define helper functions, run commands, or specify environment variables
# NOTE: any variables defined that are not environment variables will get reset after the first execution

# Authenticate with Azure PowerShell using MSI.
# Remove this if you are not planning on using MSI or Azure PowerShell.
if ($env:MSI_SECRET) {
    Disable-AzContextAutosave -Scope Process | Out-Null
    Connect-AzAccount -Identity
}

# Uncomment the next line to enable legacy AzureRm alias in Azure PowerShell.
# Enable-AzureRmAlias

# You can also define functions or aliases that can be referenced in any of your PowerShell functions.

# Import standalone PowerShell SDK
Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

Voici toutes les étapes à respecter pour utiliser le prochaine SDK PowerShell. Pour commencer à utiliser le SDK, exécutez votre application comme d’habitude, en utilisant func host start dans votre terminal.

Guide de migration

Dans cette section, nous décrivons l’interface et les changements de comportement auxquels vous pouvez vous attendre en utilisant le nouveau SDK.

Nouvelles applets de commande

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> est une nouvelle applet de commande qui permet aux utilisateurs d’utiliser des sous-orchestrateurs dans leurs workflows.

Applets de commande modifiées

  • L’applet de commande Get-DurableTaskResult -Task <task> n’accepte désormais qu’une seule tâche comme argument, et non une liste de tâches comme auparavant.

Changements de comportement

  • Les exceptions déclenchées par les activités planifiées avec Wait-DurableTask (comme dans le modèle Fan-Out/Fan-In) ne sont plus ignorées en mode silencieux. Au lieu de cela, en cas d’exception, l’applet de commande propage cette exception à l’orchestrateur afin qu’elle puisse être gérée par le code utilisateur.
  • Les valeurs null ne sont plus supprimées de la liste de résultats d’un appel Wait-DurableTask (par exemple, WhenAll). Cela signifie qu’un appel réussi de Wait-DurableTask sans l’indicateur -Any doit retourner un tableau de la même taille que le nombre de tâches planifiées.

Où obtenir du support, adresser des commentaires et suggérer des modifications

Pendant sa phase de préversion, le SDK autonome peut introduire quelques modifications supplémentaires. Sachant que ces modifications peuvent être influencées par la communauté, n’hésitez pas à nous communiquer vos commentaires et suggestions dans le nouveau dépôt GitHub du SDK.