Azure Functions バージョン 1.x からバージョン 4.x にアプリを移行する

以下の手順はローカル C# プロジェクトを想定しています。代わりに C# スクリプト (.csx ファイル) がアプリで使用されている場合、プロジェクト モデルに変換してから続行してください。

.csproj XML プロジェクト ファイルには、次の変更を加える必要があります。

1. PropertyGroup の値を設定します。TargetFramework から net8.0。

2. PropertyGroup の値を設定します。AzureFunctionsVersion から v4。

3. 次の OutputType 要素を PropertyGroup に追加します。

   <OutputType>Exe</OutputType>
   

4. ItemGroup で。PackageReference リストで、Microsoft.NET.Sdk.Functions へのパッケージ参照を次の参照に置き換えます。

     <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" />
   

   Microsoft.Azure.WebJobs.* 名前空間内の他のパッケージへの参照を書き留めます。 これらのパッケージは後の手順で置き換えます。

5. 次の新しい ItemGroup を追加します。

   <ItemGroup>
     <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
   </ItemGroup>
   

これらの変更を行うと、更新されたプロジェクトは次の例のようになります。

<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>

以下の手順はローカル C# プロジェクトを想定しています。代わりに C# スクリプト (.csx ファイル) がアプリで使用されている場合、プロジェクト モデルに変換してから続行してください。

.csproj XML プロジェクト ファイルには、次の変更を加える必要があります。

1. PropertyGroup の値を設定します。TargetFramework から net48。

2. PropertyGroup の値を設定します。AzureFunctionsVersion から v4。

3. 次の OutputType 要素を PropertyGroup に追加します。

   <OutputType>Exe</OutputType>
   

4. ItemGroup で。PackageReference リストで、Microsoft.NET.Sdk.Functions へのパッケージ参照を次の参照に置き換えます。

     <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" />
   

   Microsoft.Azure.WebJobs.* 名前空間内の他のパッケージへの参照を書き留めます。 これらのパッケージは後の手順で置き換えます。

5. 次の新しい ItemGroup を追加します。

   <ItemGroup>
     <Folder Include="Properties\" />
   </ItemGroup>
   

これらの変更を行うと、更新されたプロジェクトは次の例のようになります。

<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>

.csproj XML プロジェクト ファイルには、次の変更を加える必要があります。

1. PropertyGroup の値を設定します。TargetFramework から net8.0。

2. PropertyGroup の値を設定します。AzureFunctionsVersion から v4。

3. 既存の ItemGroup.PackageReference リストを次の ItemGroup に置き換えます。

   <ItemGroup>
     <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
   </ItemGroup>
   

これらの変更を行うと、更新されたプロジェクトは次の例のようになります。

<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.4.0" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

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

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

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

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

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

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

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

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

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

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

Microsoft.NET.Sdk.Functions の最新の安定バージョンを参照するようにプロジェクトを更新します。

アプリが使用するトリガーとバインドによっては、アプリは追加のパッケージ セットを参照する必要がある場合があります。 検討するべき拡張機能の一覧については、「サポートされているバインド」を参照し、インプロセス プロセス モデルの完全なインストール手順については、各拡張機能のドキュメントを参照してください。 対象としているすべてのパッケージの最新の安定バージョンをインストールするようにしてください。

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();

この例には、パフォーマンスを向上させ、アプリで HTTP トリガーを使用するときに使い慣れたプログラミング モデルを提供するための ASP.NET Core 統合が含まれています。 HTTP トリガーを使用しない場合は、ConfigureFunctionsWebApplication の呼び出しを ConfigureFunctionsWorkerDefaults の呼び出しに置き換えることができます。 それによって、プロジェクト ファイルから Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore への参照を削除できます。 ただし、最適なパフォーマンスを得るためには、他のトリガー タイプを持つ関数の場合でも、ASP.NET Core への FrameworkReference を保持するべきです。

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 属性と、それが適用されていたクラスを削除できます。

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 属性と、それが適用されていたクラスを削除できます。

インプロセスで実行する場合 program.cs ファイルは必要ありません。

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

host.json ファイルが制御するのは、Functions ホスト ランタイムからのログだけであり、分離ワーカー モデルでは、これらのログの一部はアプリケーションから直接取得されるため、より詳細な制御が可能になります。 これらのログをフィルター処理する方法の詳細については、「分離ワーカー モデルでのログ レベルの管理」を参照してください。

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

host.json ファイルは、Functions ホスト ランタイムからのログのみを制御し、分離ワーカー モデルでは、これらのログの一部はアプリケーションから直接取得されるため、より詳細な制御が可能になります。 これらのログをフィルター処理する方法の詳細については、「分離ワーカー モデルでのログ レベルの管理」を参照してください。

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "FUNCTIONS_INPROC_NET8_ENABLED": "1"
    }
}

このセクションでは、移行を行う際に考慮する必要があるその他のコード変更について説明します。 これらの変更はすべてのアプリケーションで必要なわけではありませんが、シナリオに関連があるかどうかを評価する必要があります。 バージョン 1.x 以降の動作変更で、プロジェクトに加える必要があるその他の変更がないかをご確認ください。

JSON シリアル化

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

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

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

バージョン 1.x 以降の動作変更で、プロジェクトに加える必要があるその他の変更がないかをご確認ください。

このセクションでは、移行を行う際に考慮する必要があるその他のコード変更について説明します。 これらの変更はすべてのアプリケーションで必要なわけではありませんが、シナリオに関連があるかどうかを評価する必要があります。 バージョン 1.x 以降の動作変更で、プロジェクトに加える必要があるその他の変更がないかをご確認ください。

JSON シリアル化

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

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

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

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;
        }
    }
}

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

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

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

Update-AzFunctionAppSetting -AppSetting @{"FUNCTIONS_EXTENSION_VERSION" = "~4"} -Name <APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -Force

Windows で実行する場合は、ランタイムのバージョン 4.x で必要な .NET 6.0 も有効にする必要があります。

az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

.NET 6 は、Windows で実行されているすべての言語の関数アプリに必要です。

Windows で実行する場合は、ランタイムのバージョン 4.x で必要な .NET 6.0 も有効にする必要があります。

Set-AzWebApp -NetFrameworkVersion v6.0 -Name <APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME>

.NET 6 は、Windows で実行されているすべての言語の関数アプリに必要です。

Linux 上で .NET アプリを実行する場合は、linuxFxVersion サイト設定も更新する必要があります。 残念ながら、現時点では Azure PowerShell を使用して linuxFxVersion を設定することはできません。 代わりに Azure CLI を使用してください。