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

Durable Functions (DF) PowerShell SDK は、PowerShell ギャラリーのスタンドアロン モジュールとして使用できるようになりました: AzureFunctions.PowerShell.Durable.SDK。 この SDK は 現在一般公開 (GA) されており、PowerShell を使用して Durable Functions アプリを作成するための推奨される方法です。 この記事では、この変更の利点と、この新しいパッケージを採用することで期待できる変化について説明します。

スタンドアロン SDK が開発された理由について

以前の DF SDK は、PowerShell 言語ワーカーに組み込まれていました。 このアプローチを取ることは、Azure Functions PowerShell ユーザーにとって、Durable Functions アプリをすぐに作成できるという利点がありました。 しかし、これには次のような様々な欠点もありました。

• 新機能、バグ修正、その他の変更は、PowerShell ワーカーのリリース周期に依存することになります。
• PowerShell ワーカーの自動アップグレードの性質上、動作の変更が破壊的変更となる可能性があるため、DF SDK はバグ修正に慎重にならざるを得ませんでした。
• 組み込みの DF SDK で使用されるリプレイ アルゴリズムは時代遅れとなっています。他の DF SDK では、より高速で信頼性の高い実装が既に使用されています。

スタンドアロンの DF PowerShell SDK パッケージを作成することで、これらの欠点を克服することができました。 この新しいスタンドアロン SDK パッケージを使用する利点は次のとおりです。

• この SDK には、例外や NULL 値の処理の改善、シリアライズの修正など、要望の多かった多くの改善が含まれています。
• このパッケージは、PowerShell ワーカーとは独立してバージョン管理されています。 これにより、ユーザーは新機能や修正が利用可能になるとすぐに取り入れることができるだけでなく、自動アップグレードによる破壊的変更を避けることもできます。
• リプレイ ロジックには C# 用の DF から分離された SDK と同じ再生エンジンが使用されており、より高速で信頼性の高いものとなっています。

組み込みの DF PowerShell SDK の非推奨計画

PowerShell worker の組み込みの DF SDK は、PowerShell 7.4 以前のリリースで引き続き使用できます。

最終的には、組み込みの SDK を使用せずに、PowerShell ワーカーの新しいメジャー バージョンをリリースする予定です。 この時点で、ユーザーは、このスタンドアロン パッケージを使用して別途 SDK をインストールする必要があります。インストール手順は以下のとおりです。

SDK をインストールして有効にする

既存のアプリに新しいスタンドアロン SDK をインストールして有効にする方法については、このセクションを参照してください。

前提条件

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

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

スタンドアロンの DF SDK へのオプトイン

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

• 名前: ExternalDurablePowerShellSDK
• 値: "true"

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

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

Azure CLI

<FUNCTION_APP_NAME> と <RESOURCE_GROUP_NAME> を実際の関数アプリとリソース グループの名前でそれぞれ置き換えます。

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

Azure PowerShell

<FUNCTION_APP_NAME> と <RESOURCE_GROUP_NAME> を実際の関数アプリとリソース グループの名前でそれぞれ置き換えます。

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

VS Code

1. VS Code 用 Azure Functions 拡張機能がインストールされていることを確認します
2. F1 キーを押してコマンド パレットを開きます。 コマンド パレットで、Azure Functions: Add New Setting... を検索して選択します。
3. プロンプトが表示されたら、サブスクリプションと関数アプリを選びます
4. 名前には「ExternalDurablePowerShellSDK」と入力し、Enter キーを押します。
5. 値には "true" と入力し、Enter キーを押します。

SDK をインストールしてインポートする

SDK パッケージをインストールするには、マネージド依存関係を使用してインストールするか、アプリ コンテンツにバンドルされるかの 2 つのオプションがあります。 このセクションでは、両方のオプションについて説明しますが、必要なのはどちらか一方だけです。

インストール オプション 1: マネージド依存関係を使用する

マネージド依存関係として SDK をインストールするには、マネージド依存関係のガイダンスに従う必要があります。 詳細については、ガイダンスを参照してください。 要約すると、まず、host.json に managedDependency セクションがあり、enabled プロパティが true に設定されていることを確認する必要があります。 以下は、この要件を満たす host.json の例です。

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

その後は、以下の例のように、requirements.psd1 ファイルに DF 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 モジュールを含める

スタンドアロン DF SDK をアプリ コンテンツに含めるには、アプリ コンテンツに モジュールを含める方法に関するガイダンスに従う必要があります。 詳細については、前述のドキュメントを必ず確認してください。 要約すると、アプリのルートにある ".\Modules" ディレクトリの中に SDK パッケージを配置する必要があります。

例えば、アプリケーションのルート内から、".\Modules" ディレクトリを作成した後、次のようにスタンドアロン SDK を modules ディレクトリにダウンロードできます。

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

SDK のインポート

最後の手順では、SDK をコードのセッションにインポートします。 これを行うには、Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop ファイルで profile.ps1 を使用して PowerShell SDK をインポートします。 たとえば、アプリがテンプレートを使用してスキャフォールディングされている場合、profile.ps1 ファイルは次のようになっている可能性があります。

# 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

これらは、次の PowerShell SDK を利用するために必要なすべての手順です。 ターミナルで func host start を使用して、通常どおりにアプリを実行し、SDK の使用を開始します。

SDK リファレンス

SDK コマンドレットとそのパラメーターの完全なリファレンスについては、 AzureFunctions.PowerShell.Durable.SDK モジュール を参照してください。

Get-Help コマンドレットを使用して、SDK コマンドレットの詳細な説明を取得することもできます。 これを行うには、前のセクションに示すように、最初にモジュールをインポートする必要があります。 その後、次のコマンドを実行して、コマンドレットの一覧全体を取得できます。

Get-Help *-Durable*

使用例など、特定のコマンドレットに関する詳細なヘルプを表示するには、次を実行します。

Get-Help Invoke-DurableOrchestration -Full

移行ガイド

このセクションでは、新しい SDK を利用する際に想定されるインターフェイスや動作変化について説明します。

新しいコマンドレット

• Invoke-DurableSubOrchestrator は、ユーザーがワークフローでサブオーケストレーターを利用できるようにする新しいコマンドレットです。
• Suspend-DurableOrchestration Resume-DurableOrchestrationは、ユーザーがそれぞれオーケストレーションを中断および再開できるようにする新しいコマンドレットです。

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

• Get-DurableTaskResult コマンドレットは、タスクの一覧を受け入れる代わりに、引数として 1 つの Task のみを受け入れるようになりました。
• New-DurableRetryOptions コマンドレットの名前が New-DurableRetryPolicy に変更されました (旧バージョンとの互換性のために古い名前のエイリアスが提供されます)。

動作の変更

• Wait-DurableTask でスケジュールされたアクティビティ (ファンアウト/ファンイン パターンなど) によってスローされる例外は、自動的に無視されなくなりました。 代わりに、例外の場合、コマンドレットはその例外をオーケストレーターに伝達して、ユーザー コードで処理できるようにします。
• Wait-DurableTask (つまり、WhenAll) 呼び出しの結果リストから Null 値が削除されなくなりました。 つまり、Wait-DurableTask フラグを指定せずに -Any の呼び出しが成功すると、スケジュールされたタスクの数と同じサイズの配列が返されます。

サポートを受け、フィードバックを提供する

SDK の GitHub リポジトリにフィードバックや提案を報告してください。