共用方式為

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

  • 發行項

重要

1.x 版的 Azure Functions 執行階段不支援 Java。 或許您想要將 Java 應用程式從 3.x 版移轉至 4.x 版。 如果您要移轉 1.x 版函數應用程式，請選取上述 C# 或 JavaScript。

重要

1.x 版的 Azure Functions 執行階段不支援 TypeScript。 或許您想要將 TypeScript 應用程式從 3.x 版移轉至 4.x 版。 如果您要移轉 1.x 版函數應用程式，請選取上述 C# 或 JavaScript。

重要

1.x 版的 Azure Functions 執行階段不支援 PowerShell。 或許您想要將 PowerShell 應用程式從 3.x 版移轉至 4.x 版。 如果您要移轉 1.x 版函數應用程式，請選取上述 C# 或 JavaScript。

重要

1.x 版的 Azure Functions 執行階段不支援 PowerShell。 或許您想要將 PowerShell 應用程式從 3.x 版移轉至 4.x 版。 如果您要移轉 1.x 版函數應用程式，請選取上述 C# 或 JavaScript。

重要

Azure Functions 執行階段 1.x 版的支援將於 2026 年 9 月 14 日結束。 強烈建議您遵循本文中的指示，將應用程式移轉至 4.x 版。

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

如果您在 Azure Stack Hub 中執行 1.x 版的執行階段，請參閱 Azure Stack Hub 的注意事項 (部分機器翻譯)。

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

使用下列 PowerShell 指令碼，以在您的訂用帳戶中產生目前以 1.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 '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

選擇您的目標 .NET 版本

在 Functions 執行階段 1.x 版上，您的 C# 函數應用程式會以 .NET Framework 為目標。

當您將函數應用程式移轉時，您有機會選擇 .NET 的目標版本。 您可以將 C# 專案更新為下列其中一個 Functions 4.x 版可支援的 .NET 版本：

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

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

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

提示

除非您的應用程式相依於僅限 .NET Framework 使用的程式庫或 API，否則建議您更新為採用隔離的背景工作角色模型的 .NET 8。 1.x 版上的許多應用程式只會以 .NET Framework 為目標，因為這是建立時可用的應用程式。 較新版本的 .NET 可以提供其他功能，如果您的應用程式因相依性而被迫留在 .NET Framework 上，則應以較新版本為目標。 .NET 8 是完整發行的版本，具有 .NET 所提供最長的支援時間範圍。

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

本指南未提供 .NET 9 的特定範例。 如果您需要以該版本為目標，您可以針對隔離的背景工作模型調整 .NET 8 範例。

為移轉做準備

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

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

  1. 檢閱 1.x 版之後的行為變更清單。 從 1.x 版移轉至 4.x 版也可能會影響繫結。
  2. 完成移轉本機專案中的步驟，將您的本機專案移轉至 4.x 版。
  3. 移轉專案之後，請使用 4.x 版的 Azure Functions Core Tools，在本機完整測試應用程式。
  4. 將 Azure 中的函數應用程式更新至新版本。 如果您需要將停機時間降到最低，請考慮使用預備位置，在 Azure 中測試及驗證新執行階段版本的已移轉應用程式。 接著，您可以使用更新的版本設定將應用程式部署至生產位置。 如需詳細資訊，請參閱使用位置更新。
  5. 將移轉的專案發佈至更新的函數應用程式。

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

移轉本機專案

下列各節說明您必須對 C# 專案檔進行的更新，才能在 Functions 4.x 版中其中一個支援的 .NET 版本上執行。 顯示的更新是大部分專案通用的更新。 您的專案程式碼可能需要本文未提及的更新，特別是在使用自訂 NuGet 套件時。

將 C# 函數應用程式從 1.x 版移轉至 4.x 版的 Functions 執行階段，需要您對專案程式碼進行變更。 其中許多變更都是 C# 語言和 .NET API 的變更結果。

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

提示

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

專案檔

下列範例是在 1.x 版上執行的 .csproj 專案檔：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </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.*。

通知中樞和 Mobile Apps 繫結只在執行階段 1.x 版支援。 升級至運執行階段 4.x 版時，您必須移除這些繫結，以便直接使用其 SDK 來使用這些服務。

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 屬性及其套用的類別。

host.json 檔案

host.json 檔案中的設定會在本機和 Azure 中的函數應用程式層級套用。 在 1.x 版中，host.json 檔案是空的，或是包含一些套用至函數應用程式中所有函式的設定。 如需詳細資訊，請參閱 Host.json v1。 如果您的 host.json 檔案有設定值，請檢閱 host.json v2 格式是否有任何變更。

若要在 4.x 版上執行，您必須將 "version": "2.0" 新增至 host.json 檔案。 您也應該考慮將 logging 新增至設定，如下列範例所示：

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

此 host.json 檔案只會控制來自 Functions 主機執行階段的記錄，而隔離的背景工作角色模型中，這些記錄中其中有一些會直接來自您的應用程式，讓您有更多控制權。 如需如何篩選這些記錄的詳細資料，請參閱在隔離的背景工作模型中管理記錄層級。

local.settings.json 檔案

local.settings.json 檔案只有在本機執行時才會使用。 如需詳細資訊，請參閱本機設定檔。 在 1.x 版中，local.settings.json 檔案只有兩個必要值：

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "AzureWebJobsDashboard": "AzureWebJobsStorageConnectionStringValue"
    }
}

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

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

注意

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

類別名稱變更

某些索引鍵類別已變更 1.x 版與 4.x 版之間的名稱。 這些變更是 .NET API 中變更的結果，或是內含式與隔離式背景工作處理序之間的差異。 下表指出 Azure Functions 在移轉時可能會變更的主要 .NET 類別：

1.x 版 .NET 8
FunctionName (屬性) Function (屬性)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData、HttpRequest (使用 ASP.NET Core 整合)
HttpResponseMessage HttpResponseData、IActionResult (使用 ASP.NET Core 整合)

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

其他程式碼變更

本節會強調當您完成移轉時所要考量的其他程式碼變更。 並非所有應用程式都需要這些變更，但您應該評估是否有任何變更與您的案例相關。 務必檢查 1.x 版之後的行為變更，以取得您可能需要對專案進行的其他變更。

JSON 序列化

根據預設，隔離的背景工作角色模型會使用 System.Text.Json 進行 JSON 序列化。 若要自訂序列化程式選項或切換至 JSON.NET (Newtonsoft.Json)，請參閱這些指示。

Application Insights 記錄層級和篩選

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

HTTP 觸發程序範本

在 HTTP 觸發函式中看到 1.x 版與 4.x 版之間的大部分程式碼變更。 1.x 版的 HTTP 觸發程序範本看起來如下列範例所示：

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

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

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

在 4.x 版中，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. 請移至其中一個 4.x 版支援的 Node.js 版本。

  3. 將 version 和 extensionBundle 元素新增至 host.json，使其看起來如下列範例所示：

    {
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

    extensionBundle 元素是必要的，因為 1.x 版之後，繫節是以外部套件的形式來維護。 如需詳細資訊，請參閱延伸模組套件組合。

  4. 更新 local.settings.json 檔案，使其至少有下列元素：

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    AzureWebJobsStorage 設定可以是 Azurite 儲存體模擬器或實際的 Azure 儲存體帳戶。 如需詳細資訊，請參閱本機儲存體模擬器。

在 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

1.x 版之後的行為變更

本節詳述在觸發程序和繫結行為以及核心函式功能和行為 1.x 版之後所做的變更。

觸發程序與繫結中的變更

從 2.x 版開始，您必須針對應用程式中函式所使用的特定觸發程序和繫結安裝擴充功能。 唯一的例外是 HTTP 和計時器觸發程序，這兩者不需要延伸模組。 如需詳細資訊，請參閱註冊及安裝繫結延伸模組。

function.json 或函式的屬性在版本之間也有一些變更。 例如，事件中樞的 path 屬性現在是 eventHubName。 如需每個繫結的文件連結，請參閱現有的繫結表格。

功能方面的變更

1.x 版之後已移除、更新或取代一些功能。 本節詳細說明在您使用 1.x 版之後，在更新版本中會看到的變更。

2.x 版中做了下列變更：

  • 用於呼叫 HTTP 端點的金鑰一律會以加密形式儲存在 Azure Blob 儲存體中。 在 1.x 版中，金鑰預設是儲存在 Azure 檔案儲存體中。 當您將應用程式從 1.x 版移轉至 2.x 版時，會重設 Azure 檔案儲存體中的現有祕密。

  • 2.x 版執行階段並未內建對 Webhook 提供者的支援。 進行此變更是為了改善效能。 您仍然可以使用 HTTP 觸發程序作為 Webhook 的端點。

  • 為了改進監視功能，已將入口網站中使用 AzureWebJobsDashboard 設定的 WebJobs 儀表板，取代成使用 APPINSIGHTS_INSTRUMENTATIONKEY 設定的 Azure Application Insights。 如需詳細資訊，請參閱監視 Azure Functions。

  • 函數應用程式中的所有函式都必須共用相同語言。 當您建立函數應用程式時，必須為應用程式選擇執行階段堆疊。 執行階段堆疊會由應用程式設定中的 FUNCTIONS_WORKER_RUNTIME 值指定。 新增此需求是為了改善使用量和啟動時間。 在本機進行開發時，您必須在 local.settings.json 檔案中也包含此設定。

  • App Service 方案中函式的預設逾時已變更為 30 分鐘。 您可以藉由在 host.json 中使用 functionTimeout 設定，將逾時手動變更回無限制。

  • 預設會針對使用情況方案函式實作 HTTP 並行節流，預設值為每一執行個體 100 個並行要求。 您可以在 host.json 檔案中的 maxConcurrentRequests 設定中變更此行為。

  • 由於 .NET Core 限制的緣故，已移除對 F# 指令碼 (.fsx 檔案) 函式的支援。 仍然支援已編譯的 F# 函式 (.fs)。

  • 「事件方格」觸發程序 Webhook 的 URL 格式已變更為遵循下列模式： https://{app}/runtime/webhooks/{triggerName}。

  • 1.x 版之後，某些預先定義的自訂計量名稱已變更。 Duration 已取代為 MaxDurationMs、MinDurationMs和 AvgDurationMs。 Success Rate 也重新命名為 Success Rate。

Azure Stack Hub 的注意事項

Azure Stack Hub 上的 App Service 不支援 Azure Functions 4.x 版。 當您在 Azure Stack Hub 中規劃從 1.x 版移轉時，您可以選擇下列其中一個選項：

  • 使用本文中的指示，移轉至裝載於公用雲端 Azure Functions 中的 4.x 版。 與其升級現有的應用程式，不如使用 4.x 版建立新的應用程式，然後將所修改的專案部署至其中。
  • 切換至 Azure Stack Hub 中 App Service 方案上裝載的 WebJobs。

下一步

深入了解 Functions 版本