將應用程式從 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 官方支援原則版本類型 函式處理模型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 Framework 可用的連結庫或 API，否則建議您在隔離的背景工作模型上更新為 .NET 8。 1.x 版上的許多應用程式只會以 .NET Framework 為目標，因為這是建立時可用的應用程式。 較新版本的 .NET 可以提供其他功能，如果您的應用程式因相依性而被迫留在 .NET Framework 上，則應以較新版本為目標。 .NET 8 是完整發行的版本，具有 .NET 所提供最長的支援時間範圍。

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

本指南不會在隔離式背景工作角色模型上呈現 .NET 7 或 .NET 6 的特定範例。 如果您需要以這些版本為目標，您可以調整 .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 觸發程式，可以將的呼叫取代為的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 屬性及其套用的類別。

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 記錄層級和篩選

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