Partager via

Guide du kit SDK autonome PowerShell Durable Functions

Le Kit de développement logiciel (SDK) PowerShell Durable Functions (DF) est désormais disponible en tant que module autonome dans PowerShell Gallery : AzureFunctions.PowerShell.Durable.SDK. Ce Kit de développement logiciel (SDK) est désormais en disponibilité générale et est l’approche recommandée pour la création d’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.

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é dans powerShell Worker reste disponible pour PowerShell 7.4 et les versions antérieures.

Nous prévoyons éventuellement de publier une nouvelle version majeure du Worker PowerShell sans Kit de développement logiciel (SDK) intégré. À ce stade, les utilisateurs devraient installer séparément le SDK à l’aide de ce package autonome. Les étapes d’installation sont détaillées 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ètre d’application suivant est requis pour exécuter le SDK PowerShell autonome :

  • Nom : ExternalDurablePowerShellSDK
  • Valeur: "true"

Ce paramètre d’application désactive le Kit de développement logiciel (SDK) durable intégré pour Les versions 7.4 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 les noms 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 sont possibles pour l’installation du package SDK : il peut être installé à l’aide des dépendances managées, ou être regroupé avec le contenu de votre application. 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' = '2.*'
}

Option d’installation 2 : Inclure le module SDK dans le contenu de votre application

Pour inclure le Kit de développement logiciel (SDK) DF autonome dans le contenu de votre application, vous devez suivre les instructions relatives à l’inclusion de modules dans le contenu 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.

Informations de référence sur le SDK

Consultez le module AzureFunctions.PowerShell.Durable.SDK pour obtenir la référence complète des applets de commande du SDK et de leurs paramètres.

Vous pouvez également utiliser l’applet Get-Help de commande pour obtenir des descriptions détaillées des applets de commande du Kit de développement logiciel (SDK). Pour ce faire, vous devez d’abord importer le module, comme indiqué dans la section précédente. Après cela, vous pouvez exécuter la commande suivante pour obtenir la liste complète des applets de commande :

Get-Help *-Durable*

Pour obtenir une aide détaillée sur une applet de commande spécifique, notamment des exemples d’utilisation, exécutez :

Get-Help Invoke-DurableOrchestration -Full

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 est un nouveau cmdlet qui permet aux utilisateurs d’utiliser des sous-automatiseurs dans leurs flux de travail.
  • Suspend-DurableOrchestration et Resume-DurableOrchestration sont de nouvelles applets de commande qui permettent aux utilisateurs de suspendre et de reprendre des orchestrations, respectivement.

Cmdlets modifiées

  • L’applet Get-DurableTaskResult de commande accepte désormais une seule tâche en tant qu’argument, au lieu d’accepter une liste de tâches.
  • L’applet New-DurableRetryOptions de commande est renommée New-DurableRetryPolicy (un alias pour l’ancien nom est fourni pour la compatibilité rétroactive).

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, sur une 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.

Obtenir du support et fournir un retour d'information

Veuillez signaler tous les commentaires et suggestions au dépôt GitHub du SDK.

  • Last updated on