共用方式為

將應用程式從 Azure Functions 3.x 版移轉至 4.x 版

  • 發行項

Azure Functions 4.x 版與 3.x 版有高度回溯相容性。 大部分應用程式應該都可以安全地移轉至 4.x，不需要重大程式碼變更。 如需有關 Functions 執行階段版本的詳細資訊，請參閱 Azure Functions 執行階段版本概觀。

重要

自 2022 年 12 月 13 日起，在 Azure Functions 執行階段 2.x 和 3.x 版上執行的函數應用程式已終止延伸支援。 如需詳細資訊，請參閱已淘汰的版本。

本文將逐步引導您完成安全地移轉函數應用程式，以在 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 8 LTS (2026 年 11 月 10 日終止支援) 隔離式背景工作角色模型、
同處理序模型2、3
.NET 6 LTS (2024 年 11 月 12 日終止支援) 隔離式背景工作角色模型、
同處理序模型2
.NET Framework 4.8 請參閱原則 隔離式背景工作角色模型

1隔離式背景工作角色模型支援 .NET 的長期支援 (LTS) 和標準期限支援 (STS) 版本，以及 .NET Framework。 同處理序模型僅支援 .NET 的 LTS 版本，結尾為 .NET 8。 如需兩個模型之間的完整特性和功能比較，請參閱內含式和隔離式背景工作處理序 .NET Azure Functions 之間的差異。

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

3 尚未針對 Linux、針對裝載於 App Service 環境中的應用程式，或針對主權雲端中的應用程式，啟用以使用同處理序模型的 .NET 8 為目標。 更新將透過 GitHub 上的此追蹤執行緒 (英文) 傳達。

提示

建議您在隔離的背景工作角色模型上更新至 .NET 8。 .NET 8 是完整發行的版本，具有 .NET 所提供最長的支援時間範圍。

雖然您可以選擇改用同處理序模型，但如果可以避免，則不建議這麼做。 針對同處理序模型的支援將於 2026年 11 月 10 日結束 (英文)，因此您必須在該時間之前先移至隔離的背景工作角色模型。 在移轉至版本 4.x 時這樣做會減少所需的總工作量，而隔離的背景工作角色模型會提供您的應用程式額外的優點 (部分機器翻譯)，包括更容易以未來 .NET 版本為目標的能力。 如果您要移至隔離的背景工作角色模型，.NET 升級小幫手也可以為您處理許多必要的程式碼變更。

本指南未提供 .NET 6 的特定範例。 如果您需要以該版本為目標，可以調整 .NET 8 範例。

為移轉做準備

如果您尚未這麼做，請使用 Azure PowerShell 來識別需要在目前 Azure 訂用帳戶中移轉的應用程式清單。

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

  1. 檢閱 3.x 與 4.x 之間的重大變更清單。
  2. 完成移轉本機專案中的步驟，將您的本機專案移轉至 4.x 版。
  3. 移轉專案之後，請使用 4.x 版的 Azure Functions Core Tools，在本機完整測試應用程式。
  4. 在裝載於 Azure 的應用程式上執行升級前驗證程式，並解決任何已識別的問題。
  5. 將 Azure 中的函數應用程式更新至新版本。 如果您需要將停機時間降到最低，請考慮使用預備位置，在 Azure 中測試及驗證新執行階段版本的已移轉應用程式。 接著，您可以使用更新的版本設定將應用程式部署至生產位置。 如需詳細資訊，請參閱使用位置更新。
  6. 將移轉的專案發佈至更新的函數應用程式。

在使用 Visual Studio 將 4.x 版專案發佈至較低版本的現有函數應用程式時，系統會提示您在部署期間讓 Visual Studio 將該函數應用程式更新至 4.x 版。 此次更新會使用無位置更新中定義的相同流程。

移轉本機專案

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

選擇符合目標 .NET 版本的索引標籤，以及所需的處理序模型 (內含式或隔離式背景工作處理序)。

提示

如果您要使用隔離式背景工作角色模型移至 .NET 的 LTS 或 STS 版本，可以使用 .NET 升級小幫手來自動進行下列各節所述的許多變更。

專案檔

下列範例是 .csproj 專案檔，在 3.x 版上使用 .NET Core 3.1：

<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 陳述式的命名空間，以及您參考的一些類型。 您可以在本文後面的 HTTP 觸發程序範本範例中看到這些命名空間變更對 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
長期函式 將參考取代為
Microsoft.Azure.WebJobs.Extensions.DurableTask
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
長期函式
(SQL 儲存體提供者)		 將參考取代為
Microsoft.DurableTask.SqlServer.AzureFunctions
最新版本的
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
長期函式
(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 類型，無論是作為觸發程式和繫結的一部分，還是獨立相依性。 您也應該利用這個機會來更新這些項目。 最新版的 Functions 延伸模組會與適用於 .NET 的 Azure SDK 最新版本搭配運作，其幾乎所有套件的格式都是 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 的參考。 不過，為了獲得最佳效能，甚至是其他觸發程序類型的函式，您也應該保留對 ASP.NET Core 的 FrameworkReference。

Program.cs 檔案會取代具有 FunctionsStartup 屬性的任何檔案，通常為 Startup.cs 檔案。 在 FunctionsStartup 程式碼參考 IFunctionsHostBuilder.Services 的位置，您可以改為在 Program.cs 中 HostBuilder 的 .ConfigureServices() 方法內新增陳述式。 若要深入了解如何使用 Program.cs，請參閱隔離的背景工作角色模型指南中的啟動和設定。

以上預設 Program.cs 範例包括設定隔離背景工作角色模型的 Application Insights 整合 (部分機器翻譯)。 在您的 Program.cs 中，您也必須設定任何應套用至專案中程式碼所產生記錄的任何記錄篩選。 在隔離的背景工作角色模型中，host.json 檔案只會控制 Functions 主機執行階段發出的事件。 如果您未在 Program.cs 中設定篩選規則，可能會看到遙測中各種類別的記錄層級差異。

雖然您可以將自訂設定來源註冊為 HostBuilder 的一部分，但請注意，這些同樣僅適用於您專案中的程式碼。 平台也需要觸發和繫結設定，這應該透過應用程式組態 (部分機器翻譯)、Key Vault 參考 (部分機器翻譯)，或應用程式組態參考 (部分機器翻譯) 功能來提供。

一旦您將現有 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 中變更的結果，或是內含式與隔離式背景工作處理序之間的差異。 下表指出 Azure Functions 在移轉時可能會變更的主要 .NET 類別：

.NET Core 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)，請參閱這些指示。

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 提供升級前驗證程式，可協助您識別將函數應用程式移轉至 4.x 時的潛在問題。 若要執行升級前驗證程式：

  1. 在 Azure 入口網站中，瀏覽至您的函式應用程式。

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

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

  4. 驗證完成後，請檢閱建議並解決您應用程式中的任何問題。 如果您需要對應用程式進行變更，請務必使用 Azure Functions Core Tools v4 或使用預備位置，在本機驗證 Azure Functions 執行階段 4.x 版的變更。

在 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 上執行時，您也需要啟用執行階段 4.x 版所需的 .NET 6.0。

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

Windows 上所執行任何語言的函數應用程式都需要 .NET 6。

在此範例中，分別將 <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. 在 Windows 中，Azure Functions 執行階段 4.x 版需要 .NET 6。 在 Linux 上，.NET 應用程式也必須更新至 .NET 6。 使用下列命令，讓執行階段也可以在 .NET 6 上執行：

    在 Windows 上執行時，您也需要啟用執行階段 4.x 版所需的 .NET 6.0。

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

    Windows 上所執行任何語言的函數應用程式都需要 .NET 6。

    在此範例中，分別將 <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. 在 Windows 中，Azure Functions 執行階段 4.x 版需要 .NET 6。 在 Linux 上，.NET 應用程式也必須更新至 .NET 6。 使用下列命令，讓執行階段也可以在 .NET 6 上執行：

    在 Windows 上執行時，您也需要啟用執行階段 4.x 版所需的 .NET 6.0。

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

    Windows 上所執行任何語言的函數應用程式都需要 .NET 6。

    在此範例中，分別將 <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 Proxy 是 Azure Functions 執行階段 1.x 版到 3.x 版的舊版功能。 可在 4.x 版中重新啟用 Functions Proxy 的支援，以便您可以成功將函數應用程式更新至最新的執行階段版本。 您應儘快切換為將函數應用程式與 Azure API 管理整合。 APIM 可讓您利用一組更完整的功能，來定義、保護、管理以 Functions 為基礎的 API 並從中獲利。 如需詳細資訊，請參閱 API 管理整合。 若要了解如何在 Functions 4.x 版中重新啟用 Proxy 支援，請參閱在 Functions 4.x 版中重新啟用 Proxy。

  • 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 6 內含式和隔離式應用程式。

  • InvalidHostServicesException 現在是嚴重錯誤。 (#2045)

  • EnableEnhancedScopes 預設為啟用。 (#1954)

  • 移除 HttpClient 為已註冊的服務。 (#1911)

  • 在 JAVA 11 中使用單一類別載入器。 (#1997)

  • 停止在 JAVA 8 中載入背景工作角色 jar。 (#1991)

  • Azure Functions 4.x 不支援 Node.js 10 和 12 版。 (#1999)

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

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

  • Azure Functions 4.x 中不支援 Python 3.6。 (#1999)

  • 預設會啟用共用記憶體傳輸。 (#1973)

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

下一步

深入了解 Functions 版本