Azure Functions と .NET アスパイア (プレビュー)

2025-05-13

.NET Aspire は、クラウドでの分散アプリケーションの開発を簡略化する独断的なスタックです。 .NET Aspire と Azure Functions の統合により、.NET Aspire アプリホストの一部として Azure Functions .NET プロジェクトを開発、デバッグ、調整できます。

Von Bedeutung

.NET Aspire と Azure Functions の統合は現在プレビュー段階であり、変更される可能性があります。

[前提条件]

.NET Aspire で Azure Functions を使用するための開発環境を設定します。

.NET 9 SDK と .NET Aspire 9.0 以降をインストールします。 .NET 9 SDK は必須ですが、.NET Aspire 9.0 では .NET 8 および .NET 9 フレームワークがサポートされています。
Visual Studio を使用する場合は、バージョン 17.12 以降に更新してください。また、Visual Studio 用 Azure Functions ツールの最新バージョンも必要です。更新プログラムを確認するには:
1. [ツール]>[オプション] に移動します。
2. [ プロジェクトとソリューション] で、[ Azure Functions] を選択します。
3. [更新プログラムの確認] を選択し、指示に従って更新プログラムをインストールします。

ソリューションの構造

Azure Functions と .NET Aspire を使用するソリューションには、アプリホストプロジェクトや 1 つ以上の Functions プロジェクトを含む複数のプロジェクトがあります。

アプリホストプロジェクトは、アプリケーションのエントリポイントです。 Functions プロジェクトを含め、アプリケーションのコンポーネントのセットアップを調整します。

このソリューションには、通常、 サービスの既定の プロジェクトも含まれます。このプロジェクトには、アプリケーション内のプロジェクト間で使用される既定のサービスと構成のセットが用意されています。

アプリホストプロジェクト

統合を正常に構成するには、アプリホストプロジェクトが次の要件を満たしていることを確認します。

アプリホストプロジェクトは、Aspire.Hosting.Azure.Functions を参照する必要があります。このパッケージは、統合に必要なロジックを定義します。
アプリホストプロジェクトには、オーケストレーションに含める Functions プロジェクトごとにプロジェクト参照が必要です。
アプリホストのProgram.cs ファイルには、AddAzureFunctionsProject<TProject>() インスタンスでIDistributedApplicationBuilderを呼び出してプロジェクトを含める必要があります。このメソッドは、.NET Aspire の他のプロジェクトの種類に使用する AddProject<TProject>() メソッドを使用する代わりに使用します。 AddProject<TProject>()を使用すると、Functions プロジェクトを正しく起動できません。

次の例は、アプリホストプロジェクトの最小 Program.cs ファイルを示しています。

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject");

builder.Build().Run();

Azure Functions プロジェクト

統合を正常に構成するには、Azure Functions プロジェクトが次の要件を満たしていることを確認します。

Functions プロジェクトは、Microsoft.Azure.Functions.Worker と Microsoft.Azure.Functions.Worker.Sdk の 2.x バージョンを参照する必要があります。また、 Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore 参照を 2.x バージョンに更新する必要があります。
Program.cs ファイルでは、IHostApplicationBuilderのバージョンを使用する必要があります。この要件は、 FunctionsApplication.CreateBuilder(args)を使用する必要があることを意味します。
ソリューションにサービスの既定のプロジェクトが含まれている場合は、Functions プロジェクトがそのプロジェクトを使用するように構成されていることを確認します。
- Functions プロジェクトには、サービスの既定のプロジェクトへのプロジェクト参照が含まれている必要があります。
- IHostApplicationBuilderでProgram.csをビルドする前に、builder.AddServiceDefaults()の呼び出しを含めます。

次の例は、.NET Aspire で使用される Functions プロジェクトの最小 Program.cs ファイルを示しています。

using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

この例には、他の多くの Program.cs の例や Azure Functions テンプレートに表示される既定の Application Insights 構成は含まれていません。代わりに、 builder.AddServiceDefaults メソッドを呼び出して、.NET Aspire で OpenTelemetry 統合を構成します。

統合を最大限に活用するには、次のガイドラインを考慮してください。

Functions プロジェクトには、Application Insights の直接統合を含めないでください。代わりに、.NET アスパイアでの監視は、OpenTelemetry のサポートによって処理されます。サービスの既定のプロジェクトを使用して Azure Monitor にデータをエクスポートするように .NET Aspire を構成できます。
Functions プロジェクトの local.settings.json ファイルでカスタムアプリ設定を定義しないでください。 local.settings.jsonに含める必要がある唯一の設定は、"FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"です。アプリホストプロジェクトを使用して、他のすべてのアプリ構成を設定します。

.NET アスパイアとの接続構成

アプリホストプロジェクトはリソースを定義し、コードを使用してそれらの間の接続を作成するのに役立ちます。このセクションでは、Azure Functions プロジェクトで使用する接続を構成およびカスタマイズする方法について説明します。

.NET Aspire には、開始に役立つ既定の接続アクセス許可が含まれています。ただし、これらのアクセス許可は、アプリケーションに適していないか、十分ではない可能性があります。

Azure ロールベースのアクセス制御 (RBAC) を使用するシナリオでは、プロジェクトリソースで WithRoleAssignments() メソッドを呼び出してアクセス許可をカスタマイズできます。 WithRoleAssignments()を呼び出すと、すべての既定のロールの割り当てが削除され、必要な完全なセットロールの割り当てを明示的に定義する必要があります。 Azure Container Apps でアプリケーションをホストする場合、WithRoleAssignments()を使用するには、AddAzureContainerAppEnvironment()でDistributedApplicationBuilderを呼び出す必要もあります。

Azure Functions ホストストレージ

Azure Functions では、いくつかのコア動作にホストストレージ接続 (AzureWebJobsStorage) が必要です。アプリホストプロジェクトで AddAzureFunctionsProject<TProject>() を呼び出すと、既定で AzureWebJobsStorage 接続が作成され、Functions プロジェクトに提供されます。この既定の接続では、ローカル開発の実行に Azure Storage エミュレーターが使用され、デプロイ時にストレージアカウントが自動的にプロビジョニングされます。より詳細な制御を行うには、Functions プロジェクトリソースで .WithHostStorage() を呼び出すことで、この接続を置き換えることができます。

ホストストレージ接続に対して .NET Aspire が設定する既定のアクセス許可は、 WithHostStorage() 呼び出すかどうかによって異なります。 WithHostStorage()を追加すると、ストレージアカウント共同作成者の割り当てが削除されます。次の表に、ホストストレージ接続に対して .NET アスパイアが設定する既定のアクセス許可を示します。

ホストストレージ接続	既定のロール
`WithHostStorage()` の呼び出しなし	ストレージ BLOB データ共同作成者、ストレージキューデータ共同作成者、ストレージテーブルデータコンストリビューター、ストレージアカウント共同作成者
呼び出し `WithHostStorage()`	ストレージ BLOB データ共同作成者、ストレージキューデータ共同作成者、ストレージテーブルデータ共同作成者

次の例は、ホストストレージを置き換え、ロールの割り当てを指定するアプリホストプロジェクトの最小 Program.cs ファイルを示しています。

using Azure.Provisioning.Storage;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("myEnv");

var myHostStorage = builder.AddAzureStorage("myHostStorage");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithHostStorage(myHostStorage)
    .WithRoleAssignments(myHostStorage, StorageBuiltInRole.StorageBlobDataOwner);

builder.Build().Run();

注

ストレージ BLOB データ所有者は、ホストストレージ接続の基本的なニーズに推奨されるロールです。 BLOB サービスへの接続に .NET アスパイアの既定のストレージ BLOB データ共同作成者のみが含まれている場合、アプリで問題が発生する可能性があります。

運用環境のシナリオでは、 WithHostStorage() と WithRoleAssignments()の両方の呼び出しを含めます。その後、必要な他のロールと共に、このロールを明示的に設定できます。

トリガーとバインドの接続

トリガーとバインドは、名前で接続を参照します。次の .NET Aspire 統合は、プロジェクトリソースの WithReference() を呼び出してこれらの接続を提供します。

.NET Aspire の統合	既定のロール
Azure Blob Storage	ストレージ BLOB データ共同作成者、ストレージキューデータ共同作成者、ストレージテーブルデータ共同作成者
Azure Queue Storage	ストレージ BLOB データ共同作成者、ストレージキューデータ共同作成者、ストレージテーブルデータ共同作成者
Azure Event Hubs	Azure Event Hubs データ所有者
Azure Service Bus	Azure Service Bus データ所有者

次の例は、キュートリガーを構成するアプリホストプロジェクトの最小 Program.cs ファイルを示しています。この例では、対応するキュートリガーの Connection プロパティが MyQueueTriggerConnection に設定されているため、 WithReference() の呼び出しで名前が指定されます。

var builder = DistributedApplication.CreateBuilder(args);

var myAppStorage = builder.AddAzureStorage("myAppStorage").RunAsEmulator();
var queues = myAppStorage.AddQueues("queues");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithReference(queues, "MyQueueTriggerConnection");

builder.Build().Run();

他の統合の場合は、 WithReference 呼び出しによって構成が別の方法で設定されます。 .NET アスパイアクライアント統合では構成を使用できますが、トリガーとバインドは使用できません。これらの統合の場合は、 WithEnvironment() を呼び出して、解決するトリガーまたはバインドの接続情報を渡します。

次の例は、接続文字列式を公開するリソースの環境変数 MyBindingConnection を設定する方法を示しています。

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection", otherIntegration.Resource.ConnectionStringExpression);

.NET Aspire クライアント統合とトリガーとバインドのシステムの両方で接続を使用する場合は、 WithReference() と WithEnvironment()の両方を構成できます。

一部のリソースでは、接続の構造が、ローカルで実行する場合と Azure に発行する場合とで異なる可能性があります。前の例では、otherIntegration はエミュレーターとして実行されるリソースである可能性があるため、ConnectionStringExpression からエミュレーター接続文字列が返されます。ただし、リソースが発行されると、.NET Aspire によって ID ベースの接続が設定され、 ConnectionStringExpression はサービスの URI を返す可能性があります。この場合、 Azure Functions の ID ベースの接続を設定するには、別の環境変数名を指定する必要がある場合があります。

次の例では、必要なサフィックスを条件付きで追加するため builder.ExecutionContext.IsPublishMode が使用されています。

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection" + (builder.ExecutionContext.IsPublishMode ? "__serviceUri" : ""), otherIntegration.Resource.ConnectionStringExpression);

各バインドでサポートされる接続形式と、それらの形式に必要なアクセス許可の詳細については、バインディングの参照ページを参照してください。

アプリケーションのホスト

既定では、Azure Functions プロジェクトを Azure に発行すると、Azure Container Apps にデプロイされます。

プレビュー期間中、コンテナーアプリリソースはイベントドリブンスケーリングをサポートしていません。このモードでデプロイされたアプリでは、Azure Functions のサポートを利用できません。サポートチケットを開く必要がある場合は、Azure Container Apps リソースの種類を選択します。

考慮事項とベストプラクティス

Azure Functions と .NET Aspire の統合を評価するときは、次の点を考慮してください。

統合のサポートは現在プレビュー段階です。
.NET Aspire を使用したトリガーとバインドの構成は、現在、特定の統合に制限されています。詳細については、この記事の「.NET アスパイアとの接続の構成」を参照してください。
Program.cs ファイルでは、IHostApplicationBuilderのバージョンを使用する必要があります。 IHostApplicationBuilder を使用すると、 builder.AddServiceDefaults() を呼び出して、.NET Aspire サービスの既定値を Functions プロジェクトに追加できます。
.NET Aspire では、監視に OpenTelemetry が使用されます。サービスの既定のプロジェクトを使用して Azure Monitor にデータをエクスポートするように .NET Aspire を構成できます。

他の多くの Azure Functions コンテキストでは、ワーカーサービスを登録することで Application Insights との直接統合を含めることができます。 .NET Aspire では、この種の統合はお勧めしません。バージョン 2.22.0 の Microsoft.ApplicationInsights.WorkerServiceでランタイムエラーが発生する可能性がありますが、バージョン 2.23.0 はこの問題に対処します。 .NET Aspire を使用している場合は、Functions プロジェクトから直接 Application Insights 統合を削除します。
.NET アスパイアオーケストレーションに参加している Functions プロジェクトの場合、ほとんどのアプリケーション構成は .NET Aspire アプリホストプロジェクトから取得する必要があります。 local.settings.json設定以外は、FUNCTIONS_WORKER_RUNTIMEで設定しないでください。 local.settings.jsonと .NET Aspire で同じ環境変数を設定すると、システムは .NET アスパイアバージョンを使用します。
local.settings.json内の接続に対して Azure Storage エミュレーターを構成しないでください。多くの Functions スターターテンプレートには、AzureWebJobsStorage の既定値としてエミュレーターが含まれています。ただし、エミュレーターの構成では、.NET Aspire が使用するバージョンと競合する可能性があるエミュレーターのバージョンを起動するように開発者ツールに求めるメッセージが表示される場合があります。

次の方法で共有

Azure Functions と .NET アスパイア (プレビュー)

[前提条件]

ソリューションの構造

アプリ ホスト プロジェクト

Azure Functions プロジェクト

.NET アスパイアとの接続構成

Azure Functions ホスト ストレージ

トリガーとバインドの接続

アプリケーションのホスト

考慮事項とベスト プラクティス

フィードバック

その他のリソース

アプリホストプロジェクト

Azure Functions ホストストレージ

考慮事項とベストプラクティス