Durable Functions のスタンドアロン PowerShell SDK のガイド
PowerShell ギャラリー (AzureFunctions.PowerShell.Durable.SDK) のスタンドアロン パッケージとして、Durable Functions (DF) PowerShell SDK がプレビューとして使用できるようになりました。
この SDK パッケージが一般提供されると、PowerShell で Durable Functions アプリを作成するための推奨手段となります。 この記事では、この変更の利点と、この新しいパッケージを採用することで期待できる変化について説明します。
Note
このパッケージは現在プレビュー段階にあります。
スタンドアロン 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 ワーカーの組み込み DF SDK は、PowerShell 7.4、7.2 およびそれ以前のリリースでは引き続き使用できます。
最終的には、組み込みの SDK を使用せずに、PowerShell ワーカーの新しいメジャー バージョンをリリースする予定です。 この時点で、ユーザーは、このスタンドアロン パッケージを使用して別途 SDK をインストールする必要があります。インストール手順は以下のとおりです。
SDK をインストールして有効にする
既存のアプリに新しいスタンドアロン SDK をインストールして有効にする方法については、このセクションを参照してください。
前提条件
スタンドアロンの PowerShell SDK には、次の最小バージョンが必要です。
- Azure Functions Runtime v4.16 以降
- Azure Functions Core Tools v4.0.5095+ 以降 (ローカルで実行する場合)
- PowerShell 7.2 以降用の Azure Functions PowerShell アプリ
スタンドアロンの DF SDK へのオプトイン
スタンドアロン PowerShell SDK を実行するには、次のアプリケーション設定が必要です。
- 名前:
ExternalDurablePowerShellSDK - 値:
"true"
このアプリケーション設定では、組み込みの Durable SDK for PowerShell バージョン 7.2 以降が無効になり、ワーカーで外部 SDK を使用する必要があります。
Azure Functions Core Tools を使ってローカルで実行している場合は、この設定を local.settings.json ファイルに追加する必要があります。 Azure で実行している場合は、選んだツールを使って以下の手順を実行します。
<FUNCTION_APP_NAME> と <RESOURCE_GROUP_NAME> を実際の関数アプリとリソース グループの名前でそれぞれ置き換えます。
az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings ExternalDurablePowerShellSDK="true"
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' = '1.*'
}
インストール オプション 2: カスタム モジュールを使用する
スタンドアロン DF SDK をカスタム モジュールとしてインストールするには、アプリ レベルのモジュール フォルダーの作成に関するガイダンスに従う必要があります。 詳細については、前述のドキュメントを必ず確認してください。
要約すると、アプリのルートにある ".\Modules" ディレクトリの中に SDK パッケージを配置する必要があります。
例えば、アプリケーションのルート内から、".\Modules" ディレクトリを作成した後、次のようにスタンドアロン SDK を modules ディレクトリにダウンロードできます。
Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"
SDK のインポート
最後の手順では、SDK をコードのセッションにインポートします。 これを行うには、profile.ps1 ファイルで Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop を使用して 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 を利用する際に想定されるインターフェイスや動作変化について説明します。
新しいコマンドレット
Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input>は、ワークフローでサブオーケストレーターを利用できるようにする新しいコマンドレットです。
変更されたコマンドレット
- コマンドレット
Get-DurableTaskResult -Task <task>には、タスクのリストではなく、引数として表した 1 つのタスクのみを指定できるようになりました。
動作の変更
Wait-DurableTaskでスケジュールされたアクティビティ (ファンアウト/ファンイン パターンなど) によってスローされる例外は、自動的に無視されなくなりました。 代わりに、例外が発生すると、その例外はコマンドレットによってオーケストレーターに伝播され、ユーザーコードによって処理されるようになりました。Wait-DurableTask(つまり、WhenAll) 呼び出しの結果リストから Null 値が削除されなくなりました。 つまり、-Anyフラグを指定せずにWait-DurableTaskの呼び出しが成功すると、スケジュールされたタスクの数と同じサイズの配列が返されます。
サポートの利用、フィードバックの提供、変更の提案を行う場所について
このリリースのプレビュー フェーズでは、スタンドアロン SDK にさらなる変更が追加で導入される可能性があります。 これらの変更にはコミュニティの意見が反映される可能性があるため、フィードバックやご提案については、SDK の "新しい GitHub リポジトリ" にご報告ください。