将应用从 Azure Functions 版本 3.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();

此示例包括 ASP.NET Core 集成，以提高性能，并在应用使用 HTTP 触发器时提供熟悉的编程模型。 如果不打算使用 HTTP 触发器，则可以将对 ConfigureFunctionsWebApplication 的调用替换为对 ConfigureFunctionsWorkerDefaults 的调用。 如果这样做，可以从项目文件中删除对 Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore 的引用。 但是，为了获得最佳性能，即使对于具有其他触发器类型的函数，您也应该将 FrameworkReference 保持在 ASP.NET Core 上。

Program.cs文件将替换具有FunctionsStartup属性的任何文件，该文件通常是Startup.cs文件。 在 FunctionsStartup 代码将引用 IFunctionsHostBuilder.Services 的位置，可以改为在 Program.cs 中 .ConfigureServices() 的 HostBuilder 方法中添加语句。 若要详细了解如何使用 Program.cs，请参阅独立辅助角色模型指南中的 启动和配置 。

前面所述的默认 Program.cs 示例包括 Application Insights 的设置。 在 Program.cs 中，还必须配置任何应该应用于项目中代码的日志的日志筛选。 在隔离的工作器模型中， host.json 文件仅控制 Functions 主机运行时发出的事件。 如果未在 Program.cs中配置筛选规则，则可能会看到遥测中各种类别的日志级别存在差异。

尽管可以将自定义配置源注册为 HostBuilder 中的一部分，但这些源同样仅适用于项目中的代码。 平台还需要触发器和绑定配置，这应该通过 应用设置、密钥保管库 引用或 App 配置 引用功能提供。

将所有内容从任何现有 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 的位置，可以改为在 Program.cs 中 .ConfigureServices() 的 HostBuilder 方法中添加语句。 若要详细了解如何使用 Program.cs，请参阅独立辅助角色模型指南中的 启动和配置 。

前面所述的默认 Program.cs 示例包括 Application Insights 的设置。 在 Program.cs 中，还必须配置任何应该应用于项目中代码的日志的日志筛选。 在隔离的工作器模型中， host.json 文件仅控制 Functions 主机运行时发出的事件。 如果未在 Program.cs中配置筛选规则，则可能会看到遥测中各种类别的日志级别存在差异。

尽管可以将自定义配置源注册为 HostBuilder 中的一部分，但这些源同样仅适用于项目中的代码。 平台还需要触发和绑定配置，这应该通过<应用程序设置>、<密钥保管库引用>或<应用程序配置引用>功能来提供。

将所有内容从任何现有 FunctionsStartup 文件移动到 Program.cs 文件后，可以删除 FunctionsStartup 该属性及其应用到的类。

使用进程内模型时不需要Program.cs文件。

{
    "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"
    }
}

无需对 host.json 文件进行更改。 但是，如果此文件中的 Application Insights 配置来自进程内模型项目，则可能需要在 Program.cs 文件中进行其他更改。 host.json 文件仅控制来自 Functions 主机运行时环境的日志记录，在隔离工作者模型中，其中一些日志是由你的应用程序直接生成的，因而给予你更多的控制权。 有关如何筛选这些日志的详细信息，请参阅在独立辅助角色模型中管理日志级别。

无需对 host.json 文件进行更改。 但是，如果此文件中的 Application Insights 配置来自进程内模型项目，则可能需要在 Program.cs 文件中进行其他更改。 host.json 文件仅控制来自 Functions 主机运行时环境的日志记录，在隔离工作者模型中，其中一些日志是由你的应用程序直接生成的，因而给予你更多的控制权。 有关如何筛选这些日志的详细信息，请参阅在独立辅助角色模型中管理日志级别。

无需对 host.json 文件进行更改。

本部分重点介绍在迁移过程中要考虑的其他代码更改。 所有应用程序都不需要这些更改，但你应该评估是否与方案相关。 请务必检查 3.x 和 4.x 之间的重大变更，以了解可能需要对项目进行的其他更改。

JSON 序列化

默认情况下，独立辅助角色模型使用 System.Text.Json 进行 JSON 序列化。 若要自定义序列化程序选项或切换到 JSON.NET（Newtonsoft.Json），请参阅 Customizing JSON 序列化。

Application Insights 日志级别和筛选

日志可以从 Functions 主机运行时和项目中的代码发送到 Application Insights。 host.json 允许你为主机日志记录配置规则，但若要控制来自代码的日志，需要将筛选规则配置为Program.cs的一部分。 有关如何筛选这些日志的详细信息，请参阅在独立辅助角色模型中管理日志级别。

本部分重点介绍在迁移过程中要考虑的其他代码更改。 所有应用程序都不需要这些更改，但你应该评估是否与方案相关。 请务必检查 3.x 和 4.x 之间的重大变更，以了解可能需要对项目进行的其他更改。

JSON 序列化

默认情况下，独立辅助角色模型使用 System.Text.Json 进行 JSON 序列化。 若要自定义序列化程序选项或切换到 JSON.NET（Newtonsoft.Json），请参阅 Customizing JSON 序列化。

Application Insights 日志级别和筛选

日志可以从 Functions 主机运行时和项目中的代码发送到 Application Insights。 host.json 允许你为主机日志记录配置规则，但若要控制来自代码的日志，需要将筛选规则配置为Program.cs的一部分。 有关如何筛选这些日志的详细信息，请参阅在独立辅助角色模型中管理日志级别。

请务必检查 3.x 和 4.x 之间的重大变更，以了解可能需要对项目进行的其他更改。

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

与版本 3.x（进程内）相同。