Memigrasikan aplikasi dari Azure Functions versi 1.x ke versi 4.x

  • Artikel

Penting

Java tidak didukung oleh runtime Azure Functions versi 1.x. Mungkin Anda ingin memigrasikan aplikasi Java Anda dari versi 3.x ke versi 4.x. Jika Anda memigrasikan aplikasi fungsi versi 1.x, pilih C# atau JavaScript di atas.

Penting

TypeScript tidak didukung oleh runtime Azure Functions versi 1.x. Mungkin Anda ingin memigrasikan aplikasi TypeScript Anda dari versi 3.x ke versi 4.x. Jika Anda memigrasikan aplikasi fungsi versi 1.x, pilih C# atau JavaScript di atas.

Penting

PowerShell tidak didukung oleh runtime Azure Functions versi 1.x. Mungkin Anda ingin memigrasikan aplikasi PowerShell Anda dari versi 3.x ke versi 4.x. Jika Anda memigrasikan aplikasi fungsi versi 1.x, pilih C# atau JavaScript di atas.

Penting

Python tidak didukung oleh runtime Azure Functions versi 1.x. Mungkin Anda ingin memigrasikan aplikasi Python Anda dari versi 3.x ke versi 4.x. Jika Anda memigrasikan aplikasi fungsi versi 1.x, pilih C# atau JavaScript di atas.

Penting

Dukungan akan berakhir untuk runtime Azure Functions versi 1.x pada 14 September 2026. Kami sangat menyarankan Anda untuk memigrasikan aplikasi Anda ke versi 4.x dengan mengikuti instruksi dalam artikel ini.

Artikel ini memandu Anda melalui proses migrasi aplikasi fungsi anda dengan aman untuk berjalan pada runtime Functions versi 4.x. Karena instruksi migrasi proyek bergantung pada bahasa, pastikan untuk memilih bahasa pengembangan Anda dari pemilih di bagian atas artikel.

Jika Anda menjalankan runtime versi 1.x di Azure Stack Hub, lihat Pertimbangan untuk Azure Stack Hub terlebih dahulu.

Mengidentifikasi aplikasi fungsi untuk dimigrasikan

Gunakan skrip PowerShell berikut untuk menghasilkan daftar aplikasi fungsi di langganan Anda yang saat ini menargetkan versi 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

Pilih versi .NET target Anda

Pada runtime Functions versi 1.x, aplikasi fungsi C# Anda menargetkan .NET Framework.

Saat memigrasikan aplikasi fungsi, Anda memiliki kesempatan untuk memilih versi target .NET. Anda dapat memperbarui proyek C# Anda ke salah satu versi .NET berikut yang didukung oleh Functions versi 4.x:

Versi .NET Jenis rilis Kebijakan Dukungan Resmi .NET Modelproses fungsi 1,3
.NET 82 LTS Model pekerja terisolasi
.NET 7 STS (akhir dukungan 14 Mei 2024) Model pekerja terisolasi
.NET 6 LTS (akhir dukungan 12 November 2024) Model pekerja terisolasi,
Model dalam proses3
.NET Framework 4.8 Lihat kebijakan Model pekerja terisolasi

1 Model pekerja yang terisolasi mendukung versi Dukungan Jangka Panjang (LTS) dan Standard Term Support (STS) .NET, serta .NET Framework. Model dalam proses hanya mendukung rilis LTS .NET. Untuk perbandingan fitur dan fungsionalitas lengkap antara kedua model, lihat Perbedaan antara proses dalam proses dan mengisolasi proses pekerja .NET Azure Functions.

2 .NET 8 belum didukung pada model dalam proses, meskipun tersedia pada model pekerja yang terisolasi. Untuk informasi tentang paket .NET 8, termasuk opsi di masa mendatang untuk model dalam proses, lihat posting Pembaruan Peta Jalan Azure Functions.

3 Dukungan berakhir untuk model dalam proses pada 10 November 2026. Untuk informasi selengkapnya, lihat pengumuman dukungan ini. Untuk dukungan penuh berkelanjutan, Anda harus memigrasikan aplikasi Anda ke model pekerja yang terisolasi.

Tip

Kecuali aplikasi Anda bergantung pada pustaka atau API yang hanya tersedia untuk .NET Framework, sebaiknya perbarui ke .NET 8 pada model pekerja yang terisolasi. Banyak aplikasi pada .NET Framework target versi 1.x hanya karena itulah yang tersedia saat dibuat. Kemampuan tambahan tersedia untuk versi .NET yang lebih baru, dan jika aplikasi Anda tidak dipaksa untuk tetap berada di .NET Framework karena dependensi, Anda harus menargetkan versi yang lebih baru. .NET 8 adalah versi yang dirilis sepenuhnya dengan jendela dukungan terpanjang dari .NET.

Meskipun Anda dapat memilih untuk menggunakan model dalam proses, ini tidak disarankan jika dapat dihindari. Dukungan akan berakhir untuk model dalam proses pada 10 November 2026, jadi Anda harus pindah ke model pekerja yang terisolasi sebelum itu. Melakukannya saat bermigrasi ke versi 4.x akan mengurangi total upaya yang diperlukan, dan model pekerja yang terisolasi akan memberikan manfaat tambahan aplikasi Anda, termasuk kemampuan untuk lebih mudah menargetkan versi .NET di masa mendatang. Jika Anda pindah ke model pekerja yang terisolasi, Asisten Peningkatan .NET juga dapat menangani banyak perubahan kode yang diperlukan untuk Anda.

Panduan ini tidak menyajikan contoh spesifik untuk .NET 7 atau .NET 6 pada model pekerja yang terisolasi. Jika Anda perlu menargetkan versi ini, Anda dapat menyesuaikan contoh model pekerja terisolasi .NET 8.

Penyiapan untuk migrasi

Jika Anda belum melakukannya, identifikasi daftar aplikasi yang perlu dimigrasikan di Langganan Azure Anda saat ini dengan menggunakan Azure PowerShell.

Sebelum memigrasikan aplikasi ke versi 4.x dari runtime Functions, Anda harus melakukan tugas berikut:

  1. Tinjau daftar perubahan perilaku setelah versi 1.x. Migrasi dari versi 1.x ke versi 4.x juga dapat memengaruhi pengikatan.
  2. Selesaikan langkah-langkah dalam Memigrasikan proyek lokal Anda untuk memigrasikan proyek lokal Anda ke versi 4.x.
  3. Setelah memigrasikan proyek Anda, uji sepenuhnya aplikasi secara lokal menggunakan versi 4.x dari Azure Functions Core Tools.
  4. Perbarui aplikasi fungsi Anda di Azure ke versi baru. Jika Anda perlu meminimalkan waktu henti, pertimbangkan untuk menggunakan slot penahapan untuk menguji dan memverifikasi aplikasi yang dimigrasikan di Azure pada versi runtime baru. Anda kemudian dapat menyebarkan aplikasi dengan pengaturan versi yang diperbarui ke slot produksi. Untuk informasi selengkapnya, lihat Memperbarui menggunakan slot.
  5. Terbitkan proyek yang dimigrasikan ke aplikasi fungsi yang diperbarui.

Saat Anda menggunakan Visual Studio untuk menerbitkan proyek versi 4.x ke aplikasi fungsi yang ada pada versi yang lebih rendah, Anda diminta untuk mengizinkan Visual Studio memperbarui aplikasi fungsi ke versi 4.x selama penyebaran. Pembaruan ini menggunakan proses yang sama yang ditentukan dalam Pembaruan tanpa slot.

Memigrasikan proyek lokal Anda

Bagian berikut menjelaskan pembaruan yang harus Anda buat ke file proyek C# Anda agar dapat berjalan pada salah satu versi .NET yang didukung di Functions versi 4.x. Pembaruan yang ditampilkan adalah yang umum untuk sebagian besar proyek. Kode proyek Anda dapat memerlukan pembaruan yang tidak disebutkan dalam artikel ini, terutama saat menggunakan paket NuGet kustom.

Memigrasikan aplikasi fungsi C# dari versi 1.x ke versi 4.x dari runtime Functions mengharuskan Anda membuat perubahan pada kode proyek Anda. Banyak dari perubahan ini adalah hasil dari perubahan dalam bahasa C# dan API .NET.

Pilih tab yang cocok dengan versi target .NET Anda dan model proses yang diinginkan (dalam proses atau proses pekerja terisolasi).

Tip

Jika Anda pindah ke versi LTS atau STS .NET menggunakan model pekerja yang terisolasi, Asisten Peningkatan .NET dapat digunakan untuk secara otomatis membuat banyak perubahan yang disebutkan di bagian berikut.

File proyek

Contoh berikut adalah .csproj file proyek yang berjalan pada versi 1.x:

<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>

Gunakan salah satu prosedur berikut untuk memperbarui file XML ini agar berjalan di Functions versi 4.x:

Langkah-langkah ini mengasumsikan proyek C# lokal, dan jika aplikasi Anda menggunakan skrip C# (.csx file), Anda harus mengonversi ke model proyek sebelum melanjutkan.

Perubahan berikut diperlukan dalam .csproj file proyek XML:

  1. Atur nilai .PropertyGroupTargetFramework ke net8.0.

  2. Atur nilai .PropertyGroupAzureFunctionsVersion ke v4.

  3. Tambahkan elemen berikut OutputType ke PropertyGroup:

    <OutputType>Exe</OutputType>

  4. ItemGroupDalam .PackageReference daftar, ganti referensi paket ke Microsoft.NET.Sdk.Functions dengan referensi berikut:

      <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" />

    Catat referensi apa pun ke paket lain di Microsoft.Azure.WebJobs.* namespace layanan. Anda akan mengganti paket ini di langkah selanjutnya.

  5. Tambahkan baru ItemGroupberikut ini :

    <ItemGroup>
  <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
</ItemGroup>

Setelah Anda membuat perubahan ini, proyek yang diperbarui akan terlihat seperti contoh berikut:

<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>

Perubahan paket dan namespace

Berdasarkan model yang Anda migrasikan, Anda mungkin perlu memperbarui atau mengubah paket referensi aplikasi Anda. Saat mengadopsi paket target, Anda kemudian perlu memperbarui namespace penggunaan pernyataan dan beberapa jenis yang Anda referensikan. Anda dapat melihat efek perubahan namespace ini pada using pernyataan dalam contoh templat pemicu HTTP nanti di artikel ini.

Jika Anda belum melakukannya, perbarui proyek Anda untuk mereferensikan versi stabil terbaru dari:

Bergantung pada pemicu dan pengikatan yang digunakan aplikasi Anda, aplikasi Anda mungkin perlu mereferensikan serangkaian paket yang berbeda. Tabel berikut ini memperlihatkan penggantian untuk beberapa ekstensi yang paling umum digunakan:

Skenario Perubahan pada referensi paket
Pemicu pengatur waktu Menambahkan
Microsoft.Azure.Functions.Worker.Extensions.Timer
Pengikatan penyimpanan Menggantikan
Microsoft.Azure.WebJobs.Extensions.Storage
dengan
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues, dan
Microsoft.Azure.Functions.Worker.Extensions.Tables
Pengikatan blob Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Pengikatan antrean Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Pengikatan tabel Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.Tables
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.Tables
Pengikatan Cosmos DB Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.CosmosDB
dan/atau
Microsoft.Azure.WebJobs.Extensions.DocumentDB
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
pengikatan Bus Layanan Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.ServiceBus
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Pengikatan Azure Event Hubs Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.EventHubs
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Pengikatan Event Grid Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.EventGrid
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Pengikatan SignalR Service Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.SignalRService
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Fungsi Tahan Lama Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.DurableTask
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Fungsi Tahan Lama
(Penyedia penyimpanan SQL)		 Ganti referensi ke
Microsoft.DurableTask.SqlServer.AzureFunctions
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Fungsi Tahan Lama
(Penyedia penyimpanan netherite)		 Ganti referensi ke
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Pengikatan SendGrid Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.SendGrid
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Pengikatan Kafka Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.Kafka
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Pengikatan RabbitMQ Ganti referensi ke
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
dengan versi terbaru
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Injeksi dependensi
dan konfigurasi startup		 Hapus referensi ke
Microsoft.Azure.Functions.Extensions
(Model pekerja yang terisolasi menyediakan fungsionalitas ini secara default.)

Lihat Pengikatan yang didukung untuk daftar lengkap ekstensi yang perlu dipertimbangkan, dan lihat dokumentasi setiap ekstensi untuk instruksi penginstalan lengkap untuk model proses yang terisolasi. Pastikan untuk menginstal versi stabil terbaru dari paket apa pun yang Anda targetkan.

Tip

Setiap perubahan pada versi ekstensi selama proses ini mungkin mengharuskan Anda untuk memperbarui file Anda host.json juga. Pastikan untuk membaca dokumentasi setiap ekstensi yang Anda gunakan. Misalnya, ekstensi Bus Layanan memiliki perubahan yang merusak dalam struktur antara versi 4.x dan 5.x. Untuk informasi selengkapnya, lihat Pengikatan Azure Bus Layanan untuk Azure Functions.

Aplikasi model pekerja terisolasi Anda tidak boleh mereferensikan paket apa pun di Microsoft.Azure.WebJobs.* namespace layanan atau Microsoft.Azure.Functions.Extensions. Jika Anda memiliki referensi yang tersisa untuk ini, referensi tersebut harus dihapus.

Tip

Aplikasi Anda mungkin juga bergantung pada jenis Azure SDK, baik sebagai bagian dari pemicu dan pengikatan Anda atau sebagai dependensi mandiri. Anda harus mengambil kesempatan ini untuk memperbarui ini juga. Versi terbaru ekstensi Functions berfungsi dengan versi terbaru Azure SDK untuk .NET, hampir semua paket yang merupakan formulir Azure.*.

Pengikatan Notification Hubs dan Mobile Apps hanya didukung di runtime versi 1.x. Saat meningkatkan ke runtime versi 4.x, Anda perlu menghapus pengikatan ini untuk bekerja dengan layanan ini secara langsung menggunakan SDK mereka.

file Program.cs

Dalam kebanyakan kasus, migrasi mengharuskan Anda untuk menambahkan file program.cs berikut ke proyek Anda:

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

Contoh ini mencakup integrasi ASP.NET Core untuk meningkatkan performa dan menyediakan model pemrograman yang familier saat aplikasi Anda menggunakan pemicu HTTP. Jika Anda tidak berniat menggunakan pemicu HTTP, Anda dapat mengganti panggilan ke ConfigureFunctionsWebApplication dengan panggilan ke ConfigureFunctionsWorkerDefaults. Jika Anda melakukannya, Anda dapat menghapus referensi ke Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore dari file proyek Anda. Namun, untuk performa terbaik, bahkan untuk fungsi dengan jenis pemicu lainnya, Anda harus menyimpan FrameworkReference ke ASP.NET Core.

File Program.cs akan menggantikan file apa pun yang memiliki FunctionsStartup atribut , yang biasanya merupakan Startup.cs file. Di tempat-tempat di mana kode Anda FunctionsStartup akan mereferensikan IFunctionsHostBuilder.Services, Anda dapat menambahkan pernyataan dalam .ConfigureServices() metode HostBuilder di .Program.cs Untuk mempelajari selengkapnya tentang bekerja dengan Program.cs, lihat Start-up dan konfigurasi dalam panduan model pekerja yang terisolasi.

Contoh default Program.cs di atas mencakup penyiapan integrasi Application Insights untuk model pekerja yang terisolasi. Program.csDi , Anda juga harus mengonfigurasi pemfilteran log apa pun yang harus berlaku untuk log yang berasal dari kode dalam proyek Anda. Dalam model pekerja yang terisolasi, host.json file hanya mengontrol peristiwa yang dipancarkan oleh runtime host Functions. Jika Anda tidak mengonfigurasi aturan pemfilteran di Program.cs, Anda mungkin melihat perbedaan tingkat log yang ada untuk berbagai kategori dalam telemetri Anda.

Meskipun Anda dapat mendaftarkan sumber konfigurasi kustom sebagai bagian HostBuilderdari , perhatikan bahwa ini juga hanya berlaku untuk kode dalam proyek Anda. Konfigurasi pemicu dan pengikatan juga diperlukan oleh platform, dan ini harus disediakan melalui pengaturan aplikasi, referensi Key Vault, atau fitur referensi App Configuration.

Setelah memindahkan semuanya dari yang ada FunctionsStartup ke Program.cs file, Anda dapat menghapus FunctionsStartup atribut dan kelas tempat atribut tersebut diterapkan.

file host.json

Pengaturan dalam file host.json berlaku di tingkat aplikasi fungsi, baik secara lokal maupun di Azure. Di versi 1.x, file host.json Anda kosong atau berisi beberapa pengaturan yang berlaku untuk semua fungsi di aplikasi fungsi. Untuk informasi selengkapnya, lihat Host.json v1. Jika file host.json Anda memiliki nilai pengaturan, tinjau format host.json v2 untuk perubahan apa pun.

Untuk berjalan pada versi 4.x, Anda harus menambahkan "version": "2.0" ke file host.json. Anda juga harus mempertimbangkan logging untuk menambahkan ke konfigurasi Anda, seperti dalam contoh berikut:

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

File host.json hanya mengontrol pengelogan dari runtime host Functions, dan dalam model pekerja yang terisolasi, beberapa log ini berasal dari aplikasi Anda secara langsung, memberi Anda lebih banyak kontrol. Lihat Mengelola tingkat log dalam model pekerja yang terisolasi untuk detail tentang cara memfilter log ini.

file local.settings.json

File local.settings.json hanya digunakan saat berjalan secara lokal. Untuk informasi, lihat File pengaturan lokal. Dalam versi 1.x, file local.settings.json hanya memiliki dua nilai yang diperlukan:

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

Saat Anda bermigrasi ke versi 4.x, pastikan file local.settings.json Anda memiliki setidaknya elemen berikut:

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

Catatan

Saat bermigrasi dari menjalankan dalam proses ke berjalan dalam proses pekerja yang terisolasi, Anda perlu mengubah nilai menjadi FUNCTIONS_WORKER_RUNTIME "dotnet-isolated".

Perubahan nama kelas

Beberapa kelas utama mengubah nama antara versi 1.x dan versi 4.x. Perubahan ini adalah hasil dari perubahan API .NET atau perbedaan antara proses dalam proses dan proses pekerja yang terisolasi. Tabel berikut menunjukkan kelas .NET kunci yang digunakan oleh Functions yang dapat berubah saat bermigrasi:

Versi 1.x .NET 8
FunctionName (atribut) Function (atribut)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (menggunakan integrasi ASP.NET Core)
HttpResponseMessage HttpResponseData, IActionResult (menggunakan integrasi ASP.NET Core)

Mungkin juga ada perbedaan nama kelas dalam pengikatan. Untuk informasi selengkapnya, lihat artikel referensi untuk pengikatan tertentu.

Perubahan kode lainnya

Bagian ini menyoroti perubahan kode lain untuk dipertimbangkan saat Anda bekerja melalui migrasi. Perubahan ini tidak diperlukan oleh semua aplikasi, tetapi Anda harus mengevaluasi apakah ada yang relevan dengan skenario Anda. Pastikan untuk memeriksa Perubahan perilaku setelah versi 1.x untuk perubahan tambahan yang mungkin perlu Anda lakukan pada proyek Anda.

Serialisasi JSON

Secara default, model pekerja terisolasi menggunakan System.Text.Json untuk serialisasi JSON. Untuk menyesuaikan opsi serializer atau beralih ke JSON.NET (Newtonsoft.Json), lihat instruksi ini.

Tingkat log dan pemfilteran Application Insights

Log dapat dikirim ke Application Insights dari runtime host Functions dan kode dalam proyek Anda. memungkinkan host.json Anda mengonfigurasi aturan untuk pengelogan host, tetapi untuk mengontrol log yang berasal dari kode Anda, Anda harus mengonfigurasi aturan pemfilteran sebagai bagian dari .Program.cs Lihat Mengelola tingkat log dalam model pekerja yang terisolasi untuk detail tentang cara memfilter log ini.

Templat pemicu HTTP

Sebagian besar perubahan kode antara versi 1.x dan versi 4.x dapat dilihat dalam fungsi yang dipicu HTTP. Templat pemicu HTTP untuk versi 1.x terlihat seperti contoh berikut:

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

Di versi 4.x, templat pemicu HTTP terlihat seperti contoh berikut:

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"]}!");
        }
    }
}

Untuk memperbarui proyek Anda ke Azure Functions 4.x:

  1. Perbarui penginstalan lokal Alat Utama Azure Functions ke versi 4.x.

  2. Pindahkan ke salah satu versi Node.js yang didukung pada versi 4.x.

  3. Tambahkan elemen version dan extensionBundle ke host.json, sehingga terlihat seperti contoh berikut:

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

    Elemen extensionBundle diperlukan karena setelah versi 1.x, pengikatan dipertahankan sebagai paket eksternal. Untuk informasi selengkapnya, lihat Bundel ekstensi.

  4. Perbarui file local.settings.json Anda sehingga memiliki setidaknya elemen berikut:

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

    Pengaturannya AzureWebJobsStorage dapat berupa emulator penyimpanan Azurite atau akun penyimpanan Azure yang sebenarnya. Untuk informasi selengkapnya, lihat Emulator penyimpanan lokal.

Memperbarui aplikasi fungsi Anda di Azure

Anda perlu memperbarui runtime host aplikasi fungsi di Azure ke versi 4.x sebelum menerbitkan proyek yang dimigrasikan. Versi runtime yang digunakan oleh host Functions dikontrol oleh FUNCTIONS_EXTENSION_VERSION pengaturan aplikasi, tetapi dalam beberapa kasus pengaturan lain juga harus diperbarui. Perubahan kode dan perubahan pada pengaturan aplikasi mengharuskan aplikasi fungsi Anda dimulai ulang.

Cara term mudah adalah memperbarui tanpa slot lalu menerbitkan ulang proyek aplikasi Anda. Anda juga dapat meminimalkan waktu henti di aplikasi dan menyederhanakan pemutaran kembali dengan memperbarui menggunakan slot.

Memperbarui tanpa slot

Cara paling sederhana untuk memperbarui ke v4.x adalah dengan mengatur FUNCTIONS_EXTENSION_VERSION pengaturan aplikasi ke ~4 pada aplikasi fungsi Anda di Azure. Anda harus mengikuti prosedur yang berbeda pada situs dengan slot.

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

Anda juga harus mengatur pengaturan lain, yang berbeda antara Windows dan Linux.

Saat berjalan di Windows, Anda juga perlu mengaktifkan .NET 6.0, yang diperlukan oleh runtime versi 4.x.

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

.NET 6 diperlukan untuk aplikasi fungsi dalam bahasa apa pun yang berjalan di Windows.

Dalam contoh ini, ganti <APP_NAME> dengan nama aplikasi fungsi Anda dan <RESOURCE_GROUP_NAME> dengan nama grup sumber daya.

Sekarang Anda dapat menerbitkan ulang proyek aplikasi yang telah dimigrasikan untuk berjalan pada versi 4.x.

Memperbarui menggunakan slot

Menggunakan slot penyebaran adalah cara yang baik untuk memperbarui aplikasi fungsi Anda ke runtime v4.x dari versi sebelumnya. Dengan menggunakan slot staging, Anda dapat menjalankan aplikasi pada versi runtime baru di slot staging dan beralih ke produksi setelah verifikasi. Slot juga menyediakan cara untuk meminimalkan waktu henti selama pembaruan. Jika Anda perlu meminimalkan waktu henti, ikuti langkah-langkah dalam Pembaruan waktu henti minimum.

Setelah memverifikasi aplikasi di slot yang diperbarui, Anda dapat menukar aplikasi dan pengaturan versi baru ke dalam produksi. Pertukaran ini memerlukan pengaturan WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 di slot produksi. Cara Anda menambahkan pengaturan ini memengaruhi jumlah waktu henti yang diperlukan untuk pembaruan.

Pembaruan standar

Jika aplikasi fungsi slot Anda dapat menangani waktu henti saat memulai ulang penuh, Anda dapat memperbarui pengaturan WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS langsung di slot produksi. Karena mengubah pengaturan ini secara langsung di slot produksi menyebabkan mulai ulang yang memengaruhi ketersediaan, pertimbangkan untuk melakukan perubahan ini saat lalu lintas berkurang. Anda kemudian dapat bertukar dalam versi yang diperbarui dari slot penahapan.

Cmdlet PowerShell Update-AzFunctionAppSetting saat ini tidak mendukung slot. Anda harus menggunakan Azure CLI atau portal Microsoft Azure.

  1. Gunakan perintah berikut untuk mengatur WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 di slot produksi:

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

    Dalam contoh ini, ganti <APP_NAME> dengan nama aplikasi fungsi Anda dan <RESOURCE_GROUP_NAME> dengan nama grup sumber daya. Perintah ini menyebabkan aplikasi yang berjalan di slot produksi dimulai ulang.

  2. Gunakan perintah berikut untuk juga mengatur WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS di slot staging:

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

  3. Gunakan perintah berikut untuk mengubah FUNCTIONS_EXTENSION_VERSION dan memperbarui slot penahapan ke versi runtime baru:

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

  4. Versi 4.x dari runtime Functions memerlukan .NET 6 di Windows. Di Linux, aplikasi .NET juga harus diperbarui ke .NET 6. Gunakan perintah berikut sehingga runtime dapat berjalan pada .NET 6:

    Saat berjalan di Windows, Anda juga perlu mengaktifkan .NET 6.0, yang diperlukan oleh runtime versi 4.x.

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

    .NET 6 diperlukan untuk aplikasi fungsi dalam bahasa apa pun yang berjalan di Windows.

    Dalam contoh ini, ganti <APP_NAME> dengan nama aplikasi fungsi Anda dan <RESOURCE_GROUP_NAME> dengan nama grup sumber daya.

  5. Jika proyek kode Anda memerlukan pembaruan apa pun untuk dijalankan pada versi 4.x, terapkan pembaruan tersebut ke slot staging sekarang.

  6. Konfirmasikan bahwa aplikasi fungsi Anda berjalan dengan benar di lingkungan penahapan yang diperbarui sebelum bertukar.

  7. Gunakan perintah berikut untuk menukar slot penahapan yang diperbarui ke produksi:

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

Pembaruan waktu henti minimum

Untuk meminimalkan waktu henti di aplikasi produksi, Anda dapat menukar pengaturan WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS dari slot staging ke produksi. Setelah itu, Anda dapat bertukar dalam versi yang diperbarui dari slot penahapan yang sudah ada sebelumnya.

  1. Gunakan perintah berikut untuk mengatur WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 di slot staging:

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

  2. Gunakan perintah berikut untuk menukar slot dengan pengaturan baru ke dalam produksi, dan pada saat yang sama memulihkan pengaturan versi di slot staging.

    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>

    Anda mungkin melihat kesalahan dari slot staging selama waktu antara versi pertukaran dan runtime yang dipulihkan saat staging. Kesalahan ini dapat terjadi karena hanya memiliki WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 pentahapan selama pertukaran FUNCTIONS_EXTENSION_VERSION menghapus pengaturan dalam penahapan. Tanpa pengaturan versi, slot Anda dalam keadaan buruk. Memperbarui versi di slot staging tepat setelah pertukaran akan mengembalikan slot ke kondisi yang baik, dan Anda memanggil kembalikan perubahan Anda jika diperlukan. Namun, setiap rollback pertukaran juga mengharuskan Anda untuk langsung menghapus WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dari produksi sebelum pertukaran kembali untuk mencegah kesalahan yang sama dalam produksi yang terlihat pada staging. Perubahan dalam pengaturan produksi ini kemudian akan menyebabkan mulai ulang.

  3. Gunakan perintah berikut untuk mengatur lagi WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 di slot staging:

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

    Pada titik ini, kedua slot memiliki WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 yang ditetapkan.

  4. Gunakan perintah berikut untuk mengubah FUNCTIONS_EXTENSION_VERSION dan memperbarui slot penahapan ke versi runtime baru:

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

  5. Versi 4.x dari runtime Functions memerlukan .NET 6 di Windows. Di Linux, aplikasi .NET juga harus diperbarui ke .NET 6. Gunakan perintah berikut sehingga runtime dapat berjalan pada .NET 6:

    Saat berjalan di Windows, Anda juga perlu mengaktifkan .NET 6.0, yang diperlukan oleh runtime versi 4.x.

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

    .NET 6 diperlukan untuk aplikasi fungsi dalam bahasa apa pun yang berjalan di Windows.

    Dalam contoh ini, ganti <APP_NAME> dengan nama aplikasi fungsi Anda dan <RESOURCE_GROUP_NAME> dengan nama grup sumber daya.

  6. Jika proyek kode Anda memerlukan pembaruan apa pun untuk dijalankan pada versi 4.x, terapkan pembaruan tersebut ke slot staging sekarang.

  7. Konfirmasikan bahwa aplikasi fungsi Anda berjalan dengan benar di lingkungan penahapan yang diperbarui sebelum bertukar.

  8. Gunakan perintah berikut untuk menukar slot penahapan yang diperbarui dan telah diperbarui ke produksi:

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

Perubahan perilaku setelah versi 1.x

Bagian ini merinci perubahan yang dilakukan setelah versi 1.x dalam perilaku pemicu dan pengikatan serta dalam fitur dan perilaku Fungsi inti.

Perubahan pemicu dan pengikatan

Dimulai dengan versi 2.x, Anda harus memasang ekstensi untuk pemicu dan pengikatan tertentu yang digunakan oleh fungsi di aplikasi Anda. Satu-satunya pengecualian adalah untuk pemicu HTTP dan timer yang tidak memerlukan ekstensi. Untuk informasi selengkapnya, lihat Mendaftar dan memasang ekstensi pengikatan.

Terdapat juga beberapa perubahan dalam function.json atau atribut fungsi antar versi. Misalnya, properti Pusat Aktivitas path adalah sekarang eventHubName. Lihat tabel pengikatan yang sudah ada untuk tautan ke dokumentasi setiap pengikatan.

Perubahan fitur dan fungsionalitas

Beberapa fitur dihapus, diperbarui, atau diganti setelah versi 1.x. Bagian ini merinci perubahan yang Anda lihat di versi yang lebih baru setelah menggunakan versi 1.x.

Pada versi 2.x, perubahan berikut dibuat:

  • Kunci untuk memanggil titik akhir HTTP selalu disimpan dengan enkripsi di dalam Azure Blob Storage. Pada versi 1.x, kunci disimpan di dalam Azure Files secara default. Saat Anda memigrasikan aplikasi dari versi 1.x ke versi 2.x, rahasia yang ada di Azure Files akan diatur ulang.

  • Runtime versi 2.x tidak menyertakan dukungan bawaan untuk penyedia webhook. Perubahan ini dilakukan untuk meningkatkan performa. Anda masih dapat menggunakan pemicu HTTP sebagai titik akhir untuk webhook.

  • Untuk meningkatkan pemantauan, dasbor WebJobs di portal, yang menggunakan pengaturan AzureWebJobsDashboard diganti dengan Azure Application Insights, yang menggunakan pengaturan APPINSIGHTS_INSTRUMENTATIONKEY. Untuk mengetahui informasi selengkapnya, lihat Memantau Azure Functions.

  • Semua fungsi dalam aplikasi fungsi harus berbagi bahasa pemrogram yang sama. Saat membuat aplikasi fungsi, Anda harus memilih tumpukan runtime untuk aplikasi. Tumpukan runtime ditentukan oleh nilai FUNCTIONS_WORKER_RUNTIME dalam pengaturan aplikasi. Persyaratan ini ditambahkan untuk meningkatkan jejak dan waktu pengaktifan. Saat mengembangkan secara lokal, Anda juga harus menyertakan pengaturan ini dalam file local.settings.json.

  • Batas waktu default untuk fungsi dalam paket App Service diubah menjadi 30 menit. Anda dapat secara manual mengubah ulang batas waktu ke unlimited dengan menggunakan pengaturan function Timeout pada host.json.

  • Pembatasan konkurensi HTTP diimplementasikan secara default untuk fungsi paket Konsumsi, dengan default 100 permintaan bersamaan per instans. Anda dapat mengubah perilaku ini di pengaturan maxConcurrentRequests di file host.json.

  • Karena keterbatasan .NET Core, dukungan untuk fungsi skrip F# (.fsx file) telah dihapus. Fungsi F# yang dikompilasi (.fs) masih didukung.

  • Format URL dari webhooks pemicu Event Grid telah diubah untuk mengikuti pola ini: https://{app}/runtime/webhooks/{triggerName}.

  • Nama beberapa metrik kustom yang telah ditentukan sebelumnya diubah setelah versi 1.x. Duration diganti dengan MaxDurationMs, MinDurationMs, dan AvgDurationMs. Success Rate juga diganti namanya menjadi Success Rate.

Pertimbangan untuk Azure Stack Hub

App Service di Azure Stack Hub tidak mendukung Azure Functions versi 4.x. Saat merencanakan migrasi dari versi 1.x di Azure Stack Hub, Anda dapat memilih salah satu opsi berikut:

  • Migrasikan ke versi 4.x yang dihosting di Azure Functions cloud publik menggunakan instruksi dalam artikel ini. Alih-alih meningkatkan aplikasi yang ada, Anda akan membuat aplikasi baru menggunakan versi 4.x lalu menyebarkan proyek yang dimodifikasi ke aplikasi tersebut.
  • Beralih ke WebJobs yang dihosting pada paket App Service di Azure Stack Hub.

Langkah berikutnya

Pelajari selengkapnya tentang versi Functions