Durable Functions のスタンドアロン PowerShell SDK のガイド

PowerShell を使用してDurable Functions アプリを作成するには、スタンドアロン Durable Functions PowerShell SDK (AzureFunctions.PowerShell.Durable.SDK) をお勧めします。 組み込みの SDK をより高速な再生ロジック (C# 分離 SDK と同じエンジン)、独立したバージョン管理、および改善された例外処理、null 値処理、シリアル化に置き換えます。 組み込みの SDK は PowerShell 7.4 以前で引き続き使用できますが、今後の PowerShell worker のメジャー リリースでは削除される予定です。

移行チェックリスト

次のチェックリストを使用して、各移行手順の進行状況を追跡します。

スタンドアロン SDK をインストールする

既存のアプリにスタンドアロン SDK をインストールして有効にするには、次の手順に従います。

前提条件の確認

スタンドアロンの PowerShell SDK には、次の最小バージョンが必要です。

• Azure Functions Runtime v4.16 以降
• Azure Functions Core Tools v4.0.5095+ 以降 (ローカルで実行する場合)
• PowerShell 7.4 以降用 Azure Functions PowerShell アプリ

スタンドアロン SDK を有効にする

スタンドアロン PowerShell SDK を実行するには、次のアプリケーション設定が必要です。

• 名前: ExternalDurablePowerShellSDK
• 値: "true"

このアプリケーション設定では、組み込みの Durable SDK for PowerShell バージョン 7.4 以降が無効になり、ワーカーは外部 SDK を使用する必要があります。

Azure Functions Core Tools を使ってローカルで実行している場合は、この設定を local.settings.json ファイルに追加する必要があります。 Azure で実行している場合は、選んだツールを使って以下の手順を実行します。

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'"}

SDK パッケージをインストールする

SDK パッケージをインストールするには、2 つのオプションがあります。 特定のバージョンをピン留めする必要がある場合、またはデプロイで マネージド依存関係 がサポートされていない場合は、マネージド依存関係 (ほとんどのアプリに推奨) を使用するか、 モジュールをアプリコンテンツとバンドル します。 必要なオプションは 1 つだけです。

オプション 1: マネージド依存関係を使用する (推奨)

マネージド依存関係として SDK をインストールするには、 マネージド依存関係のガイダンスに従います。 まず、host.jsonに、managedDependencyが enabled に設定されたtrue セクションが含まれていることを確認します。

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

次に、 requirements.psd1 ファイルで SDK のエントリを指定します。

# 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.*'
}

オプション 2: アプリのコンテンツに SDK モジュールを含める

SDK をアプリにバンドルするには、アプリのルートにある ".\Modules" ディレクトリ内に SDK パッケージを配置します。 詳細については、「 アプリ コンテンツにモジュールを含める」を参照してください。

アプリケーション ルートからディレクトリを作成し、SDK をダウンロードします。

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

SDK をインポートする

profile.ps1 ファイルに次の行を追加して、すべてのコールド スタートで SDK をインポートします。

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

アプリを実行する

func host startでアプリを起動します。 スタンドアロン SDK がアクティブになりました。

組み込みの SDK から移行する

組み込みの SDK から既存のアプリを移行する場合は、次のインターフェイスと動作の変更を確認してください。

新しいコマンドレット

変更されたコマンドレット

動作の変更

Wait-DurableTask の例外処理

Wait-DurableTask (ファンアウト/ファンイン パターン) でスケジュールされたアクティビティによってスローされる例外は、暗黙的に無視されなくなりました。 これで、コマンドレットによってオーケストレーターに例外が伝達され、コードで処理できるようになります。

組み込みのSDK — 例外が黙って飲み込まれた:

# 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

スタンドアロン SDK — 例外がオーケストレーターに伝達されます。

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: $_"
}

null 値はWait-DurableTaskの結果に保持される。

null 値は、 Wait-DurableTask (WhenAll) 呼び出しの結果リストから削除されなくなりました。 -Any フラグを指定せずに正常に呼び出されると、スケジュールされたタスクの数と同じサイズの配列が返されるようになりました。これには、null を返したアクティビティのエントリ$null含まれます。

組み込みの SDK — null の結果が削除されました。

# 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

スタンドアロン SDK — null の結果は保持されます。

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

SDK リファレンス

コマンドレットの完全なリファレンスについては、AzureFunctions.PowerShell.Durable.SDK モジュールを参照してください。 モジュールをインポートした後、 Get-Help *-Durable* を実行して使用可能なすべてのコマンドレットを一覧表示したり、 Get-Help <cmdlet-name> -Full して詳細な使用方法を確認したりすることもできます。

サポートを受ける

SDK の GitHub リポジトリでバグと機能要求を報告します。

次のステップ

• PowerShell を使用してDurable Functions アプリを作成します
• Durable Functions のパターンと概念
• Azure Functions 用 PowerShell 開発者リファレンス