Bagikan melalui

Panduan untuk menjalankan C# Azure Functions dalam model pekerja terisolasi

Artikel ini adalah pengantar untuk bekerja dengan Azure Functions di .NET, menggunakan model pekerja yang terisolasi. Model ini memungkinkan proyek Anda untuk menargetkan versi .NET secara independen dari komponen runtime lainnya. Untuk informasi tentang versi .NET tertentu yang didukung, lihat versi yang didukung.

Gunakan tautan berikut untuk segera memulai membangun fungsi model pekerja terisolasi .NET.

Memulai Konsep Sampel

Untuk mempelajari tentang menyebarkan proyek model pekerja terisolasi ke Azure, lihat Menyebarkan ke Azure Functions.

Manfaat model pekerja yang terisolasi

Ada dua mode di mana Anda dapat menjalankan fungsi pustaka kelas .NET Anda: baik dalam proses yang sama dengan Functions-host runtime (dalam proses) atau dalam proses pekerja yang terisolasi. Saat fungsi .NET Anda berjalan dalam proses pekerja yang terisolasi, Anda dapat memanfaatkan manfaat berikut:

  • Lebih sedikit konflik: Karena fungsi Anda berjalan dalam proses terpisah, rakitan yang digunakan di aplikasi Anda tidak bertentangan dengan versi rakitan yang sama yang berbeda yang digunakan oleh proses host.
  • Kontrol penuh proses: Anda mengontrol pemulaan aplikasi, yang berarti Anda dapat mengelola konfigurasi yang digunakan dan middleware yang dijalankan.
  • Injeksi dependensi standar: Karena Anda memiliki kontrol penuh atas proses, Anda dapat menggunakan perilaku .NET saat ini untuk injeksi dependensi dan memasukkan middleware ke dalam aplikasi fungsi Anda.
  • Fleksibilitas versi .NET: Berjalan di luar proses host berarti bahwa fungsi Anda dapat berjalan pada versi .NET yang tidak didukung secara asli oleh runtime Functions, termasuk .NET Framework.

Jika Anda memiliki aplikasi fungsi C# yang berjalan dalam proses, Anda perlu memigrasikan aplikasi untuk memanfaatkan manfaat ini. Untuk informasi selengkapnya, lihat Memigrasikan aplikasi .NET dari model dalam proses ke model pekerja yang terisolasi.

Untuk perbandingan yang lebih komprehensif antara kedua mode, lihat Perbedaan antara proses in-process dan proses pekerja isolate pada .NET Azure Functions.

Versi yang didukung

Versi runtime Functions mendukung versi .NET tertentu. Untuk mempelajari selengkapnya tentang versi Functions, lihat Gambaran umum versi runtime Azure Functions. Dukungan versi juga bergantung pada apakah fungsi Anda berjalan dalam proses atau proses pekerja terisolasi.

Catatan

Untuk mempelajari cara mengubah versi runtime Functions yang digunakan oleh aplikasi fungsi Anda, lihat menampilkan dan memperbarui versi runtime saat ini.

Tabel berikut menunjukkan tingkat tertinggi .NET atau .NET Framework yang dapat digunakan dengan versi Functions tertentu.

Versi runtime Functions Model pekerja terisolasi Model dalam proses4
Fungsi 4.x1 .NET 9.0
.NET 8.0
.NET Framework 4.82		 .NET 8.0
Fungsi 1.x3 N/a .NET Framework 4.8

1 .NET 6 sebelumnya didukung pada kedua model tetapi mencapai akhir dukungan resmi pada 12 November 2024. .NET 7 sebelumnya didukung pada model pekerja yang terisolasi namun mencapai akhir dukungan resmi pada 14 Mei 2024.

2 Proses build juga memerlukan .NET SDK.

3 Dukungan berakhir untuk runtime Azure Functions versi 1.x pada 14 September 2026. Untuk informasi selengkapnya, lihat pengumuman dukungan ini. Untuk dukungan penuh berkelanjutan, Anda harus memigrasikan aplikasi Anda ke versi 4.x.

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

Untuk berita terbaru tentang rilis Azure Functions, termasuk penghapusan versi minor lama tertentu, lihat pengumuman Azure App Service.

Struktur proyek

Proyek .NET untuk Azure Functions menggunakan model pekerja terisolasi pada dasarnya adalah proyek aplikasi konsol .NET yang menargetkan runtime .NET yang didukung. Berikut adalah file dasar yang diperlukan dalam proyek terisolasi .NET apa pun:

  • File proyek C# (.csproj) yang menentukan proyek dan dependensi.
  • File Program.cs itulah titik masuk untuk aplikasi.
  • File kode apa pun mendefinisikan fungsi Anda.
  • host.json file yang menentukan konfigurasi yang dibagikan oleh fungsi dalam proyek Anda.
  • local.settings.json file yang menentukan variabel lingkungan yang digunakan oleh proyek Anda saat dijalankan secara lokal di komputer Anda.

Untuk contoh lengkapnya, lihat proyek sampel .NET 8 dan proyek sampel .NET Framework 4.8.

Referensi Paket

Proyek .NET untuk Azure Functions menggunakan model pekerja terisolasi menggunakan serangkaian paket unik, untuk fungsionalitas inti dan ekstensi pengikatan.

Paket inti

Paket berikut diperlukan untuk menjalankan fungsi .NET Anda dalam proses pekerja yang terisolasi:

Versi 2.x

Versi 2.x dari paket inti mengubah kerangka kerja yang didukung dan membawa dukungan untuk API .NET baru dari versi yang lebih baru ini. Saat Anda menargetkan .NET 9 atau yang lebih baru, aplikasi Anda perlu mereferensikan versi 2.0.0 atau yang lebih baru dari kedua paket.

Saat memperbarui ke versi 2.x, perhatikan perubahan berikut:

  • Dimulai dengan Microsoft.Azure.Functions.Worker.Sdk versi 2.0.0:
    • SDK menyertakan konfigurasi default untuk pembangunan kontainer SDK.
    • SDK menyertakan dukungan untuk dotnet run ketika Azure Functions Core Tools diinstal. Di Windows, Core Tools perlu diinstal melalui mekanisme selain NPM.
  • Dimulai dengan Microsoft.Azure.Functions.Worker versi 2.0.0:
    • Versi ini menambahkan dukungan untuk IHostApplicationBuilder. Beberapa contoh dalam panduan ini mencakup tab untuk menampilkan alternatif menggunakan IHostApplicationBuilder. Contoh-contoh ini memerlukan versi 2.x.
    • Validasi cakupan penyedia layanan disertakan secara default jika dijalankan di lingkungan pengembangan. Perilaku ini cocok dengan ASP.NET Core.
    • Opsi EnableUserCodeException diaktifkan secara default. Properti sekarang ditandai sebagai usang.
    • Opsi IncludeEmptyEntriesInMessagePayload diaktifkan secara default. Ketika opsi ini diaktifkan, picu payload yang mewakili koleksi selalu menyertakan entri kosong. Misalnya, jika pesan dikirim tanpa isi, entri kosong akan tetap ada untuk string[] data pemicu. Penyertaan entri kosong memfasilitasi referensi silang dengan array metadata yang juga dapat direferensikan oleh fungsi. Anda dapat menonaktifkan perilaku ini dengan mengatur IncludeEmptyEntriesInMessagePayload ke falseWorkerOptions dalam konfigurasi layanan.
    • Kelas ILoggerExtensions diganti namanya menjadi FunctionsLoggerExtensions. Penggantian nama mencegah kesalahan panggilan ambigu saat menggunakan LogMetric() pada ILogger instans.
    • Untuk aplikasi yang menggunakan HttpResponseData, WriteAsJsonAsync() metode tidak lagi akan mengatur kode status ke 200 OK. Dalam 1.x, ini mengesampingkan kode kesalahan lain yang telah ditetapkan.
  • Versi 2.x menghilangkan dukungan .NET 5 TFM.

Paket ekstensi

Karena fungsi proses pekerja terisolasi .NET menggunakan jenis pengikatan yang berbeda, fungsi tersebut memerlukan serangkaian paket ekstensi pengikatan yang unik.

Anda menemukan paket ekstensi ini di bawah Microsoft.Azure.Functions.Worker.Extensions.

Pemula dan Konfigurasi

Saat Anda menggunakan model pekerja yang terisolasi, Anda memiliki akses ke pemulaian aplikasi fungsi Anda, yang biasanya ada di Program.cs. Anda bertanggung jawab untuk membuat dan memulai instans host Anda sendiri. Dengan demikian, Anda juga memiliki akses langsung ke alur konfigurasi untuk aplikasi Anda. Dengan proses pekerja terisolasi .NET Functions, Anda dapat jauh lebih mudah menambahkan konfigurasi, menyuntikkan dependensi, dan menjalankan middleware Anda sendiri.

Kode berikut menunjukkan contoh alur HostBuilder:

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(s =>
    {
        s.AddApplicationInsightsTelemetryWorkerService();
        s.ConfigureFunctionsApplicationInsights();
        s.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
        s.Configure<LoggerFilterOptions>(options =>
        {
            // The Application Insights SDK adds a default logging filter that instructs ILogger to capture only Warning and more severe logs. Application Insights requires an explicit override.
            // Log levels can also be configured using appsettings.json. For more information, see https://learn.microsoft.com/en-us/azure/azure-monitor/app/worker-service#ilogger-logs
            LoggerFilterRule? toRemove = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");

            if (toRemove is not null)
            {
                options.Rules.Remove(toRemove);
            }
        });
    })
    .Build();

Kode ini membutuhkan using Microsoft.Extensions.DependencyInjection;.

Sebelum memanggil Build() di IHostBuilder, Anda harus:

  • Panggil ConfigureFunctionsWebApplication() jika menggunakan integrasi ASP.NET Core atau ConfigureFunctionsWorkerDefaults() jika tidak. Lihat pemicu HTTP untuk detail tentang opsi ini.
    Jika Anda menulis aplikasi menggunakan F#, beberapa ekstensi pemicu dan pengikatan memerlukan konfigurasi tambahan. Lihat dokumentasi penyiapan untuk ekstensi Blob, ekstensi Tabel, dan ekstensi Cosmos DB saat Anda berencana menggunakan ekstensi ini di aplikasi F#.
  • Konfigurasikan layanan atau konfigurasi aplikasi apa pun yang diperlukan proyek Anda. Lihat Konfigurasi untuk detailnya.
    Jika Anda berencana menggunakan Application Insights, Anda perlu memanggil AddApplicationInsightsTelemetryWorkerService() dan ConfigureFunctionsApplicationInsights() dalam ConfigureServices() delegate. Lihat Application Insights untuk detailnya.

Jika proyek Anda menargetkan .NET Framework 4.8, Anda juga perlu menambahkan FunctionsDebugger.Enable(); sebelum membuat HostBuilder. Ini harus menjadi baris pertama dari metode Main() Anda. Untuk informasi selengkapnya, lihat Debugging saat menargetkan .NET Framework.

HostBuilder digunakan untuk membangun dan mengembalikan instans yang dibuat dan diinisialisasi sepenuhnya, yang kemudian Anda jalankan secara asinkron untuk memulai aplikasi fungsi Anda.

await host.RunAsync();

Konfigurasi

Jenis penyusun yang Anda gunakan menentukan bagaimana Anda dapat mengonfigurasi aplikasi.

Metode ConfigureFunctionsWorkerDefaults digunakan untuk menambahkan pengaturan yang diperlukan agar aplikasi fungsi berjalan. Metode ini mencakup fungsionalitas berikut:

  • Perangkat konverter bawaan.
  • Atur JsonSerializerOptions bawaan untuk mengabaikan pembedaan huruf besar/kecil pada nama properti.
  • Integrasikan dengan pencatatan Azure Functions.
  • Middleware dan fitur pengikatan output.
  • Perangkat lunak perantara eksekusi fungsi.
  • Dukungan bawaan gRPC.
.ConfigureFunctionsWorkerDefaults()

Memiliki akses ke alur penyusun host berarti Anda juga dapat mengatur konfigurasi aplikasi apa pun selama inisialisasi. Anda dapat memanggil metode ConfigureAppConfiguration di HostBuilder satu atau beberapa kali untuk menambahkan sumber konfigurasi apa pun yang diperlukan oleh kode Anda. Untuk mempelajari selengkapnya tentang konfigurasi aplikasi, lihat Konfigurasi di ASP.NET Core.

Konfigurasi ini hanya berlaku untuk kode fungsi yang Anda tulis, dan tidak secara langsung mempengaruhi konfigurasi host atau pemicu dan pengikatan pada host Functions. Untuk membuat perubahan pada host fungsi atau memicu dan mengikat konfigurasi, Anda masih perlu menggunakan file host.json.

Catatan

Sumber konfigurasi kustom tidak dapat digunakan untuk konfigurasi pemicu dan pengikatan. Konfigurasi pemicu dan pengikatan harus tersedia untuk platform Functions, dan bukan hanya kode aplikasi Anda. Anda dapat menyediakan konfigurasi ini melalui pengaturan aplikasi, referensi Key Vault, atau referensi App Configuration.

Penyuntikan ketergantungan

Model pekerja yang terisolasi menggunakan mekanisme .NET standar untuk menyuntikkan layanan.

Saat Anda menggunakan HostBuilder, panggil ConfigureServices pada pembangun host dan gunakan metode ekstensi pada IServiceCollection untuk menyuntikkan layanan tertentu. Contoh berikut memasukkan dependensi layanan singleton:

.ConfigureServices(services =>
{
    services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
})

Kode ini membutuhkan using Microsoft.Extensions.DependencyInjection;. Untuk mempelajari selengkapnya, lihat Injeksi dependensi di ASP.NET Core.

Mendaftarkan klien Azure

Injeksi dependensi dapat digunakan untuk berinteraksi dengan layanan Azure lainnya. Anda dapat menyuntikkan klien dari Azure SDK untuk .NET menggunakan paket Microsoft.Extensions.Azure . Setelah menginstal paket, daftarkan klien dengan memanggil AddAzureClients() koleksi layanan di Program.cs. Contoh berikut mengonfigurasi klien yang diberi nama untuk Azure Blobs:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Azure;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices((hostContext, services) =>
    {
        services.AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(hostContext.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });
    })
    .Build();

host.Run();

Contoh berikut menunjukkan bagaimana kita dapat menggunakan pendaftaran ini dan jenis SDK untuk menyalin konten blob sebagai aliran dari satu kontainer ke kontainer lainnya menggunakan klien yang disuntikkan:

using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Logging;

namespace MyFunctionApp
{
    public class BlobCopier
    {
        private readonly ILogger<BlobCopier> _logger;
        private readonly BlobContainerClient _copyContainerClient;

        public BlobCopier(ILogger<BlobCopier> logger, IAzureClientFactory<BlobServiceClient> blobClientFactory)
        {
            _logger = logger;
            _copyContainerClient = blobClientFactory.CreateClient("copierOutputBlob").GetBlobContainerClient("samples-workitems-copy");
            _copyContainerClient.CreateIfNotExists();
        }

        [Function("BlobCopier")]
        public async Task Run([BlobTrigger("samples-workitems/{name}", Connection = "MyStorageConnection")] Stream myBlob, string name)
        {
            await _copyContainerClient.UploadBlobAsync(name, myBlob);
            _logger.LogInformation($"Blob {name} copied!");
        }

    }
}

ILogger<T> pada contoh ini juga diperoleh melalui sebuah injeksi dependensi, sehingga terdaftar secara otomatis. Untuk mempelajari selengkapnya tentang opsi konfigurasi untuk pengelogan, lihat Pengelogan.

Petunjuk / Saran

Contoh menggunakan string literal untuk nama klien dalam Program.cs dan fungsi. Pertimbangkan untuk menggunakan string konstanta bersama yang ditentukan pada kelas fungsi. Misalnya, Anda dapat menambahkan public const string CopyStorageClientName = nameof(_copyContainerClient); lalu mereferensikan BlobCopier.CopyStorageClientName di kedua lokasi. Anda juga dapat menentukan nama bagian konfigurasi dengan fungsi daripada di Program.cs.

Middleware

Model pekerja yang terisolasi juga mendukung pendaftaran middleware, sekali lagi dengan menggunakan model yang mirip dengan apa yang ada di ASP.NET. Model ini memberi Anda kemampuan untuk memasukkan logika ke dalam alur pemanggilan serta sebelum dan sesudah fungsi dijalankan.

Metode ekstensi ConfigureFunctionsWorkerDefaults memiliki kelebihan beban yang memungkinkan Anda mendaftarkan middleware Anda sendiri, seperti yang dapat Anda lihat dalam contoh berikut.

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(workerApplication =>
    {
        // Register our custom middlewares with the worker

        workerApplication.UseMiddleware<ExceptionHandlingMiddleware>();

        workerApplication.UseMiddleware<MyCustomMiddleware>();

        workerApplication.UseWhen<StampHttpHeaderMiddleware>((context) =>
        {
            // We want to use this middleware only for http trigger invocations.
            return context.FunctionDefinition.InputBindings.Values
                          .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
        });
    })
    .Build();

Metode UseWhen ekstensi dapat digunakan untuk mendaftarkan middleware yang dieksekusi secara kondisional. Anda harus mengirimkan suatu predikat yang mengembalikan nilai boolean ke metode ini, dan middleware berpartisipasi dalam alur pemrosesan panggilan ketika nilai pengembalian predikat adalah true.

Metode ekstensi berikut pada FunctionContext mempermudah bekerja dengan middleware dalam model yang terisolasi.

Metode Deskripsi
GetHttpRequestDataAsync Mengambil instans HttpRequestData ketika dipanggil oleh pemicu HTTP. Metode ini mengembalikan instans ValueTask<HttpRequestData?>, yang berguna ketika Anda ingin membaca data pesan, seperti header permintaan dan cookie.
GetHttpResponseData Mengambil instans HttpResponseData ketika dipanggil oleh pemicu HTTP.
GetInvocationResult Memperoleh instans InvocationResult, yang mewakili hasil eksekusi fungsi saat ini. Gunakan properti Value untuk mendapatkan atau mengatur nilai sesuai kebutuhan.
GetOutputBindings Mengambil entri pengikatan output untuk pelaksanaan fungsi saat ini. Setiap entri dalam hasil metode ini berjenis OutputBindingData. Anda dapat menggunakan properti Value untuk mendapatkan atau mengatur nilai sesuai kebutuhan.
BindInputAsync Mengikat item pengikatan input untuk instans BindingMetadata yang diminta. Misalnya, Anda dapat menggunakan metode ini ketika Anda memiliki fungsi dengan BlobInput pengikatan input yang perlu digunakan oleh middleware Anda.

Ini adalah contoh implementasi middleware yang membaca instans HttpRequestData dan memperbarui instans HttpResponseData selama eksekusi fungsi.

internal sealed class StampHttpHeaderMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        var requestData = await context.GetHttpRequestDataAsync();

        string correlationId;
        if (requestData!.Headers.TryGetValues("x-correlationId", out var values))
        {
            correlationId = values.First();
        }
        else
        {
            correlationId = Guid.NewGuid().ToString();
        }

        await next(context);

        context.GetHttpResponseData()?.Headers.Add("x-correlationId", correlationId);
    }
}

Middleware ini memeriksa keberadaan header permintaan spesifik (x-correlationId), dan saat ada, menggunakan nilai header tersebut untuk menandai header respons. Jika tidak, ini menghasilkan nilai GUID baru dan menggunakannya untuk menandai header respons. Untuk contoh yang lebih lengkap tentang menggunakan middleware kustom di aplikasi fungsi Anda, lihat sampel referensi middleware kustom.

Menyesuaikan serialisasi JSON

Model pekerja yang terisolasi menggunakan System.Text.Json secara default. Anda dapat menyesuaikan perilaku serializer dengan mengonfigurasi layanan sebagai bagian dari file Anda Program.cs . Bagian ini mencakup serialisasi tujuan umum dan tidak memengaruhi serialisasi JSON pemicu HTTP dengan integrasi ASP.NET Core, yang harus dikonfigurasi secara terpisah.

Contoh berikut menunjukkan ini menggunakan ConfigureFunctionsWebApplication, tetapi juga akan berfungsi untuk ConfigureFunctionsWorkerDefaults:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
        {
            jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
            jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
            jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

            // override the default value
            jsonSerializerOptions.PropertyNameCaseInsensitive = false;
        });
    })
    .Build();

host.Run();

Anda mungkin ingin menggunakan JSON.NET (Newtonsoft.Json) untuk serialisasi. Untuk melakukan ini, Anda akan menginstal Microsoft.Azure.Core.NewtonsoftJson paket. Kemudian, dalam pendaftaran layanan, Anda akan menetapkan Serializer ulang properti pada WorkerOptions konfigurasi. Contoh berikut menunjukkan ini menggunakan ConfigureFunctionsWebApplication, tetapi juga akan berfungsi untuk ConfigureFunctionsWorkerDefaults:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<WorkerOptions>(workerOptions =>
        {
            var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
            settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
            settings.NullValueHandling = NullValueHandling.Ignore;

            workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
        });
    })
    .Build();

host.Run();

Metode yang dikenali sebagai fungsi

Fungsi metode adalah metode publik dari kelas publik dengan atribut Function yang diterapkan pada metode dan atribut pemicu yang diterapkan pada parameter input, seperti yang ditunjukkan dalam contoh berikut:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Atribut pemicu menentukan jenis pemicu dan mengikat data input ke parameter metode. Fungsi contoh sebelumnya dipicu oleh pesan antrean dan pesan antrean diteruskan ke metode di parameter myQueueItem.

Atribut Function menandai metode sebagai titik masuk fungsi. Nama dalam proyek harus unik, dimulai dengan huruf dan hanya berisi huruf, angka, _, dan -, hingga 127 karakter. Templat proyek sering membuat metode bernama Run, tetapi nama metode dapat menjadi nama metode C# yang valid. Metode harus menjadi anggota publik dari kelas publik. Ini umumnya harus menjadi metode instansi sehingga layanan dapat diteruskan melalui dependency injection.

Parameter fungsi

Berikut adalah beberapa parameter yang dapat Anda sertakan sebagai bagian dari tanda tangan metode fungsi:

  • Pengikatan, yang ditandai sebagai dengan menandai parameter sebagai atribut. Fungsi harus berisi tepat satu parameter pemicu.
  • Sebuah objek konteks eksekusi yang menyediakan informasi tentang pemanggilan saat ini.
  • Token pembatalan, digunakan untuk penghentian yang mulus.

Konteks eksekusi

.NET terisolasi meneruskan objek FunctionContext ke metode fungsi Anda. Objek ini memungkinkan Anda mendapatkan objek instance ILogger untuk menulis ke log dengan memanggil metode GetLogger dan menggunakan categoryName string. Anda dapat menggunakan konteks ini untuk mendapatkan ILogger tanpa harus menggunakan injeksi dependensi. Untuk mempelajari selengkapnya, lihat Pencatatan.

Token pembatalan

Fungsi dapat menerima parameter CancellationToken yang memungkinkan sistem operasi untuk memberi tahu kode Anda ketika fungsi akan dihentikan. Anda dapat menggunakan pemberitahuan ini untuk memastikan fungsi tidak berakhir secara tiba-tiba dengan meninggalkan data dalam status tidak konsisten.

Token pembatalan didukung dalam fungsi .NET ketika dijalankan dalam proses pekerja terisolasi. Contoh berikut menimbulkan pengecualian saat permintaan pembatalan diterima:

[Function(nameof(ThrowOnCancellation))]
public async Task ThrowOnCancellation(
    [EventHubTrigger("sample-workitem-1", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(ThrowOnCancellation));

    foreach (var message in messages)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

Contoh berikut melakukan tindakan pembersihan saat permintaan pembatalan diterima:

[Function(nameof(HandleCancellationCleanup))]
public async Task HandleCancellationCleanup(
    [EventHubTrigger("sample-workitem-2", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(HandleCancellationCleanup));

    foreach (var message in messages)
    {
        if (cancellationToken.IsCancellationRequested)
        {
            _logger.LogInformation("A cancellation token was received, taking precautionary actions.");
            // Take precautions like noting how far along you are with processing the batch
            _logger.LogInformation("Precautionary activities complete.");
            break;
        }

        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

Skenario yang menyebabkan pembatalan

Token pembatalan diaktifkan ketika pemanggilan fungsi dibatalkan. Beberapa alasan dapat menyebabkan pembatalan, dan itu dapat bervariasi tergantung pada jenis pemicu yang digunakan. Beberapa alasan umum adalah:

  1. Klien terputus: klien yang memanggil fungsi Anda terputus. Ini kemungkinan besar untuk fungsi HttpTrigger.
  2. Menyalakan ulang Function App: jika Anda, atau platform, menyalakan ulang (atau menghentikan) Function App pada waktu yang sama ketika terjadi permintaan pemanggilan. Mulai ulang dapat terjadi karena pergerakan instans pekerja, pembaruan instans pekerja, atau penskalakan.
    • Pemanggilan dalam penerbangan selama peristiwa hidupkan ulang dapat dicoba kembali tergantung pada bagaimana pemicunya. Silakan merujuk ke dokumentasi coba ulang untuk informasi lebih lanjut.

Untuk model pekerja yang terisolasi, host kami akan mengirimkan pemanggilan ke pekerja meskipun token pembatalan telah dibatalkan sebelum host dapat mengirim permintaan pemanggilan ke pekerja.

Jika Anda tidak ingin pemanggilan yang telah dibatalkan sebelumnya dikirim ke pekerja, Anda dapat menambahkan properti SendCanceledInvocationsToWorker ke file host.json Anda untuk menonaktifkan perilaku ini. Contoh berikut menunjukkan host.json file yang menggunakan properti ini:

{
    "version": "2.0",
    "SendCanceledInvocationsToWorker": "false"
}

Penting

Mengatur SendCanceledInvocationsToWorker menjadi false dapat menyebabkan pengecualian FunctionInvocationCanceled dengan log berikut:

Cancellation has been requested. The invocation request with id '{invocationId}' is canceled and will not be sent to the worker

Ini terjadi ketika token pembatalan dibatalkan (sebagai akibat dari salah satu peristiwa yang dijelaskan di atas) sebelum host mengirimkan permintaan invokasi kepada pekerja. Pengecualian ini dapat diabaikan dengan aman dan akan diharapkan ketika SendCanceledInvocationsToWorker adalah false.

Pengikatan

Pengikatan ditentukan dengan menggunakan atribut pada metode, parameter, dan jenis pengembalian. Pengikatan dapat menyediakan data sebagai string, array, dan jenis yang dapat diserialisasikan, seperti objek kelas lama biasa (POCO). Untuk beberapa ekstensi pengikatan, Anda juga dapat mengikat ke jenis layanan spesifik yang ditentukan dalam SDK layanan.

Untuk pemicu HTTP, lihat bagian pemicu HTTP.

Untuk serangkaian sampel referensi lengkap menggunakan pemicu dan pengikatan dengan fungsi proses pekerja yang terisolasi, lihat sampel referensi ekstensi pengikatan.

Pengikatan input

Fungsi dapat memiliki pengikatan input nol atau lebih yang dapat meneruskan data ke fungsi. Seperti pemicu, pengikatan input ditentukan dengan menerapkan atribut pengikatan ke parameter input. Saat fungsi dijalankan, runtime mencoba untuk mendapatkan data yang ditentukan dalam pengikatan. Data yang diminta sering kali bergantung pada informasi yang diberikan oleh pemicu menggunakan parameter pengikatan.

Pengikatan output

Untuk menulis ke pengikatan output, Anda harus menerapkan atribut pengikatan output ke metode fungsi, yang mengatur cara menulis ke layanan yang terikat. Nilai yang dikembalikan oleh metode ditulis ke pengikatan output. Misalnya, contoh berikut menulis nilai string ke antrean pesan bernama output-queue dengan menggunakan pengikatan output:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Beberapa pengikatan output

Data yang ditulis ke pengikatan output selalu merupakan nilai yang dikembalikan dari fungsi. Jika Anda perlu menulis ke lebih dari satu pengikatan output, Anda harus membuat jenis pengembalian kustom. Jenis pengembalian ini harus memiliki atribut pengikatan output yang diterapkan ke satu atau beberapa properti kelas. Contoh berikut adalah fungsi yang dipicu HTTP menggunakan integrasi ASP.NET Core yang menulis ke respons HTTP dan pengikatan output antrean:

public class MultipleOutputBindings
{
    private readonly ILogger<MultipleOutputBindings> _logger;

    public MultipleOutputBindings(ILogger<MultipleOutputBindings> logger)
    {
        _logger = logger;
    }

    [Function("MultipleOutputBindings")]
    public MyOutputType Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        _logger.LogInformation("C# HTTP trigger function processed a request.");
        var myObject = new MyOutputType
        {
            Result = new OkObjectResult("C# HTTP trigger function processed a request."),
            MessageText = "some output"
        };
        return myObject;
    }

    public class MyOutputType
    {
        [HttpResult]
        public IActionResult Result { get; set; }

        [QueueOutput("myQueue")]
        public string MessageText { get; set; }
    }
}

Saat menggunakan jenis pengembalian kustom untuk beberapa pengikatan output dengan integrasi ASP.NET Core, Anda harus menambahkan [HttpResult] atribut ke properti yang memberikan hasilnya. Atribut HttpResult ini tersedia saat menggunakan SDK 1.17.3-preview2 atau yang lebih baru bersama dengan versi 3.2.0 atau yang lebih baru dari ekstensi HTTP dan versi 1.3.0 atau yang lebih baru dari ekstensi ASP.NET Core.

Jenis SDK

Untuk beberapa jenis pengikatan khusus layanan, data pengikatan dapat disediakan menggunakan jenis dari SDK layanan dan kerangka kerja. Ini memberikan lebih banyak kemampuan dibandingkan dengan apa yang dapat ditawarkan oleh string atau objek CLR (POCO) yang diserialisasikan. Untuk menggunakan jenis yang lebih baru, proyek Anda perlu diperbarui untuk menggunakan versi dependensi inti yang lebih baru.

Dependensi Persyaratan versi
Microsoft.Azure.Functions.Worker 1.18.0 atau yang lebih baru
Microsoft.Azure.Functions.Worker.Sdk 1.13.0 atau yang lebih baru

Saat menguji jenis SDK secara lokal di komputer, Anda juga perlu menggunakan Azure Functions Core Tools, versi 4.0.5000 atau yang lebih baru. Anda dapat memeriksa versi Anda saat ini menggunakan func version perintah .

Setiap ekstensi pemicu dan pengikatan juga memiliki persyaratan versi minimumnya sendiri, yang dijelaskan dalam artikel referensi ekstensi. Pengikatan khusus layanan berikut menyediakan jenis SDK:

Layanan Pemicu Pengikatan masukan Pengikatan output
Azure Blobs Tersedia Secara Umum Tersedia Secara Umum Jenis SDK tidak disarankan.1
Antrean Azure Tersedia Secara Umum Pengikatan input tidak ada Jenis SDK tidak disarankan.1
Azure Service Bus Tersedia Secara Umum Pengikatan input tidak ada Jenis SDK tidak disarankan.1
Azure Event Hubs Tersedia Secara Umum Pengikatan input tidak ada Jenis SDK tidak disarankan.1
Azure Cosmos DB Jenis SDK tidak digunakan2 Tersedia Secara Umum Jenis SDK tidak disarankan.1
Tabel Azure Pemicu tidak ada Tersedia Secara Umum Jenis SDK tidak disarankan.1
Azure Event Grid Tersedia Secara Umum Pengikatan input tidak ada Jenis SDK tidak disarankan.1

1 Untuk skenario output di mana Anda akan menggunakan jenis SDK, Anda harus membuat dan bekerja dengan klien SDK secara langsung alih-alih menggunakan pengikatan output. Lihat Registrasi klien Azure untuk contoh injeksi dependensi.

2 Pemicu Cosmos DB menggunakan umpan perubahan Azure Cosmos DB dan mengekspos item umpan perubahan sebagai jenis yang dapat diserialisasikan JSON. Tidak adanya jenis SDK adalah berdasarkan desain untuk skenario ini.

Catatan

Saat menggunakan ekspresi pengikatan yang mengandalkan data pemicu, jenis SDK untuk pemicu itu sendiri tidak dapat digunakan.

Pemicu HTTP

Pemicu HTTP memungkinkan fungsi dipanggil oleh permintaan HTTP. Ada dua pendekatan berbeda yang dapat digunakan:

  • Model integrasi ASP.NET Core yang menggunakan konsep yang akrab dengan pengembang ASP.NET Core
  • Model bawaan, yang tidak memerlukan dependensi tambahan dan menggunakan jenis kustom untuk permintaan dan respons HTTP. Pendekatan ini dipertahankan untuk kompatibilitas ke belakang dengan aplikasi pekerja terisolasi .NET sebelumnya.

Integrasi ASP.NET Core

Bagian ini menunjukkan cara bekerja dengan permintaan HTTP dan objek respons yang mendasar menggunakan jenis dari ASP.NET Core termasuk HttpRequest, HttpResponse, dan IActionResult. Model ini tidak tersedia untuk aplikasi yang menargetkan .NET Framework, yang seharusnya menggunakan model bawaan.

Catatan

Tidak semua fitur ASP.NET Core diekspos oleh model ini. Khususnya, pipeline middleware ASP.NET Core dan kemampuan routing tidak tersedia. integrasi ASP.NET Core mengharuskan Anda menggunakan paket yang diperbarui.

Untuk mengaktifkan integrasi ASP.NET Core untuk HTTP:

  1. Tambahkan referensi dalam proyek Anda ke paket Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore , versi 1.0.0 atau yang lebih baru.

  2. Perbarui proyek Anda untuk menggunakan versi paket tertentu ini:

  3. Dalam file Anda Program.cs, perbarui konfigurasi pembangun host untuk memanggil ConfigureFunctionsWebApplication(). Ini menggantikan ConfigureFunctionsWorkerDefaults() jika sebaliknya Anda akan menggunakan metode tersebut. Contoh berikut menunjukkan penyiapan minimal tanpa penyesuaian lainnya:

    using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .Build();

host.Run();

  4. Perbarui fungsi yang dipicu HTTP yang ada untuk menggunakan jenis ASP.NET Core. Contoh ini menunjukkan standar HttpRequest dan IActionResult yang digunakan untuk fungsi "halo, dunia" sederhana.

    [Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

Serialisasi JSON dengan integrasi ASP.NET Core

ASP.NET Core memiliki lapisan serialisasinya sendiri, dan tidak terpengaruh dengan menyesuaikan konfigurasi serialisasi umum. Untuk menyesuaikan perilaku serialisasi yang digunakan untuk pemicu HTTP, Anda perlu menyertakan .AddMvc() panggilan sebagai bagian dari pendaftaran layanan. Yang dikembalikan IMvcBuilder dapat digunakan untuk memodifikasi pengaturan serialisasi JSON ASP.NET Core.

Anda dapat terus menggunakan HttpRequestData dan HttpResponsedata saat menggunakan integrasi ASP.NET, meskipun untuk sebagian besar aplikasi, lebih baik menggunakan HttpRequest dan IActionResult. Menggunakan HttpRequestData/HttpResponseData tidak memanggil lapisan serialisasi ASP.NET Core dan sebagai gantinya bergantung pada konfigurasi serialisasi pekerja umum untuk aplikasi. Namun, ketika integrasi ASP.NET Core diaktifkan, Anda mungkin masih perlu menambahkan konfigurasi. Perilaku default dari ASP.NET Core adalah melarang IO sinkron. Untuk menggunakan serializer kustom yang tidak mendukung IO asinkron, seperti NewtonsoftJsonObjectSerializer, Anda perlu mengaktifkan IO sinkron untuk aplikasi Anda dengan mengonfigurasi KestrelServerOptions.

Contoh berikut menunjukkan cara mengonfigurasi JSON.NET (Newtonsoft.Json) dan paket NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson untuk serialisasi menggunakan pendekatan ini:

using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
        services.AddMvc().AddNewtonsoftJson();

        // Only needed if using HttpRequestData/HttpResponseData and a serializer that doesn't support asynchronous IO
        // services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true);
    })
    .Build();
host.Run();

Model HTTP bawaan

Dalam model bawaan, sistem menerjemahkan pesan permintaan HTTP masuk ke objek HttpRequestData yang diteruskan ke fungsi . Objek ini menyediakan data dari permintaan, termasuk Headers, , CookiesIdentities, URL, dan secara opsional pesan Body. Objek ini adalah representasi permintaan HTTP tetapi tidak terhubung langsung ke pendengar HTTP yang mendasar atau pesan yang diterima.

Demikian juga, fungsi mengembalikan objek HttpResponseData yang memberikan data yang digunakan untuk membuat respons HTTP, termasuk pesan StatusCode, Headers, dan opsional pesan Body.

Contoh berikut menunjukkan penggunaan HttpRequestData dan HttpResponseData:

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

Pengelogan

Anda dapat menulis ke log dengan menggunakan instans ILogger<T> atau ILogger . Pencatat dapat diperoleh melalui injeksi dependensi dari sebuah ILogger<T> atau sebuah ILoggerFactory:

public class MyFunction {
    
    private readonly ILogger<MyFunction> _logger;
    
    public MyFunction(ILogger<MyFunction> logger) {
        _logger = logger;
    }
    
    [Function(nameof(MyFunction))]
    public void Run([BlobTrigger("samples-workitems/{name}", Connection = "")] string myBlob, string name)
    {
        _logger.LogInformation($"C# Blob trigger function Processed blob\n Name: {name} \n Data: {myBlob}");
    }

}

Pencatat juga dapat diperoleh dari objek FunctionContext yang diteruskan ke fungsi Anda. Panggil metode GetLogger<T> atau GetLogger, yang meneruskan nilai string yang merupakan nama untuk kategori tempat log ditulis. Kategori ini biasanya merupakan nama fungsi tertentu tempat log ditulis. Untuk mempelajari selengkapnya tentang kategori, lihat artikel pemantauan.

Gunakan metode ILogger<T> dan ILogger untuk menulis berbagai tingkat log, seperti LogWarning atau LogError. Untuk mempelajari selengkapnya tentang tingkat log, lihat artikel pemantauan. Anda dapat menyesuaikan tingkat log untuk komponen yang ditambahkan ke kode Anda dengan mendaftarkan filter:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services =>
    {
        // Registers IHttpClientFactory.
        // By default this sends a lot of Information-level logs.
        services.AddHttpClient();
    })
    .ConfigureLogging(logging =>
    {
        // Disable IHttpClientFactory Informational logs.
        // Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
        logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    })
    .Build();

Sebagai bagian dari mengonfigurasi aplikasi di Program.cs, Anda juga dapat menentukan perilaku bagaimana kesalahan muncul di log Anda. Perilaku default bergantung pada jenis pembangun yang Anda gunakan.

Ketika Anda menggunakan HostBuilder, secara default, pengecualian yang dilemparkan oleh kode Anda dapat berakhir dibungkus dalam RpcException. Untuk menghapus lapisan tambahan ini, atur EnableUserCodeException properti ke "true" sebagai bagian dari mengonfigurasi penyusun:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(builder => {}, options =>
    {
        options.EnableUserCodeException = true;
    })
    .Build();

host.Run();

Application Insights

Anda dapat mengonfigurasi aplikasi proses terisolasi untuk memancarkan log langsung ke Application Insights. Perilaku ini menggantikan perilaku default menyampaikan log melalui host. Kecuali Anda menggunakan .NET Aspire, sangat disarankan untuk mengonfigurasi integrasi langsung Application Insights karena ini memberi Anda kontrol atas bagaimana log tersebut dihasilkan.

Integrasi Application Insights tidak diaktifkan secara default di semua pengalaman penyiapan. Beberapa templat akan membuat proyek Fungsi dengan paket yang diperlukan dan kode startup yang terkomen. Jika Anda ingin menggunakan integrasi Application Insights, Anda dapat membuka komentar baris ini di Program.cs dan pada file proyek .csproj. Instruksi di sisa bagian ini juga menjelaskan cara mengaktifkan integrasi.

Jika proyek Anda adalah bagian dari orkestrasi .NET Aspire, proyek tersebut menggunakan OpenTelemetry untuk pemantauan sebagai gantinya. Anda tidak boleh mengaktifkan integrasi Application Insights langsung dalam proyek .NET Aspire. Sebagai gantinya, konfigurasikan pengekspor OpenTelemetry Azure Monitor sebagai bagian dari proyek layanan default. Jika proyek Functions Anda menggunakan integrasi Application Insights dalam konteks .NET Aspire, aplikasi akan mengalami kesalahan saat startup.

Memasang paket

Untuk menulis log langsung ke Application Insights dari kode Anda, tambahkan referensi ke paket ini di proyek Anda:

Anda dapat menjalankan perintah berikut untuk menambahkan referensi ini ke proyek Anda:

dotnet add package Microsoft.ApplicationInsights.WorkerService
dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights

Mengonfigurasi pengaktifan

Dengan paket yang diinstal, Anda harus memanggil AddApplicationInsightsTelemetryWorkerService() dan ConfigureFunctionsApplicationInsights() selama konfigurasi layanan dalam file Anda Program.cs , seperti dalam contoh ini:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

Panggilan untuk ConfigureFunctionsApplicationInsights() menambahkan ITelemetryModule, yang mendengarkan Fungsi yang ditentukan ActivitySource. Ini membuat telemetri dependensi yang diperlukan untuk mendukung pelacakan terdistribusi. Untuk mempelajari selengkapnya tentang AddApplicationInsightsTelemetryWorkerService() dan cara menggunakannya, lihat Aplikasi Insights untuk aplikasi Layanan Pekerja.

Mengelola tingkat log

Penting

Host Functions dan pekerja proses terisolasi memiliki konfigurasi terpisah untuk tingkat log, dll. Setiap konfigurasi Application Insights dalam host.json tidak akan memengaruhi pengelogan dari pekerja, dan demikian pula, konfigurasi yang dibuat dalam kode pekerja Anda tidak akan memengaruhi pengelogan dari host. Anda perlu menerapkan perubahan di kedua tempat jika skenario Anda memerlukan penyesuaian di kedua lapisan.

Sisa aplikasi Anda terus bekerja dengan ILogger dan ILogger<T>. Namun, secara default, Application Insights SDK menambahkan filter pengelogan yang menginstruksikan pencatat untuk hanya menangkap peringatan dan log yang lebih parah. Jika Anda ingin menonaktifkan perilaku ini, hapus aturan filter sebagai bagian dari konfigurasi layanan:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .ConfigureLogging(logging =>
    {
        logging.Services.Configure<LoggerFilterOptions>(options =>
        {
            LoggerFilterRule defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
            if (defaultRule is not null)
            {
                options.Rules.Remove(defaultRule);
            }
        });
    })
    .Build();

host.Run();

Pengoptimalan performa

Bagian ini menguraikan opsi yang dapat Anda aktifkan yang meningkatkan performa di sekitar cold start.

Secara umum, aplikasi Anda harus menggunakan versi terbaru dependensi intinya. Minimal, Anda harus memperbarui proyek Anda sebagai berikut:

  1. Tingkatkan Microsoft.Azure.Functions.Worker ke versi 1.19.0 atau yang lebih baru.
  2. Tingkatkan Microsoft.Azure.Functions.Worker.Sdk ke versi 1.16.4 atau yang lebih baru.
  3. Tambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App, kecuali aplikasi Anda menargetkan .NET Framework.

Cuplikan berikut menunjukkan konfigurasi ini dalam konteks file proyek:

  <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.16.4" />
  </ItemGroup>

Placeholder

Tempat penampung adalah kemampuan platform yang meningkatkan cold start untuk aplikasi yang menargetkan .NET 6 atau yang lebih baru. Untuk menggunakan pengoptimalan ini, Anda harus secara eksplisit mengaktifkan tempat penampung menggunakan langkah-langkah berikut:

  1. Perbarui konfigurasi proyek Anda untuk menggunakan versi dependensi terbaru, seperti yang dirinci di bagian sebelumnya.

  2. Atur WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED pengaturan aplikasi ke 1, yang dapat Anda lakukan dengan menggunakan perintah az functionapp config appsettings set ini:

    az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'

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

  3. Pastikan bahwa netFrameworkVersion properti aplikasi fungsi cocok dengan kerangka kerja target proyek Anda, yang harus .NET 6 atau yang lebih baru. Anda dapat melakukan ini dengan menggunakan perintah az functionapp config set ini:

    az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

    Dalam contoh ini, ganti <framework> juga dengan string versi yang sesuai, seperti v8.0, sesuai dengan versi .NET target Anda.

  4. Pastikan aplikasi fungsi Anda dikonfigurasi untuk menggunakan proses 64-bit, yang dapat Anda lakukan dengan menggunakan perintah az functionapp config set ini:

    az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false

Penting

Saat mengatur WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED ke 1, semua konfigurasi aplikasi fungsi lainnya harus diatur dengan benar. Jika tidak, aplikasi fungsi Anda mungkin gagal dimulai.

Pelaksana yang dioptimalkan

Pelaksana fungsi adalah komponen platform yang menyebabkan pemanggilan berjalan. Versi yang dioptimalkan dari komponen ini diaktifkan secara default dimulai dengan SDK versi 1.16.2. Tidak diperlukan konfigurasi lainnya.

ReadyToRun

Anda dapat mengompilasi aplikasi fungsi Anda sebagai biner ReadyToRun. ReadyToRun adalah bentuk kompilasi sebelum waktu berjalan yang dapat meningkatkan performa startup untuk membantu mengurangi efek cold start ketika dijalankan dalam rencana Konsumsi. ReadyToRun tersedia di .NET 6 dan versi yang lebih baru dan memerlukan runtime Azure Functions versi 4.0 atau yang lebih baru .

ReadyToRun mengharuskan Anda untuk membangun proyek terhadap arsitektur runtime aplikasi hosting. Jika ini tidak selaras, aplikasi Anda akan mengalami kesalahan saat startup. Pilih pengidentifikasi runtime Anda dari tabel ini:

Sistem Operasi Aplikasi adalah 32-bit1 Pengidentifikasi waktu proses
Windows Benar win-x86
Windows Salah win-x64
Linux Benar N/A (tidak didukung)
Linux Salah linux-x64

1 Hanya aplikasi 64-bit yang memenuhi syarat untuk beberapa pengoptimalan performa lainnya.

Untuk memeriksa apakah aplikasi Windows Anda 32-bit atau 64-bit, Anda dapat menjalankan perintah CLI berikut, mengganti <group_name> dengan nama grup sumber daya Anda dan <app_name> dengan nama aplikasi Anda. Output "true" menunjukkan bahwa aplikasi adalah 32-bit, dan "false" menunjukkan 64-bit.

 az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

Anda dapat mengubah aplikasi Anda menjadi 64-bit dengan perintah berikut, menggunakan substitusi yang sama:

az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

Untuk mengompilasi proyek Anda sebagai ReadyToRun, perbarui file proyek Anda dengan menambahkan elemen <PublishReadyToRun> dan <RuntimeIdentifier>. Contoh berikut menunjukkan konfigurasi untuk penerbitan ke aplikasi fungsi Windows 64-bit.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

Jika Anda tidak ingin mengatur <RuntimeIdentifier> sebagai bagian dari file proyek, Anda juga dapat mengonfigurasi ini sebagai bagian dari gerakan penerbitan itu sendiri. Misalnya, dengan aplikasi fungsi Windows 64-bit, perintah .NET CLI adalah:

dotnet publish --runtime win-x64

Di Visual Studio, opsi Target Runtime dalam profil publish harus diatur ke pengidentifikasi runtime yang benar. Saat diatur ke nilai default Portable, ReadyToRun tidak digunakan.

Menyebarkan ke Azure Functions

Saat Anda menyebarkan proyek kode fungsi ke Azure, proyek tersebut harus berjalan di aplikasi fungsi atau di kontainer Linux. Aplikasi fungsi dan sumber daya Azure lain yang diperlukan harus ada sebelum Anda menyebarkan kode Anda.

Anda juga dapat menyebarkan aplikasi fungsi Anda di kontainer Linux. Untuk informasi selengkapnya, lihat Bekerja dengan kontainer dan Azure Functions.

Membuat sumber daya Azure

Anda dapat membuat aplikasi fungsi dan sumber daya lain yang diperlukan di Azure menggunakan salah satu metode berikut:

  • Visual Studio: Visual Studio dapat membuat sumber daya untuk Anda selama proses penerbitan kode.
  • Visual Studio Code: Visual Studio Code dapat tersambung ke langganan Anda, membuat sumber daya yang diperlukan oleh aplikasi Anda, lalu menerbitkan kode Anda.
  • Azure CLI: Anda dapat menggunakan Azure CLI untuk membuat sumber daya yang diperlukan di Azure.
  • Azure PowerShell: Anda dapat menggunakan Azure PowerShell untuk membuat sumber daya yang diperlukan di Azure.
  • Templat penyebaran: Anda dapat menggunakan templat ARM dan file Bicep untuk mengotomatiskan penyebaran sumber daya yang diperlukan ke Azure. Pastikan templat Anda menyertakan pengaturan yang diperlukan.
  • portal Azure: Anda dapat membuat sumber daya yang diperlukan di portal Azure.

Menerbitkan aplikasi Anda

Setelah membuat aplikasi fungsi dan sumber daya lain yang diperlukan di Azure, Anda dapat menyebarkan proyek kode ke Azure menggunakan salah satu metode berikut:

Untuk informasi selengkapnya, lihat Teknologi penyebaran di Azure Functions.

Muatan penyebaran

Banyak metode penyebaran menggunakan arsip zip. Jika Anda membuat arsip zip sendiri, itu harus mengikuti struktur yang diuraikan di bagian ini. Jika tidak, aplikasi Anda mungkin mengalami kesalahan saat startup.

Payload penyebaran harus cocok dengan output dotnet publish perintah, meskipun tanpa folder induk yang tertutup. Arsip zip harus dibuat dari file berikut:

  • .azurefunctions/
  • extensions.json
  • functions.metadata
  • host.json
  • worker.config.json
  • Proyek Anda dapat dieksekusi (aplikasi konsol)
  • File dan direktori pendukung lain sejajar dengan file yang dapat dieksekusi tersebut.

File-file ini dihasilkan oleh proses build, dan tidak dimaksudkan untuk diedit secara langsung.

Saat menyiapkan arsip zip untuk penyebaran, Anda hanya boleh mengompres konten direktori output, bukan direktori penutup itu sendiri. Ketika arsip diekstrak ke direktori kerja saat ini, file yang tercantum di atas harus segera terlihat.

Persyaratan penyebaran

Ada beberapa persyaratan untuk menjalankan fungsi .NET dalam model pekerja terisolasi di Azure, tergantung pada sistem operasi:

  • FUNCTIONS_WORKER_RUNTIME harus diatur ke nilai dotnet-isolated.
  • netFrameworkVersion harus diatur ke versi yang diinginkan.

Saat Anda membuat aplikasi fungsi di Azure menggunakan metode di bagian sebelumnya, pengaturan yang diperlukan ini ditambahkan untuk Anda. Saat Anda membuat sumber daya ini dengan menggunakan templat ARM atau file Bicep untuk otomatisasi, Anda harus memastikan untuk mengaturnya dalam templat.

.NET Aspire (Pratinjau)

.NET Aspire adalah kerangka kerja yang terstruktur dengan tegas yang menyederhanakan pengembangan aplikasi terdistribusi di komputasi awan. Anda dapat mendaftarkan proyek model pekerja terisolasi .NET 8 dan .NET 9 ke dalam orkestrasi Aspire 9.0 dengan dukungan fitur pratinjau. Lihat Azure Functions dengan .NET Aspire (Pratinjau) untuk informasi selengkapnya.

Pemecahan Masalah

Saat berjalan secara lokal menggunakan Visual Studio atau Visual Studio Code, Anda dapat men-debug proyek pekerja terisolasi .NET seperti biasa. Namun, ada dua skenario penelusuran kesalahan yang tidak berfungsi seperti yang diharapkan.

Penelusuran Kesalahan Jarak Jauh menggunakan Visual Studio

Karena aplikasi proses pekerja terisolasi Anda berjalan di luar runtime Functions, Anda perlu melampirkan debugger jarak jauh ke proses terpisah. Untuk mempelajari selengkapnya tentang penelusuran kesalahan menggunakan Visual Studio, lihat Penelusuran Kesalahan Jarak Jauh.

Penelusuran kesalahan saat menargetkan .NET Framework

Jika proyek terisolasi Anda menargetkan .NET Framework 4.8, Anda perlu melakukan langkah-langkah secara manual untuk mengaktifkan debugging. Langkah-langkah ini tidak diperlukan jika menggunakan kerangka kerja target lain.

Aplikasi Anda harus dimulai dengan panggilan ke FunctionsDebugger.Enable(); sebagai operasi pertamanya. Ini terjadi pada metode Main() sebelum menginisialisasi HostBuilder. File Anda Program.cs akan terlihat mirip dengan ini:

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

namespace MyDotnetFrameworkProject
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .Build();

            host.Run();
        }
    }
}

Selanjutnya, Anda perlu secara manual mengaitkan debugger .NET Framework ke proses tersebut. Visual Studio belum melakukan ini secara otomatis untuk aplikasi proses pekerja terisolasi .NET Framework, dan operasi "Mulai Debugging" harus dihindari.

Di direktori proyek Anda (atau direktori output build-nya), jalankan:

func host start --dotnet-isolated-debug

Proses ini memulai pekerja Anda, dan kemudian berhenti dengan pesan berikut:

Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...

Dimana <process id> adalah ID dari proses pekerja Anda. Anda sekarang dapat menggunakan Visual Studio untuk melampirkan proses secara manual. Untuk petunjuk tentang operasi ini, lihat Cara melampirkan ke proses yang sedang berjalan.

Setelah debugger dilampirkan, eksekusi proses dilanjutkan, dan Anda akan dapat men-debug.

Pratinjau versi .NET

Sebelum rilis yang tersedia secara umum, versi .NET mungkin dirilis dalam status Pratinjau atau Go-live . Lihat Kebijakan Dukungan Resmi .NET untuk detail tentang status ini.

Meskipun mungkin untuk menargetkan rilis tertentu dari proyek Functions lokal, aplikasi fungsi yang dihosting di Azure mungkin tidak memiliki rilis yang tersedia. Azure Functions hanya dapat digunakan dengan rilis Pratinjau atau Go-live yang tercantum di bagian ini.

Azure Functions saat ini tidak mendukung rilis .NET "Pratinjau" atau "Siap Produksi". Lihat Versi yang didukung untuk daftar rilis yang tersedia secara umum yang dapat Anda gunakan.

Menggunakan pratinjau .NET SDK

Untuk menggunakan Azure Functions dengan versi pratinjau .NET, Anda perlu memperbarui proyek Anda dengan:

  1. Menginstal versi .NET SDK yang relevan dalam pengembangan Anda
  2. Mengubah pengaturan TargetFramework dalam file .csproj Anda

Saat menyebarkan ke aplikasi fungsi di Azure, Anda juga perlu memastikan bahwa kerangka kerja tersedia untuk aplikasi. Selama periode pratinjau, beberapa alat dan pengalaman mungkin tidak menampilkan versi pratinjau baru sebagai opsi. Jika Anda tidak melihat versi pratinjau yang disertakan dalam portal Microsoft Azure, misalnya, Anda dapat menggunakan REST API, file Bicep, atau Azure CLI untuk mengonfigurasi versi secara manual.

Untuk aplikasi yang dihosting di Windows, gunakan perintah Azure CLI berikut. Ganti <groupName> dengan nama grup sumber daya, dan ganti <appName> dengan nama aplikasi fungsi Anda. Ganti <framework> dengan string versi yang sesuai, seperti v8.0.

az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

Pertimbangan untuk menggunakan versi pratinjau .NET

Perhatikan hal-hal berikut saat menggunakan Functions dengan versi pratinjau .NET:

  • Saat menulis fungsi di Visual Studio, Anda harus menggunakan Pratinjau Visual Studio, yang mendukung pembuatan proyek Azure Functions dengan SDK pratinjau .NET.

  • Pastikan Anda memiliki alat dan templat Functions terbaru. Untuk memperbarui alat Anda:

    1. Navigasi ke , pilih > di bawah Proyek dan Solusi.
    2. Pilih Periksa pembaruan dan instal pembaruan seperti yang diminta.

  • Selama periode pratinjau, lingkungan pengembangan Anda mungkin memiliki versi pratinjau .NET yang lebih baru daripada layanan yang dihosting. Ini dapat menyebabkan aplikasi fungsi Anda gagal saat disebarkan. Untuk mengatasi hal ini, Anda dapat menentukan versi SDK yang akan digunakan di global.json.

    1. Jalankan dotnet --list-sdks perintah dan perhatikan versi pratinjau yang saat ini Anda gunakan selama pengembangan lokal.
    2. Jalankan dotnet new globaljson --sdk-version <SDK_VERSION> --force perintah , di mana <SDK_VERSION> adalah versi yang Anda gunakan secara lokal. Misalnya, dotnet new globaljson --sdk-version dotnet-sdk-8.0.100-preview.7.23376.3 --force menyebabkan sistem menggunakan .NET 8 Preview 7 SDK saat membangun proyek Anda.

Catatan

Karena pemuatan kerangka kerja pratinjau just-in-time, aplikasi fungsi yang berjalan di Windows dapat mengalami peningkatan waktu start dingin dibandingkan dengan versi GA terdahulu.

Langkah berikutnya

Pelajari selengkapnya tentang praktik terbaik untuk Azure Functions

Memigrasikan aplikasi .NET ke model pekerja yang terisolasi

Integrasikan dengan .NET Aspire