Guide du kit SDK autonome PowerShell Durable Functions

Le SDK PowerShell autonome Durable Functions (AzureFunctions.PowerShell.Durable.SDK) est l’approche recommandée pour la création d’applications Durable Functions avec PowerShell. Il remplace le Kit de développement logiciel (SDK) intégré par une logique de relecture plus rapide (le même moteur que le SDK isolé C#), le contrôle de version indépendant et la gestion améliorée des exceptions, la gestion des valeurs null et la sérialisation. Le Kit de développement logiciel (SDK) intégré reste disponible pour PowerShell 7.4 et versions antérieures, mais sera supprimé dans une prochaine version majeure de PowerShell Worker.

Liste des éléments à vérifier pour la migration

Utilisez la liste de contrôle suivante pour suivre votre progression à chaque étape de migration :

Installer le Kit de développement logiciel (SDK) autonome

Suivez ces étapes pour installer et activer le Kit de développement logiciel (SDK) autonome dans votre application existante.

Vérifier les prérequis

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

• Runtime Azure Functions v4.16+
• Azure Functions Core Tools v4.0.5095+ (en cas d’exécution locale)
• Application PowerShell Azure Functions pour PowerShell 7.4 ou version ultérieure

Activer le Kit de développement logiciel (SDK) 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 PowerShell versions 7.4 et ultérieures, 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 :

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

Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"ExternalDurablePowerShellSDK" = "'true'"}

Installer le package du Kit de développement logiciel (SDK)

Vous avez deux options pour installer le package sdk. Utilisez des dépendances managées (recommandées pour la plupart des applications) ou regroupez le module avec le contenu de votre application si vous devez épingler une version spécifique ou votre déploiement ne prend pas en charge les dépendances gérées. Une seule option est nécessaire.

Option 1 : Utiliser des dépendances managées (recommandé)

Pour installer le Kit de développement logiciel (SDK) en tant que dépendance managée, suivez les instructions relatives aux dépendances managées. Tout d’abord, vérifiez que votre host.json contient une section managedDependency avec enabled défini sur true:

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

Spécifiez ensuite une entrée pour le Kit de développement logiciel (SDK) dans votre requirements.psd1 fichier :

# 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 2 : Inclure le module SDK dans le contenu de votre application

Pour regrouper le Kit de développement logiciel (SDK) avec votre application, placez le package sdk à l’intérieur d’un ".\Modules" répertoire à la racine de votre application. Pour plus d’informations, consultez Inclure des modules dans le contenu de l’application.

À partir de la racine de votre application, créez le répertoire et téléchargez le Kit de développement logiciel (SDK) :

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

Importer le Kit de développement logiciel (SDK)

Ajoutez la ligne suivante à votre profile.ps1 fichier pour importer le Kit de développement logiciel (SDK) à chaque démarrage à froid :

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

Exécuter votre application

Démarrez votre application avec func host start. Le Kit de développement logiciel (SDK) autonome est désormais actif.

Migrer à partir du Kit de développement logiciel (SDK) intégré

Si vous migrez une application existante à partir du Kit de développement logiciel (SDK) intégré, passez en revue l’interface et les modifications comportementales suivantes.

Nouvelles applets de commande

Cmdlets modifiées

Changements comportementaux

Gestion des exceptions dans Wait-DurableTask

Les exceptions levées par les activités planifiées avec Wait-DurableTask (modèle fan-out/fan-in) ne sont plus ignorées en mode silencieux. L’applet de commande propage désormais l’exception à l’orchestrateur afin de pouvoir la gérer dans votre code.

Kit de développement logiciel (SDK) intégré : les exceptions ont été avalées silencieusement :

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

Kit de développement logiciel (SDK) autonome : les exceptions se propagent à l’orchestrateur :

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Valeurs null conservées dans les Wait-DurableTask résultats

Les valeurs null ne sont plus supprimées de la liste des résultats d’un appel WhenAll Wait-DurableTask. Un appel réussi sans l’indicateur -Any retourne désormais un tableau de la même taille que le nombre de tâches planifiées, y compris $null les entrées pour les activités qui ont retourné null.

Kit de développement logiciel (SDK) intégré : les résultats null ont été supprimés :

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

Kit de développement logiciel (SDK) autonome : les résultats null sont conservés :

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

Informations de référence sur le SDK

Pour obtenir la référence complète de l’applet de commande, consultez AzureFunctions.PowerShell.Durable.SDK Module. Après avoir importé le module, vous pouvez également exécuter Get-Help *-Durable* pour répertorier toutes les applets de commande disponibles ou Get-Help <cmdlet-name> -Full pour une utilisation détaillée.

Obtenir du support

Signalez les bogues et les demandes de fonctionnalités dans le dépôt GitHub du kit sdk.

Étapes suivantes

• Créer une application Durable Functions avec PowerShell
• Modèles et concepts Durable Functions
• Référence du développeur PowerShell pour Azure Functions