將應用程式從 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 官方支援原則版本類型 函式處理模型1,3
.NET 82 LTS 隔離式背景工作角色模型
.NET 7 STS (2024 年 5 月 14 日終止支援) 隔離式背景工作角色模型
.NET 6 LTS (2024 年 11 月 12 日終止支援) 隔離式背景工作角色模型、
進程內模型3
.NET Framework 4.8 請參閱原則 隔離式背景工作角色模型

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

2 內含式模型尚不支援 .NET 8，但可在隔離式背景工作角色模型上使用。 如需 .NET 8 方案的相關資訊，包括內含式模型的未來選項，請參閱 Azure Functions 藍圖更新文章。

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

提示

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

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

本指南不會在隔離式背景工作角色模型上呈現 .NET 7 或 .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 觸發程式，可以將的呼叫取代為的ConfigureFunctionsWorkerDefaults呼叫ConfigureFunctionsWebApplication。 如果這樣做，您可以從項目檔中移除 的 Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore 參考。 不過，為了獲得最佳效能，即使是其他觸發程式類型的函式，您也應該保留 FrameworkReference ASP.NET Core。

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一部分，但請注意，這些同樣適用於專案中的程序代碼。 平臺也需要觸發程式和系結組態，而且這應該透過應用程式設定、金鑰保存庫 參考或 應用程式組態 參考功能來提供。

一旦您將現有 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 記錄層級和篩選

記錄可以從函式主機運行時間和專案中的程式代碼傳送至 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 版本