.NET アプリをインプロセス モデルから分離ワーカー モデルに移行する

この記事では、.NET 関数アプリをインプロセス モデルから分離ワーカー モデルに安全に移行するプロセスについて説明します。 これらのモデル間の高レベルの違いについては、「実行モードの比較」を参照してください。

このガイドでは、アプリが Functions ランタイムのバージョン 4.x で実行されていることを前提としています。 そうでない場合は、ホストのバージョンをアップグレードするためのガイドに従う必要があります。

• Azure Functions バージョン 2.x および 3.x からバージョン 4.x にアプリを移行する
• Azure Functions バージョン 1.x からバージョン 4.x にアプリを移行する

これらのホスト バージョン移行ガイドは、作業中に分離ワーカー モデルに移行するのにも役立ちます。

移行する関数アプリを特定する

次の Azure PowerShell スクリプトを使用して、現在インプロセス モデルを使用しているサブスクリプション内の関数アプリの一覧を生成します。

スクリプトは、Azure PowerShell が使用するように現在構成されているサブスクリプションを使用します。 サブスクリプションを変更するには、最初に Set-AzContext -Subscription '<YOUR SUBSCRIPTION ID>' を実行し、<YOUR SUBSCRIPTION ID> を評価したいサブスクリプションの ID に置き換えます。

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.Runtime -eq 'dotnet')
     {
          $AppInfo.Add($App.Name, $App.Runtime)
     }
}

$AppInfo

ターゲットの .NET バージョンを選択する

Functions ランタイムのバージョン 4.x では、インプロセス モデルを使用する場合、.NET 関数アプリは .NET 6 または .NET 8 をターゲットとします。

関数アプリを移行すると、.NET のターゲット バージョンを選択できます。 C# プロジェクトを Functions バージョン 4.x でサポートされている次のいずれかのバージョンの .NET に更新できます。

¹分離ワーカー モデルでは、.NET の長期サポート (LTS) と標準期間サポート (STS) の各バージョンと、.NET Framework がサポートされます。 インプロセス モデルでは、.NET の LTS リリースのみがサポートされます (.NET 8 で終了)。 2 つのプロセス モデル間の完全な機能の比較については、インプロセスと分離ワーカー プロセスの .NET Azure Functions の違いに関するページを参照してください。

² インプロセス モデルのサポートは、2026 年 11 月 10 日に終了します。 詳細については、こちらのサポートに関するお知らせを参照してください。 完全なサポートを受け続けるには、分離ワーカー モデルにアプリを移行する必要があります。

このガイドでは、.NET 9 の具体的な例については説明しません。 このバージョンをターゲットにする必要がある場合は、.NET 8 の例を適応させることができます。

移行を準備する

まだ実行していない場合は、Azure PowerShell を使用して、現在の Azure サブスクリプションで移行する必要があるアプリの一覧を特定します。

アプリを分離ワーカー モデルに移行する前に、このガイドの内容をよく確認してください。 また、分離ワーカー モデルの機能と、2 つのモデルの違いについても理解する必要があります。

アプリケーションを移行するには、次の手順を実行します。

1. 「ローカル プロジェクトを移行する」の手順に従って、ローカル プロジェクトを分離ワーカー モデルに移行します。
2. プロジェクトを移行したら、Azure Functions Core Tools のバージョン 4.x を使用して、アプリをローカルで完全にテストします。
3. Azure の関数アプリを分離モデルに更新します。

ローカル プロジェクトを移行する

このセクションでは、ローカル プロジェクトを分離ワーカー モデルに移行するために必要なさまざまな変更の概要を説明します。 一部の手順は、.NET のターゲット バージョンに基づいて異なります。 タブを使用して、目的のバージョンに一致する手順を選択します。 以下の手順はローカル C# プロジェクトを想定しています。代わりに C# スクリプト (.csx ファイル) がアプリで使用されている場合、プロジェクト モデルに変換してから続行してください。

最初に、プロジェクト ファイルを変換して、依存関係を更新します。 すると、プロジェクトのビルド エラーが表示されます。 以降の手順では、対応する変更を行ってこれらのエラーを除去します。

プロジェクト ファイル

次の例は、バージョン 4.x で .NET 8 を使用する .csproj プロジェクト ファイルです。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

次のいずれかの手順を使用して、分離ワーカー モデルで実行されるようにこの XML ファイルを更新します。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
      <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
      <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Folder Include="Properties\" />
  </ItemGroup>
</Project>

プロジェクトのターゲット フレームワークを変更するには、プロジェクト コードの外部でツールチェーンの一部を変更する必要がある場合もあります。 たとえば、VS Code では、ユーザー設定またはプロジェクトの .vscode/settings.json ファイルを使用して、azureFunctions.deploySubpath 拡張機能の設定を更新することが必要な場合があります。 ビルド ステップまたは CI/CD パイプラインの一部として、フレームワーク バージョンへの依存関係があるかどうかを確認します。これはプロジェクト コードの外部に存在する可能性があります。

パッケージ参照

分離ワーカー モデルに移行する場合は、アプリケーションが参照するパッケージを変更する必要があります。

まだ更新していない場合、次に示すものの最新の安定バージョンを参照するようにプロジェクトを更新します。

• Microsoft.Azure.Functions.Worker
• Microsoft.Azure.Functions.Worker.Sdk

アプリが使用するトリガーとバインドによっては、アプリは別のパッケージ セットを参照する必要がある場合があります。 次の表に、最も一般的に使用されるいくつかの拡張機能の置換を示します。

検討するべき拡張機能の全一覧については、「サポートされているバインド」を参照し、分離プロセス モデルの完全なインストール手順については、各拡張機能のドキュメントを参照してください。 対象としているすべてのパッケージの最新の安定バージョンをインストールするようにしてください。

分離ワーカー モデル アプリケーションでは Microsoft.Azure.WebJobs.* 名前空間や Microsoft.Azure.Functions.Extensions 内のどのパッケージも参照するべきではありません。 これらへの参照が何か残っている場合は、それらを削除する必要があります。

Program.cs ファイル

分離ワーカー プロセスで実行できるよう移行する場合は、Program.cs ファイルをプロジェクトに次の内容で追加する必要があります。

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

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

namespace Company.FunctionApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .ConfigureServices(services => {
                    services.AddApplicationInsightsTelemetryWorkerService();
                    services.ConfigureFunctionsApplicationInsights();
                })
                .Build();
            host.Run();
        }
    }
}

Program.cs ファイルで置換されるファイルに FunctionsStartup 属性がある場合は、通常は Startup.cs ファイルです。 FunctionsStartup コードが IFunctionsHostBuilder.Services を参照する場所で、代わりに HostBuilder の .ConfigureServices() メソッド内のステートメントを Program.cs に追加できます。 Program.cs の操作については、分離ワーカー モデル ガイドの「スタートアップと構成」をご覧ください。

上記の既定の Program.cs の例には、分離ワーカー モデル用の Application Insights 統合のセットアップが含まれます。 実際の Program.cs の中で、プロジェクト内のコードから受け取るログに適用する必要があるログのフィルター処理も構成する必要があります。 分離ワーカー モデルにおいて、host.json ファイルが制御するのは、Functions ホスト ランタイムによって生成されたイベントだけです。 Program.cs でフィルター規則を構成しない場合、テレメトリのさまざまなカテゴリに対して異なるログ レベルが表示される場合があります。

HostBuilder の一部としてカスタム構成ソースを登録することはできますが、これらが適用されるのも同様にプロジェクト内のコードに対してだけであることに注意してください。 トリガーとバインドの構成はプラットフォームでも必要であり、これは、アプリケーション設定、Key Vault 参照、または App Configuration 参照機能を通して提供する必要があります。

既存の FunctionsStartup から Program.cs ファイルへすべてを移動すると、FunctionsStartup 属性と、それが適用されていたクラスを削除できます。

関数シグネチャの変更

一部の主要な種類は、インプロセス モデルと分離ワーカー モデルの間で変更されます。 これらの多くが関連している属性、パラメーター、および戻り値の型は、関数シグネチャを構成しています。 関数のそれぞれに対して、以下に変更を加える必要があります。

• 関数属性 (関数の名前も設定します)
• 関数がどのように ILogger/ILogger<T> を取得するか
• トリガーとバインドの属性とパラメーター

このセクションの残りの部分では、これらの手順について説明します。

関数の属性

分離ワーカー モデルの Function 属性は FunctionName 属性に置き換えられます。 新しい属性は同じシグネチャを持ち、唯一の違いは名前にあります。 そのため、行えるのはプロジェクト全体にわたる文字列置換だけになります。

ログ記録

インプロセス モデルでは、省略可能な ILogger パラメーターを関数に含めるか、依存関係の挿入を使用して ILogger<T> を取得することができます。 アプリに既に依存関係の挿入を使用していた場合、同じメカニズムが分離ワーカー モデルでも作用します。

ただし、ILogger メソッド パラメーターに依存した関数の場合は、変更を行う必要があります。 依存関係の挿入を使用して ILogger<T> を取得することをお勧めします。 次の手順を使用して関数のログ記録メカニズムを移行します。

1. 関数クラスで、private readonly ILogger<MyFunction> _logger; プロパティを追加して、MyFunction を関数クラスの名前に置き換えます。

2. ILogger<T> をパラメーターとして受け取る関数クラスのコンストラクターを作成します。

   public MyFunction(ILogger<MyFunction> logger) {
       _logger = logger;
   }
   

   先ほどのコード スニペットに含まれる MyFunction の両インスタンスを、関数クラスの名前に置き換えます。

3. 関数コードの中のログ記録操作で、ILogger パラメーターへの参照を _logger に置き換えます。

4. ILogger パラメーターを関数シグネチャから削除します。

詳細については、「分離ワーカー モデルでのログ記録」をご覧ください。

トリガーとバインディングの変更

前の手順でパッケージ参照を変更したとき発生したトリガーとバインディングのエラーを、これから修正します。

1. すべての using Microsoft.Azure.WebJobs; ステートメントを削除します。

2. using Microsoft.Azure.Functions.Worker; ステートメントを追加します。

3. 各バインディング属性で、属性の名前をそのリファレンス ドキュメントの指定のとおりに変更します。「サポートされるバインディング」インデックスをご覧ください。 一般的に、属性名の変更は次のとおりです。

   • トリガーは、通常は同じ名前のままです。 たとえば、QueueTrigger が両モデルの属性名になります。
   • 入力バインディングは、通常は "Input" をその名前に追加する必要があります。 たとえば、CosmosDB 入力バインディング属性をインプロセス モデルで使用した場合、この属性は CosmosDBInput になります。
   • 出力バインディングは、通常は "Output" をその名前に追加する必要があります。 たとえば、Queue 出力バインディング属性をインプロセス モデルで使用した場合、この属性は QueueOutput になります。

4. 属性パラメーターを、バインディングのリファレンス ドキュメントで指定されているように、分離ワーカー モデル バージョンが反映されるように更新します。

   たとえば、インプロセス モデルで、BLOB 出力バインディングは、Access プロパティを含む [Blob(...)] 属性で表現されます。 分離ワーカー モデルでは、BLOB 出力属性は [BlobOutput(...)] になります。 バインディングに Access プロパティは必要でなくなるため、パラメーターを削除できます。 そのため、[Blob("sample-images-sm/{fileName}", FileAccess.Write, Connection = "MyStorageConnection")] は [BlobOutput("sample-images-sm/{fileName}", Connection = "MyStorageConnection")] になります。

5. 出力バインディングを関数パラメーター リストから取り出します。 出力バインディングがひとつだけある場合は、これを関数の戻り値の型に適用できます。 複数の出力がある場合、各出力のプロパティで新しいクラスを作成し、属性をこれらのプロパティに適用します。 詳細については、「複数の出力バインディング」を参照してください。

6. それぞれのバインディングのリファレンス ドキュメントで、バインディング先にできる種類について参照してください。 場合によっては、種類の変更が必要になることがあります。 出力バインディングでは、インプロセス モデル バージョンで IAsyncCollector<T> を使用した場合、これを対象になる種類の配列である T[] へのバインディングに置き換えることができます。 出力バインディングを、それが表すサービスのクライアント オブジェクトに、使用可能な場合は入力バインディングのバインディングの種類として、あるいはクライアントを自分で挿入することにより、置き換えることも検討できます。

7. 関数に IBinder パラメーターが含まれる場合は、それを除去してください。 機能を、それが表すサービスのクライアント オブジェクトに、使用可能な場合は入力バインディングのバインディングの種類として、あるいはクライアントを自分で挿入することにより、置き換えます。

8. 関数コードを更新して、すべての新しい種類で機能するようにします。

local.settings.json ファイル

local.settings.json ファイルは、ローカルで実行している場合にのみ使用されます。 詳細については、「ローカル設定ファイル」を参照してください。

インプロセスの実行から分離ワーカー プロセスでの実行に移行する場合は、FUNCTIONS_WORKER_RUNTIME 値を "dotnet-isolated" に変更する必要があります。 local.settings.json ファイルに少なくとも次の要素が含まれていることを確認してください。

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

'AzureWebJobsStorage'' の値は、違っている場合があります。 その値を移行処理の一部として変更する必要はありません。

host.json ファイル

host.json ファイルに変更は必要ありません。 ただし、このファイル内の Application Insights 構成がインプロセス モデル プロジェクトからのものである場合、Program.cs ファイルに追加の変更を加える必要があるかもしれません。 host.json ファイルが制御するのは、Functions ホスト ランタイムからのログだけであり、分離ワーカー モデルでは、これらのログの一部はアプリケーションから直接取得されるため、より詳細な制御が可能になります。 これらのログをフィルター処理する方法の詳細については、「分離ワーカー モデルでのログ レベルの管理」を参照してください。

その他のコード変更

このセクションでは、移行を行う際に考慮する必要があるその他のコード変更に焦点を当てます。 これらの変更はすべてのアプリケーションで必要なわけではありませんが、何かが自分のシナリオに関連するかどうかを評価する必要があります。

JSON シリアル化

既定では、分離ワーカー モデルは JSON シリアル化に System.Text.Json を使用します。 シリアライザー オプションをカスタマイズしたり、JSON.NET (Newtonsoft.Json) に切り替えたりするには、こちらの手順を参照してください。

Application Insights のログ レベルとフィルター処理

ログは、Functions ホスト ランタイムとプロジェクト内のコードの両方から Application Insights に送信できます。 host.json では、ホスト ログの規則を構成できますが、コードからのログを制御するには、Program.cs の一部としてフィルター規則を構成する必要があります。 これらのログをフィルター処理する方法の詳細については、「分離ワーカー モデルでのログ レベルの管理」を参照してください。

関数移行の例

HTTP トリガーの例

インプロセス モデルの HTTP トリガーは次の例のようになります。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get", Route = null)] HttpRequest req,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

移行後のバージョンの HTTP トリガーは次の例のようになります。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequestData req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

Azure で関数アプリを更新する

関数アプリを分離モデルに更新するには、2 つの変更を同時に完了する必要があります。これは、1 つだけを完了すると、アプリはエラー状態になるためです。 これらの変更により、アプリ プロセスが再起動されます。 これらの理由から、ステージング スロットを使用して更新を実行する必要があります。 ステージング スロットを使用すると、アプリのダウンタイムを最小限に抑え、Azure の更新された構成を使用して移行されたコードをテストおよび確認できるようになります。 その後、スワップ操作を通じて、完全に移行したアプリを運用スロットにデプロイできます。

以下の手順に従って、デプロイ スロットを使用し、関数アプリを分離ワーカー モデルに更新します。

1. まだの場合はデプロイ スロットを作成します。 また、スロット スワップ プロセスを理解し、中断を最小限に抑えて既存のアプリケーションを更新できるようにすることもできます。

2. FUNCTIONS_WORKER_RUNTIME アプリケーション設定を dotnet-isolated に設定して、分離ワーカー モデルを使用するようにステージング (非運用) スロットの構成を変更します。 FUNCTIONS_WORKER_RUNTIME は "スロット設定" としてマークしないでください。

   更新の一部として別のバージョンの .NET も対象にしている場合は、スタック構成も変更する必要があります。 これを行うには、分離ワーカー モデルのスタック構成を更新する手順に関する記事を参照してください。 今後、.NET バージョンの更新を行う際にも同じ手順を実行します。

   CI/CD パイプラインなどの自動化されたインフラストラクチャ プロビジョニングがある場合は、FUNCTIONS_WORKER_RUNTIME を dotnet-isolated に設定したままにし、正しい .NET バージョンを対象とするように自動化も更新されていることを確認します。

3. 移行したプロジェクトを関数アプリのステージング (非運用) スロットに発行します。

   Visual Studio を使用して、インプロセス モデルを使用する既存のアプリまたはスロットに分離ワーカー モデル プロジェクトを発行する場合、前の手順を同時に完了することもできます。 前の手順を完了していない場合、Visual Studio では、デプロイ時に関数アプリを更新するように求められます。 Visual Studio では、これは 1 つの操作として表示されますが、それでも 2 つの独立した操作です。 中間状態でも、ステージング (非運用) スロットからのログにエラーが表示される場合があります。

4. アプリケーションがステージング (非運用) スロット内で期待どおりに機能していることを確認します。

5. スロット スワップ操作を実行します。 これにより、ステージング (非運用) スロットで行った変更が運用スロットに適用されます。 スロット スワップは 1 回の更新として行われるため、運用環境での一時的なエラー状態が発生することを回避できます。

6. アプリケーションが運用スロット内で期待どおりに機能していることを確認します。

これらの手順を完了すると、移行が完了し、アプリは分離モデル上で動作します。 お疲れさまでした。 移行が必要な他のアプリについては、必要に応じてこのガイドの手順を繰り返します。

次のステップ