將應用程式從 Azure Functions 3.x 版遷移到 4.x 版

重要事項

截至 2022 年 12 月 13 日，運行於 Azure Functions 執行時 2.x 與 3.x 版本的函式應用程式已結束延長支援。 如需詳細資訊，請參閱已淘汰的版本。

Azure Functions 4.x 版本與 3.x 版本具備高度向下相容性。 大部分應用程式應該都可以安全地移轉至 4.x，不需要重大程式碼變更。 欲了解更多 Functions 執行時版本的資訊，請參見 Azure Functions 執行時版本概覽。

重要事項

在 Linux 上使用 Consumption 計劃且仍使用已到期的 v3 執行階段 的函式應用程式，在 2026 年 9 月 30 日後將停止運行。 為避免服務中斷，請將 應用程式遷移到 v4 執行環境。

在 Linux 上以 Consumption 方案託管功能應用程式的選項將於 2028 年 9 月 30 日終止。 Linux 消費方案沒有新增功能或 語言版本。 在 Windows 上運行的 Consumption 方案應用程式目前不受影響。 在退休日前將應用程式遷移到 Flex Consumption 計畫。

本文將逐步引導您完成安全地移轉函數應用程式，以在 Functions 執行階段 4.x 版上執行的程序。 因為專案移轉指示與語言有關，因此請務必從文章頂端的選取器中選擇您的開發語言。

識別要移轉的函數應用程式

使用下列 PowerShell 指令碼，以在您的訂用帳戶中產生目前以 2.x 或 3.x 版為目標的函數應用程式清單：

$Subscription = '<YOUR SUBSCRIPTION ID>' 
 
Set-AzContext -Subscription $Subscription | Out-Null

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"] -like '*3*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

選擇你的目標 .NET 版本

在 Functions 執行階段的 3.x 版本中，您的 C# 函式應用程式可以選擇以內部進程模型搭配 .NET Core 3.1，或以隔離的工作執行緒模型搭配 .NET 5。

當你遷移功能應用程式時，可以選擇目標版本的 .NET。 你可以將 C# 專案更新為以下 Functions 4.x 版本支援的 .NET 版本之一：

.NET 版本 .NET 官方支援政策 發布類型 Functions 處理序模型1、2
.NET 10 LTS（2028 年 11 月 14 日終止支援） 隔離式背景工作角色模型
.NET 9 STS（2026 年 11 月 10 日終止支援）3 隔離式背景工作角色模型
.NET 8 LTS (2026 年 11 月 10 日終止支援) 隔離式背景工作角色模型、
同處理序模型2
.NET 框架 4.8 請參閱原則 隔離式背景工作角色模型

1孤立工作者模型支援長期支援（LTS）及標準期限支援（STS）版本的.NET，以及.NET框架。 in-process模型僅支援.NET的LTS版本，最後支援到.NET 8。 欲了解兩種工作程序在功能和特性上的完整比較，請參閱進程中與隔離工作程序的.NET Azure Functions 差異。

2 內含式模型的支援會於 2026 年 11 月 10 日結束。 如需詳細資訊，請參閱此支援公告。 如需持續的完整支援，您應該將應用程式移轉至隔離式背景工作角色模型。

3 .NET 9 先前預計支援終止日期為 2026 年 5 月 12 日。 在 .NET 9 服務期間，.NET 團隊將 STS 版本的支援延長至 24 個月，從 .NET 9 開始。 如需詳細資訊，請參閱 部落格文章。

秘訣

我們建議在孤立工作者模式下更新至 .NET 8。 .NET 8 是支援時間窗口最長的完整釋出版本。

雖然您可以選擇改用進程內模型，但如果您可以避免此方法，我們不建議使用此方法。 針對同處理序模型的支援將於 2026年 11 月 10 日結束 (英文)，因此您必須在該時間之前先移至隔離的背景工作角色模型。 在遷移至 4.x 版本時，如此操作將減少總工作量，而孤立的工作者模式將為你的應用程式帶來額外好處，包括更加輕鬆地針對 .NET 的未來版本。 如果你要轉用隔離工作者模式，.NET升級助理也能幫你處理許多必要的程式碼變更。

本指南未提供 .NET 10（預覽版）或 .NET 9 的具體範例。 如果您需要針對其中一個版本，可以調整 .NET 8 範例。

為移轉做準備

如果你還沒這麼做，請用 Azure PowerShell 找出你目前 Azure 訂閱中需要遷移的應用程式清單。

將應用程式移轉至 Functions 執行階段 4.x 版之前，您應該執行下列工作：

  1. 檢閱 3.x 與 4.x 之間的重大變更清單。
  2. 完成移轉本機專案中的步驟，將您的本機專案移轉至 4.x 版。
  3. 遷移專案後，請在本地使用 Azure Functions核心工具 版本 4.x 完整測試應用程式。
  4. 在Azure託管的應用程式上執行預升級驗證器，並解決任何發現的問題。
  5. 在 Azure 中更新你的函式應用程式到新版本。 如果你需要減少停機時間，可以考慮使用 staging slot 在 Azure 上測試並驗證你在新執行時版本中遷移的應用程式。 接著，您可以使用更新的版本設定將應用程式部署至生產位置。 如需詳細資訊，請參閱使用位置更新。
  6. 將移轉的專案發佈至更新的函數應用程式。

當你使用 Visual Studio 將版本 4.x 專案發佈到現有的函式應用程式（較低版本）時，部署時會提示讓 Visual Studio 將函式應用程式更新到 4.x 版本。 此次更新會使用無位置更新中定義的相同流程。

移轉本機專案

升級指示與語言相關。 若沒有看到您的語言，請從文章頂端的選取器中選擇。

選擇與目標版本 .NET 及所需流程模型（進行中或隔離工作程序）相符的分頁。

秘訣

如果您正在轉用使用隔離工作者模型的 LTS 或 STS 版本的 .NET，可以使用 .NET 升級助理 自動進行下列章節中提及的許多變更。

專案檔案

以下範例是一個 .csproj 專案檔案，使用的是 .NET Core 3.1 的 3.x 版本：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="3.0.13" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="Microsoft.CSharp" />
  </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 檔案，以在 Functions 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>

套件和命名空間變更

根據您要移轉至的模型，您可能需要更新或變更應用程式參考的套件。 當您採用目標套件時，您必須更新 using 陳述式的命名空間，以及您參考的一些類型。 您可以在本文後面的 using中看到這些命名空間變更對 陳述式的影響。

如果您尚未這麼做，請更新專案以參考最新穩定版本的：

根據應用程式所使用的觸發程序和繫結，您的應用程式可能需要參考一組不同的套件。 下表顯示一些最常用延伸模組的取代項目：

狀況 套件參考的變更
計時器觸發程序 加
Microsoft.Azure.Functions.Worker.Extensions.Timer
儲存體繫結 Replace
Microsoft.Azure.WebJobs.Extensions.Storage
取代為
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs，
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues，以及
Microsoft.Azure.Functions.Worker.Extensions.Tables
Blob 繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
佇列繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
資料表繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.Tables
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.Tables
Cosmos DB 繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.CosmosDB
和/或
Microsoft.Azure.WebJobs.Extensions.DocumentDB
最新版本的
Microsoft.Azure。Functions.Worker.Extensions.CosmosDB
服務匯流排 綁定 將參考取代為
Microsoft.Azure.WebJobs.Extensions.ServiceBus
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
事件中樞繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.EventHubs
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
事件方格繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.EventGrid
最新版本的
Microsoft.Azure。Functions.Worker.Extensions.EventGrid
SignalR Service 綁定 將參考取代為
Microsoft.Azure.WebJobs.Extensions.SignalRService
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Durable Functions 將參考取代為
Microsoft.Azure.WebJobs.Extensions.DurableTask
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Durable Functions
(SQL 儲存體提供者)		 將參考取代為
Microsoft.DurableTask.SqlServer.AzureFunctions
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Durable Functions
(Netherite 儲存體提供者)		 將參考取代為
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
SendGrid 繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.SendGrid
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Kafka 繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.Kafka
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.Kafka
RabbitMQ 繫結 將參考取代為
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
相依性插入
和啟動設定		 移除對下列項目的參考：
Microsoft.Azure.Functions.Extensions
(隔離式背景工作角色模型預設會提供這項功能。)

如需要納入考量的完整延伸模組清單，請參閱支援的繫結，並參閱每個延伸模組的文件，以取得隔離式處理序模型的完整安裝指示。 對於您要以其作為目標的任何套件，請務必安裝其最新穩定版本。

秘訣

此程序期間對延伸模組版本所做的任何變更，也可能需要您更新 host.json 檔案。 請務必閱讀您使用的每個延伸模組的文件。 例如，服務匯流排 擴充套件在 4.x 與 5.x 版本間結構有破壞性變更。 更多資訊請參見 Azure Functions 的 Azure 服務匯流排 綁定。

你的孤立工作者模型應用程式不應引用 Microsoft.Azure.WebJobs.* 命名空間或 Microsoft.Azure.Functions.Extensions 中的任何套件。 如果您有任何對這些項目的其餘參考，則應該移除這些參考。

秘訣

你的應用程式也可能依賴 Azure SDK 類型，無論是作為觸發器和綁定的一部分，或是作為獨立的相依。 您也應該利用這個機會來更新這些項目。 最新版本的函式擴充功能可以搭配最新版本的 Azure SDK for .NET 使用，且其幾乎所有的套件都是以 Azure.* 格式為主。

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

此範例包含 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的位置，您可以改為在.ConfigureServices()的HostBuilder方法中新增語句。 若要深入瞭解如何使用 Program.cs，請參閱隔離的背景工作模型指南中的 啟動和 設定。

先前描述的預設 Program.cs 範例包括 Application Insights 的設定。 在您的 Program.cs中，您也必須設定應該套用至專案中程式代碼所產生記錄的任何記錄篩選。 在隔離的工作者模型中，host.json 檔案僅控制由 Function 主機執行環境所觸發的事件。 如果您未在 Program.cs 中設定篩選規則，您可能會看到遙測中各種類別的記錄層級差異。

雖然您可以將自定義組態來源註冊為HostBuilder的一部分，但這些同樣僅適用於您專案中的程式碼。 平台也需要觸發與綁定設定，這應透過 application settings、金鑰保存庫 references 或 App Configuration references 功能提供。

將所有專案從任何現有的 FunctionsStartup 檔案移至 Program.cs 檔案之後，您可以刪除 FunctionsStartup 屬性及其套用的類別。

local.settings.json 檔案

local.settings.json 檔案只有在本機執行時才會使用。 如需詳細資訊，請參閱本機設定檔。

當您移轉至 4.x 版時，請確定您的 local.settings.json 檔案至少有下列元素：

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

附註

從執行內含式移轉至在隔離式背景工作處理序中執行時，您需要將 FUNCTIONS_WORKER_RUNTIME 值變更為 "dotnet-isolated"。

host.json 檔案

您的 host.json 檔案不需要變更。 不過，如果您的 Application Insights 設定檔來自您的進行中模型專案，您可能想要在您的 Program.cs 檔案中進行其他變更。 此 host.json 檔案只會控制來自 Functions 主機執行階段的記錄，而隔離的背景工作角色模型中，這些記錄中其中有一些會直接來自您的應用程式，讓您有更多控制權。 如需如何篩選這些記錄的詳細資料，請參閱在隔離的背景工作模型中管理記錄層級 (部分機器翻譯)。

類別名稱變更

某些索引鍵類別已在版本之間變更名稱。 這些變更可能是因為 .NET API 的變更，或是進行中與獨立工作程序之間的差異所致。 遷移時，以下表格顯示可能變更的關鍵 .NET 函式使用的類別:

.NET 核心 3.1 .NET 5 .NET 8
FunctionName (屬性) Function (屬性) Function (屬性)
ILogger ILogger ILogger、ILogger<T>
HttpRequest HttpRequestData HttpRequestData，HttpRequest（使用 ASP.NET Core 整合）
IActionResult HttpResponseData HttpResponseData，IActionResult（使用 ASP.NET Core 整合）
FunctionsStartup (屬性) 改用 Program.cs 改用 Program.cs

繫結中也可能有類別名稱差異。 如需詳細資訊，請參閱特定繫結的參考文章。

其他程式碼變更

本節會強調當您完成移轉時所要考量的其他程式碼變更。 所有應用程式不需要這些變更，但您應該評估是否有任何與案例相關。 請務必檢視 3.x 和 4.x 之間的重大變更，以了解其他您可能需要對專案進行的變更。

JSON 序列化

根據預設，隔離的背景工作模型會使用 System.Text.Json 進行 JSON 串行化。 若要自訂序列化器選項或切換至 JSON.NET（Newtonsoft.Json），請參見 Customizing JSON serialization。

Application Insights 記錄層級和篩選

您可以從 Functions 主機執行階段和專案中的程式碼將記錄傳送至 Application Insights。 host.json 可讓您設定主機記錄的規則，但若要控制來自程式代碼的記錄，您必須將篩選規則設定為Program.cs的一部分。 如需如何篩選這些記錄的詳細資料，請參閱在隔離的背景工作模型中管理記錄層級 (部分機器翻譯)。

HTTP 觸發程序範本

在 HTTP 觸發的函式中，可以看到同處理序和隔離式背景工作處理序之間的差異。 3.x 版 (同處理序) 的 HTTP 觸發程序範本看起來像下列範例：

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

移轉後版本的 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"]}!");
        }
    }
}

要將你的專案更新到 Azure Functions 4.x：

  1. 將你的 Azure Functions Core Tools 的本地安裝更新到 4.x 版本。

  2. 將你的應用程式的 Azure Functions 擴充套件 更新到 2.x 或以上。 如需詳細資訊，請參閱重大變更。

  1. 如有需要，可轉至 4.x 版本支援的 Java 版本。

  2. 更新應用程式的 POM.xml 檔案，以將 FUNCTIONS_EXTENSION_VERSION 設定修改為 ~4，如下列範例所示：

    <configuration>
    <resourceGroup>${functionResourceGroup}</resourceGroup>
    <appName>${functionAppName}</appName>
    <region>${functionAppRegion}</region>
    <appSettings>
        <property>
            <name>WEBSITE_RUN_FROM_PACKAGE</name>
            <value>1</value>
        </property>
        <property>
            <name>FUNCTIONS_EXTENSION_VERSION</name>
            <value>~4</value>
        </property>
    </appSettings>
</configuration>
  1. 如有需要，請移至其中一個 4.x 版支援的 Node.js 版本。
  1. 請利用此機會升級至建議使用的 PowerShell 7.2。 如需詳細資訊，請參閱 PowerShell 版本。
  1. 如果你用的是 Python 3.6，建議改用支援的版本。

執行升級前驗證程式

Azure Functions 提供一個預升級驗證器，幫助你在遷移 function 應用程式到 4.x 時發現潛在問題。 若要執行升級前驗證程式：

  1. 在 Azure 入口網站，導航至你的功能應用程式。

  2. 選取 [診斷並解決問題] 頁面。

  3. 在函數應用程式診斷中，開始輸入 Functions 4.x Pre-Upgrade Validator，然後從清單中選擇它。

  4. 驗證完成後，請檢閱建議並解決您應用程式中的任何問題。 如果需要對您的應用程式進行修改，請務必使用 Functions 執行時版本 4.x 來驗證這些變更，可以本地使用 Azure Functions Core Tools v4，或是使用 暫存插槽。

在 Azure 更新你的函式應用程式

你需要在發佈遷移專案前，先將 Azure 函式應用主機的執行時更新到 4.x 版本。 Functions 主機所使用的執行階段版本是由 FUNCTIONS_EXTENSION_VERSION 應用程式設定所控制，但在某些情況下，其他設定也必須更新。 程式碼變更和應用程式設定的變更都需要您的函數應用程式重新啟動。

最簡單的方式是不使用位置更新，然後重新發佈您的應用程式專案。 您也可以將應用程式中的停機時間降到最低，並透過使用位置更新來簡化復原。

無位置更新

更新到 v4.x 最簡單的方法是在 Azure 的函式應用程式中，將 FUNCTIONS_EXTENSION_VERSION 應用程式設定設為 ~4。 在具有位置的網站上，您必須遵循不同的程序。

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

你還必須設定另一個設定，這在 Windows 和 Linux 之間是不同的。

在 Windows 上執行時，你還需要啟用 .NET 8.0，這是執行環境版本 4.x 所要求的。

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

.NET 6 是任何語言中運行 Windows 函式應用程式的必備條件。

在此範例中，分別將 <APP_NAME> 和 <RESOURCE_GROUP_NAME> 取代為函數應用程式的名稱和資源群組名稱。

您現在可以重新發佈已移轉為在 4.x 版上執行的應用程式專案。

使用位置更新

使用部署位置是將函數應用程式從舊版更新至 v4.x 執行階段的好方法。 使用預備位置，您可以在預備位置的新執行階段版本上執行應用程式，並在驗證之後切換至生產環境。 位置也提供了在更新期間盡量減少停機時間的方式。 如果您需要盡量減少停機時間，請遵循最低停機時間更新中的步驟。

在更新位置中驗證應用程式之後，您可以將應用程式和新版本設定交換至生產環境。 交換需要在生產位置中設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0。 新增此設定的方式會影響更新所需的停機時間。

標準更新

如果您位置啟用的函數應用程式可以接受完整重新啟動的停機時間，您可以直接在生產位置更新 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS 設定。 由於直接在生產位置中變更此設定會導致重新啟動，影響可用性，因此請考量在流量較少時執行這項變更。 接下來您便可以從預備位置交換更新的版本。

Update-AzFunctionAppSetting PowerShell Cmdlet 目前不支援位置。 你必須使用 Azure CLI 或 Azure 入口網站。

  1. 使用下列命令在生產位置中設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0：

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    在此範例中，分別將 <APP_NAME> 和 <RESOURCE_GROUP_NAME> 取代為函數應用程式的名稱和資源群組名稱。 此命令會導致在生產位置中執行的應用程式重新啟動。

  2. 使用下列命令在預備位置中設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS：

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. 使用下列命令，變更 FUNCTIONS_EXTENSION_VERSION 並將預備位置更新至新的執行階段版本：

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

  4. Functions 執行環境 4.x 版本在 Windows 中需要 .NET 6。 在 Linux 上，.NET 應用程式也必須更新到 .NET 6。 請使用以下指令，讓執行時能在 .NET 6 上執行：

    在 Windows 上執行時，你還需要啟用 .NET 8.0，這是執行環境版本 4.x 所要求的。

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

    .NET 6 是任何語言中運行 Windows 函式應用程式的必備條件。

    在此範例中，分別將 <APP_NAME> 和 <RESOURCE_GROUP_NAME> 取代為函數應用程式的名稱和資源群組名稱。

  5. 如果您的程式碼專案需要任何更新才能在 4.x 版上執行，請立即將這些更新部署到預備位置。

  6. 交換前，請確認函數應用程式在更新的預備環境中正確執行。

  7. 使用下列命令，將更新的預備位置交換至生產環境：

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

最短停機時間更新

若要盡可能減少生產應用程式中的停機時間，您可以將 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS 設定從預備位置交換至生產環境。 之後，您可以從預先載入的預備位置交換更新的版本。

  1. 使用下列命令在預備位置中設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0：

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  2. 使用下列命令，將位置與新的設定交換至生產環境，同時還原預備位置中的版本設定。

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production
az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~3 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    在交換及在預備環境上還原執行階段版本的期間，您可能會在預備位置上看到錯誤。 發生此錯誤的原因在於交換期間僅在預備位置設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0，這會移除預備位置中的 FUNCTIONS_EXTENSION_VERSION 設定。 如果沒有版本設定，您的位置會處於不良狀態。 在交換後立即更新預備位置中的版本，應該便能將位置恢復至良好的狀態，而您可視需要復原變更。 不過，若要復原任何交換，您需要在復原之前直接從生產環境移除 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0，以避免在預備環境中發生相同的錯誤。 然後，生產設定中的這項變更會導致重新開機。

  3. 使用下列命令再次在預備位置中設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0：

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    此時，這兩個位置都已設定 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0。

  4. 使用下列命令，變更 FUNCTIONS_EXTENSION_VERSION 並將預備位置更新至新的執行階段版本：

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

  5. Functions 執行環境 4.x 版本在 Windows 中需要 .NET 6。 在 Linux 上，.NET 應用程式也必須更新到 .NET 6。 請使用以下指令，讓執行時能在 .NET 6 上執行：

    在 Windows 上執行時，你還需要啟用 .NET 8.0，這是執行環境版本 4.x 所要求的。

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

    .NET 6 是任何語言中運行 Windows 函式應用程式的必備條件。

    在此範例中，分別將 <APP_NAME> 和 <RESOURCE_GROUP_NAME> 取代為函數應用程式的名稱和資源群組名稱。

  6. 如果您的程式碼專案需要任何更新才能在 4.x 版上執行，請立即將這些更新部署到預備位置。

  7. 交換前，請確認函數應用程式在更新的預備環境中正確執行。

  8. 使用下列命令，將已更新且預先載入的預備位置交換至實際執行環境：

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

3.x 與 4.x 之間的中斷性變更

以下是將 3.x 應用程式升級至 4.x 之前要注意的重要中斷性變更，包括語言特定的中斷性變更。 完整清單請參閱標示為破壞性變革：批准的Azure Functions GitHub議題。

如果您沒有看到程式設計語言，請從頁面頂端選取。

執行階段

  • Azure Functions 代理是 Azure Functions 執行環境版本 1.x 至 3.x 中的一項功能。 4.x 版不支援此功能。 欲了解更多資訊，請參閱 使用 Azure Functions 的 Serverless REST API。

  • 在 4.x 版本中，使用 AzureWebJobsDashboard 登入 Azure 儲存體 已不再支援。 您應該改用 Application Insights。 （#1923）

  • Azure Functions 4.x 現在強制執行擴充功能的最低版本要求。 更新至最新版本的受影響延伸模組。 對於非 .NET 語言，更新至擴展組件版本 2.x 或更高版本。 （#1987）

  • 在 4.x 中，對於使用量方案中在 Linux 上執行的函數應用程式，現在會強制執行預設和最大逾時。 （#1915）

  • Azure Functions 4.x 使用 Azure.Identity 和 Azure.Security.KeyVault.Secrets 做為 金鑰保存庫 供應商，並且已棄用 Microsoft.Azure.KeyVault。 想了解更多如何設定功能應用程式設定的資訊，請參考管理金鑰儲存中的金鑰保存庫選項。 （#2048）

  • 共用儲存體帳戶的函數應用程式現在在其機識別碼相同時無法啟動。 如需詳細資訊，請參閱主機識別碼考量。 （#2049）

  • Azure Functions 4.x 支援較新版本的 .NET。 完整版本列表請參閱 c0>支援語言。

  • InvalidHostServicesException 現在是嚴重錯誤。 （#2045）

  • EnableEnhancedScopes 預設為啟用。 （#1954）

  • 移除 HttpClient 為已註冊的服務。 （#1911）

  • 在 Java 11 中使用單一類別載入器。 （#1997）

  • 停止在 Java 8 載入 worker jars。 （#1991）

  • Node.js 10 和 12 版本在 4.x Azure Functions中不支援。 （#1999）

  • Node.js 應用程式中的輸出序列化已更新，以解決先前不一致的情況。 （#2007）

  • 預設執行緒計數已更新。 不是安全執行緒或具有高記憶體使用量的函式可能會受到影響。 （#1962）

  • Python 3.6 在 Azure Functions 4.x 中不被支援。 （#1999）

  • 預設會啟用共用記憶體傳輸。 （#1973）

  • 預設執行緒計數已更新。 不是安全執行緒或具有高記憶體使用量的函式可能會受到影響。 （#1962）

後續步驟

深入了解 Functions 版本

  • Last updated on