Mengembangkan fungsi pustaka kelas C# menggunakan Azure Functions

Artikel
04/07/2024

Penting

Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.

Artikel ini adalah pengantar untuk mengembangkan Azure Functions dengan menggunakan skrip C# pustaka kelas .NET. Pustaka kelas ini digunakan untuk menjalankan dalam proses dengan runtime Functions. Fungsi .NET Anda dapat berjalan _isolated dari runtime Functions, yang menawarkan beberapa keuntungan. Untuk mempelajari selengkapnya, lihat model pekerja yang terisolasi. Untuk perbandingan komprehensif antara kedua model ini, lihat Perbedaan antara model dalam proses dan model pekerja yang terisolasi.

Penting

Artikel ini mendukung fungsi pustaka kelas .NET yang berjalan dalam proses dengan runtime. Fungsi C# Anda juga dapat kehabisan proses dan diisolasi dari runtime Fungsi. Model proses pekerja yang terisolasi adalah satu-satunya cara untuk menjalankan versi aplikasi .NET dan .NET Framework non-LTS dalam versi runtime Functions saat ini. Untuk mempelajari lebih lanjut, lihat fungsi proses pekerja terisolasi .NET. Untuk perbandingan komprehensif antara proses pekerja yang terisolasi dan Fungsi .NET dalam proses, lihat Perbedaan antara proses dalam proses dan mengisolasi proses pekerja .NET Azure Functions.

Sebagai pengembang C#, Anda mungkin juga tertarik dengan salah satu artikel berikut:

Memulai	Konsep	Pembelajaran/sampel terpandu
Menggunakan Visual Studio Menggunakan Visual Studio Code Menggunakan alat baris perintah	Opsi hosting Pertimbangan performa Pengembangan Visual Studio Injeksi dependensi	Buat aplikasi tanpa server Sampel C++

Azure Functions mendukung C# dan bahasa pemrograman skrip C#. Jika Anda mencari panduan tentang menggunakan C# di portal Microsoft Azure, lihat referensi pengembang skrip C# (.csx).

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 proses⁵
Functions 4.x	.NET 8.0 .NET 7.0¹ .NET 6.0² .NET Framework 4.8³	.NET 6.0²
Functions 1.x⁴	n/a	.NET Framework 4.8

¹ .NET 7 mencapai akhir dukungan resmi pada 14 Mei 2024.
² .NET 6 mencapai akhir dukungan resmi pada 12 November 2024.
³ Proses build juga memerlukan .NET SDK. ⁴ 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.
⁵ 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.

Proyek pustaka kelas Functions

Di Visual Studio, templat proyek Azure Functions membuat proyek pustaka kelas C# yang berisi file berikut ini:

host.js - menyimpan pengaturan konfigurasi yang mempengaruhi semua fungsi dalam proyek saat berjalan secara lokal atau di Azure.
local.settings.json - menyimpan pengaturan aplikasi dan string koneksi yang digunakan saat berjalan secara lokal. File ini berisi rahasia dan tidak dipublikasikan ke aplikasi fungsi Anda di Azure. Sebagai gantinya, tambahkan pengaturan aplikasi ke aplikasi fungsi Anda.

Saat Anda membuat proyek, struktur folder yang terlihat seperti contoh berikut dibuat di direktori output build:

<framework.version>
 | - bin
 | - MyFirstFunction
 | | - function.json
 | - MySecondFunction
 | | - function.json
 | - host.json

Direktori inilah yang akan diterapkan ke aplikasi fungsi Anda di Azure. Ekstensi pengikatan yang diperlukan dalam versi 2.x dari runtime Functions ditambahkan ke proyek sebagai paket NuGet.

Penting

Proses build membuat file function.json untuk setiap fungsi. File function.json tidak dimaksudkan untuk diedit secara langsung. Anda tidak dapat mengubah konfigurasi pengikatan atau menonaktifkan fungsi dengan mengedit file ini. Untuk mempelajari cara menonaktifkan fungsi, lihat Cara menonaktifkan fungsi.

Metode yang dikenali sebagai fungsi

Di pustaka kelas, fungsi adalah metode dengan FunctionName atribut pemicu dan , seperti yang ditunjukkan dalam contoh berikut:

public static class SimpleExample
{
    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

Atribut FunctionName 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. Contoh di atas menunjukkan metode statis yang digunakan, tetapi fungsi tidak diharuskan statis.

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

Parameter tanda tangan metode

Tanda tangan metode mungkin berisi parameter selain yang digunakan dengan atribut pemicu. Berikut adalah beberapa parameter lain yang dapat Anda sertakan:

Pengikatan input dan output ditandai dengan melengkapinya dengan atribut.
Parameter ILogger atau TraceWriter (hanya versi 1.x) untuk pengelogan.
Parameter CancellationToken untuk mematikan dengan tanpa paksaan.
Parameter ekspresi pengikatan untuk mendapatkan metadata pemicu.

Urutan parameter dalam tanda tangan fungsi tidak masalah. Misalnya, Anda dapat meletakkan parameter pemicu sebelum atau sesudah pengikatan lain dan Anda dapat meletakkan parameter pencatat sebelum atau sesudah parameter pemicu atau pengikatan.

Pengikatan output

Fungsi dapat memiliki nol atau beberapa pengikatan output yang ditentukan dengan menggunakan parameter output.

Contoh berikut memodifikasi contoh sebelumnya dengan menambahkan pengikatan antrean output bernama myQueueItemCopy. Fungsi ini menulis isi pesan yang memicu fungsi ke pesan baru dalam antrean yang berbeda.

public static class SimpleExampleWithOutput
{
    [FunctionName("CopyQueueMessage")]
    public static void Run(
        [QueueTrigger("myqueue-items-source")] string myQueueItem, 
        [Queue("myqueue-items-destination")] out string myQueueItemCopy,
        ILogger log)
    {
        log.LogInformation($"CopyQueueMessage function processed: {myQueueItem}");
        myQueueItemCopy = myQueueItem;
    }
}

Nilai yang ditetapkan ke pengikatan output ditulis saat fungsi keluar. Anda dapat menggunakan lebih dari satu pengikatan output dalam fungsi hanya dengan menetapkan nilai ke beberapa parameter output.

Artikel referensi yang mengikat (Antrean penyimpanan, misalnya) menjelaskan jenis parameter mana yang dapat Anda gunakan dengan atribut pemicu, pengikatan input, atau output.

Contoh ekspresi pengikatan

Kode berikut mendapatkan nama antrean untuk memantau dari pengaturan aplikasi, dan mendapatkan waktu pembuatan pesan antrean di insertionTime parameter.

public static class BindingExpressionsExample
{
    [FunctionName("LogQueueMessage")]
    public static void Run(
        [QueueTrigger("%queueappsetting%")] string myQueueItem,
        DateTimeOffset insertionTime,
        ILogger log)
    {
        log.LogInformation($"Message content: {myQueueItem}");
        log.LogInformation($"Created at: {insertionTime}");
    }
}

Function.json otomatis

Proses build membuat file function.json dalam folder fungsi di folder build. Seperti disebutkan sebelumnya, file ini tidak dimaksudkan untuk diedit secara langsung. Anda tidak dapat mengubah konfigurasi pengikatan atau menonaktifkan fungsi dengan mengedit file ini.

Tujuan dari file ini adalah untuk memberikan informasi kepada pengontrol skala untuk penggunaan keputusan penskalaan pada rencana Konsumsi. Untuk alasan ini, file hanya memiliki info pemicu, bukan pengikatan input / output.

File function.json yang dihasilkan mencakup configurationSource properti yang memberitahu runtime untuk menggunakan atribut .NET untuk pengikatan daripada konfigurasi function.json. Berikut contohnya:

{
  "generatedBy": "Microsoft.NET.Sdk.Functions-1.0.0.0",
  "configurationSource": "attributes",
  "bindings": [
    {
      "type": "queueTrigger",
      "queueName": "%input-queue-name%",
      "name": "myQueueItem"
    }
  ],
  "disabled": false,
  "scriptFile": "..\\bin\\FunctionApp1.dll",
  "entryPoint": "FunctionApp1.QueueTrigger.Run"
}

Microsoft.NET.Sdk.Functions

Pembuatan file function.json dilakukan oleh paket NuGet Microsoft.NET.Sdk.Functions.

Contoh berikut menunjukkan bagian yang relevan dari .csproj file yang memiliki kerangka kerja target yang berbeda dari paket yang sama Sdk :

v4.x
v1.x

<PropertyGroup>
  <TargetFramework>net6.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
</ItemGroup>

<PropertyGroup>
  <TargetFramework>net48</TargetFramework>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
</ItemGroup>

Di antara Sdk paket dependensi di antaranya adalah pemicu dengan pengikatan. Proyek 1.x mengacu pada pemicu dan pengikatan 1.x karena pemicu dan pengikatan tersebut menargetkan .NET Framework, sementara 4.x memicu dan mengikat target .NET Core.

Paket Sdk ini juga tergantung pada Newtonsoft.Json, dan secara tidak langsung pada WindowsAzure.Storage. Dependensi ini memastikan bahwa proyek Anda menggunakan versi paket yang berfungsi dengan versi runtime Functions yang ditargetkan oleh proyek. Misalnya, Newtonsoft.Json memiliki versi 11 untuk .NET Framework 4.6.1, tetapi runtime Functions yang menargetkan .NET Framework 4.6.1 hanya kompatibel dengan Newtonsoft.Json 9.0.1. Jadi kode fungsi Anda dalam proyek itu juga harus menggunakan Newtonsoft.Json 9.0.1.

Kode sumber untuk Microsoft.NET.Sdk.Functions tersedia dalam repositori GitHub azure-functions-vs-build-sdk.

Versi runtime lokal

Visual Studio menggunakan Azure Functions Core Tools untuk menjalankan proyek Functions di komputer lokal. Alat Inti adalah antarmuka baris perintah untuk runtime Functions.

Jika Anda menginstal Core Tools menggunakan paket penginstal Windows (MSI) atau dengan menggunakan npm, itu tidak memengaruhi versi Core Tools yang digunakan oleh Visual Studio. Untuk runtime Functions versi 1.x, Visual Studio menyimpan versi Alat Inti di %USERPROFILE%\AppData\Local\Azure.Functions.Cli dan menggunakan versi terbaru yang disimpan di sana. Untuk Functions 4.x, Core Tools disertakan dalam ekstensi Azure Functions dan Web Jobs Tools . Untuk Functions 1.x, Anda dapat melihat versi apa yang digunakan dalam output konsol saat menjalankan proyek Functions:

[3/1/2018 9:59:53 AM] Starting Host (HostId=contoso2-1518597420, Version=2.0.11353.0, ProcessId=22020, Debug=False, Attempt=0, FunctionsExtensionVersion=)

ReadyToRun

Anda dapat mengompilasi aplikasi fungsi Anda sebagai biner ReadyToRun. ReadyToRun adalah bentuk kompilasi ke depan yang dapat meningkatkan performa startup untuk membantu mengurangi dampak cold-start saat berjalan dalam rencana Konsumsi.

ReadyToRun tersedia di .NET 6 dan versi yang lebih baru dan memerlukan runtime Azure Functions versi 4.0.

Untuk mengompilasi proyek Anda sebagai ReadyToRun, perbarui file proyek Anda dengan menambahkan elemen <PublishReadyToRun> dan <RuntimeIdentifier>. Berikut ini adalah konfigurasi untuk menerbitkan ke aplikasi fungsi Windows 32-bit.

<PropertyGroup>
  <TargetFramework>net6.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <PublishReadyToRun>true</PublishReadyToRun>
  <RuntimeIdentifier>win-x86</RuntimeIdentifier>
</PropertyGroup>

Penting

Mulai dari .NET 6, dukungan untuk kompilasi Composite ReadyToRun telah ditambahkan. Lihat Pembatasan platform dan arsitektur ReadyToRun Cross.

Anda juga dapat membuat aplikasi dengan ReadyToRun dari baris perintah. Untuk informasi lebih lanjut, lihat -p:PublishReadyToRun=true opsi di dotnet publish.

Jenis yang didukung untuk pengikatan

Setiap pengikatan memiliki jenis yang didukung sendiri; misalnya, atribut pemicu blob dapat digunakan dengan parameter string, parameter POCO, parameter CloudBlockBlob, atau salah satu dari beberapa jenis lain yang didukung. Artikel referensi pengikatan untuk pengikatan blob mencantumkan semua jenis parameter yang didukung. Untuk informasi selengkapnya, lihat Pemicu dan pengikatan dan dokumen referensi pengikatan untuk setiap jenis pengikatan.

Tip

Jika Anda berencana untuk menggunakan pengikatan HTTP atau WebHook, rencanakan untuk menghindari kekurangan port yang dapat disebabkan oleh pembuatan objek yang tidak tepat dari HttpClient. Untuk informasi selengkapnya, lihat Cara mengelola koneksi di Azure Functions.

Pengikatan ke nilai pengembalian metode

Anda dapat menggunakan nilai pengembalian metode untuk pengikatan output, dengan menerapkan atribut ke nilai pengembalian metode. Misalnya, lihat Pemicu dan pengikatan.

Gunakan nilai yang dikembalikan hanya jika eksekusi fungsi yang berhasil selalu menghasilkan nilai yang dikembalikan untuk diteruskan ke pengikatan output. Jika tidak, gunakan ICollector atau IAsyncCollector, seperti yang ditunjukkan di bagian berikut.

Menulis beberapa nilai output

Untuk menulis beberapa nilai ke pengikatan output, atau jika pemanggilan fungsi yang berhasil mungkin tidak menghasilkan apa pun untuk diteruskan ke pengikatan output, gunakan jenis ICollector atau IAsyncCollector. Jenis-jenis ini adalah koleksi hanya-tulis yang ditulis ke pengikatan output ketika metode selesai.

Contoh ini menulis beberapa pesan antrean ke dalam antrean yang sama menggunakan ICollector:

public static class ICollectorExample
{
    [FunctionName("CopyQueueMessageICollector")]
    public static void Run(
        [QueueTrigger("myqueue-items-source-3")] string myQueueItem,
        [Queue("myqueue-items-destination")] ICollector<string> myDestinationQueue,
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
        myDestinationQueue.Add($"Copy 1: {myQueueItem}");
        myDestinationQueue.Add($"Copy 2: {myQueueItem}");
    }
}

Asinkron

Untuk membuat fungsi asinkron, gunakan kata kunci asyncdan kembalikan Task objek.

public static class AsyncExample
{
    [FunctionName("BlobCopy")]
    public static async Task RunAsync(
        [BlobTrigger("sample-images/{blobName}")] Stream blobInput,
        [Blob("sample-images-copies/{blobName}", FileAccess.Write)] Stream blobOutput,
        CancellationToken token,
        ILogger log)
    {
        log.LogInformation($"BlobCopy function processed.");
        await blobInput.CopyToAsync(blobOutput, 4096, token);
    }
}

Anda tidak dapat menggunakan parameter out dalam fungsi asinkron. Untuk pengikatan output, gunakan nilai pengembalian fungsi atau objek kolektor.

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.

Pertimbangkan kasus ketika Anda memiliki fungsi yang memproses pesan dalam batch. Fungsi yang dipicu azure Bus Layanan berikut memproses array objek ServiceBusReceivedMessage, yang mewakili batch pesan masuk yang akan diproses oleh pemanggilan fungsi tertentu:

using Azure.Messaging.ServiceBus;
using System.Threading;

namespace ServiceBusCancellationToken
{
    public static class servicebus
    {
        [FunctionName("servicebus")]
        public static void Run([ServiceBusTrigger("csharpguitar", Connection = "SB_CONN")]
               ServiceBusReceivedMessage[] messages, CancellationToken cancellationToken, ILogger log)
        {
            try
            { 
                foreach (var message in messages)
                {
                    if (cancellationToken.IsCancellationRequested)
                    {
                        log.LogInformation("A cancellation token was received. Taking precautionary actions.");
                        //Take precautions like noting how far along you are with processing the batch
                        log.LogInformation("Precautionary activities --complete--.");
                        break;
                    }
                    else
                    {
                        //business logic as usual
                        log.LogInformation($"Message: {message} was processed.");
                    }
                }
            }
            catch (Exception ex)
            {
                log.LogInformation($"Something unexpected happened: {ex.Message}");
            }
        }
    }
}

Pencatatan

Dalam kode fungsi, Anda dapat menulis output ke log yang muncul sebagai jejak di Application Insights. Cara yang disarankan untuk menulis ke log adalah memasukkan parameter tipe ILogger, yang biasanya bernama log. Versi 1.x dari runtime Functions yang digunakan TraceWriter dan juga menulis ke Application Insights, tetapi tidak mendukung pengelogan terstruktur. Jangan gunakan Console.Write untuk menulis log Anda, karena data ini tidak ditangkap oleh Application Insights.

ILogger

Dalam definisi fungsi Anda, sertakan parameter ILogger, yang mendukung pengelogan terstruktur.

Dengan objek ILogger, Anda memanggil Log<level>metode ekstensi di ILogger untuk membuat log. Kode berikut menulis Information log dengan kategori Function.<YOUR_FUNCTION_NAME>.User.:

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, ILogger logger)
{
    logger.LogInformation("Request for item with key={itemKey}.", id);

Untuk mempelajari selengkapnya tentang bagaimana Fungsi mengimplementasikan ILogger, lihat Mengumpulkan data telemetri. Kategori yang diawali dengan Function asumsikan Anda menggunakan ILogger instans. Jika Anda memilih untuk menggunakan ILogger<T>, nama kategori mungkin lebih didasarkan pada T.

Pengelogan terstruktur

Urutan tempat penampung, bukan namanya, menentukan parameter mana yang digunakan dalam pesan log. Misalkan Anda memiliki kode berikut:

string partitionKey = "partitionKey";
string rowKey = "rowKey";
logger.LogInformation("partitionKey={partitionKey}, rowKey={rowKey}", partitionKey, rowKey);

Jika Anda menyimpan string pesan yang sama dan membalikkan urutan parameter, teks pesan yang dihasilkan akan memiliki nilai di tempat yang salah.

Tempat penampung ditangani dengan cara ini sehingga Anda dapat melakukan pengelogan terstruktur. Application Insights menyimpan pasangan nilai nama parameter dan string pesan. Hasilnya adalah argumen pesan menjadi bidang yang bisa Anda kueri.

Jika panggilan metode pencatat Anda terlihat seperti contoh sebelumnya, Anda bisa mengkueri bidang customDimensions.prop__rowKey. Awalan prop__ ditambahkan untuk memastikan tidak ada tabrakan antara bidang yang ditambahkan runtime dengan bidang yang ditambahkan kode fungsi Anda.

Anda juga bisa membuat kueri pada string pesan asli dengan mereferensikan customDimensions.prop__{OriginalFormat} bidang.

Berikut contoh customDimensions data representasi JSON:

{
  "customDimensions": {
    "prop__{OriginalFormat}":"C# Queue trigger function processed: {message}",
    "Category":"Function",
    "LogLevel":"Information",
    "prop__message":"c9519cbf-b1e6-4b9b-bf24-cb7d10b1bb89"
  }
}

Log telemetri kustom

Ada versi SDK Application Insights khusus Functions yang dapat Anda gunakan untuk mengirim data telemetri kustom dari fungsi Anda ke Application Insights: Microsoft.Azure.WebJobs.Logging.ApplicationInsights. Gunakan perintah berikut dari perintah untuk memasang paket ini:

Perintah
PowerShell

dotnet add package Microsoft.Azure.WebJobs.Logging.ApplicationInsights --version <VERSION>

Install-Package Microsoft.Azure.WebJobs.Logging.ApplicationInsights -Version <VERSION>

Dalam perintah ini, ganti <VERSION> dengan versi paket ini yang mendukung versi Microsoft.Azure.WebJobs yang terpasang.

Contoh C# berikut menggunakan API telemetri kustom. Contohnya adalah untuk pustaka kelas .NET, tetapi kode Application Insights sama untuk skrip C#.

v4.x
v1.x

Versi 2.x dan versi yang lebih baru dari runtime menggunakan fitur yang lebih baru di Application Insights untuk secara otomatis menghubungkan telemetri dengan operasi saat ini. Tidak perlu mengatur operasi bidang Id, ParentId, atau Name secara manual.

using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;
using System.Linq;

namespace functionapp0915
{
    public class HttpTrigger2
    {
        private readonly TelemetryClient telemetryClient;

        /// Using dependency injection will guarantee that you use the same configuration for telemetry collected automatically and manually.
        public HttpTrigger2(TelemetryConfiguration telemetryConfiguration)
        {
            this.telemetryClient = new TelemetryClient(telemetryConfiguration);
        }

        [FunctionName("HttpTrigger2")]
        public Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)]
            HttpRequest req, ExecutionContext context, ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            DateTime start = DateTime.UtcNow;

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

            // Write an event to the customEvents table.
            var evt = new EventTelemetry("Function called");
            evt.Context.User.Id = name;
            this.telemetryClient.TrackEvent(evt);

            // Generate a custom metric, in this case let's use ContentLength.
            this.telemetryClient.GetMetric("contentLength").TrackValue(req.ContentLength);

            // Log a custom dependency in the dependencies table.
            var dependency = new DependencyTelemetry
            {
                Name = "GET api/planets/1/",
                Target = "swapi.co",
                Data = "https://swapi.co/api/planets/1/",
                Timestamp = start,
                Duration = DateTime.UtcNow - start,
                Success = true
            };
            dependency.Context.User.Id = name;
            this.telemetryClient.TrackDependency(dependency);

            return Task.FromResult<IActionResult>(new OkResult());
        }
    }
}

Dalam contoh ini, data metrik kustom dikumpulkan oleh host sebelum dikirim ke tabel customMetrics. Untuk mempelajari lebih lanjut, lihat dokumentasi GetMetric di Application Insights.

Saat berjalan secara lokal, Anda harus menambahkan APPINSIGHTS_INSTRUMENTATIONKEYpengaturan, dengan kunci Application Insights, ke file local.settings.json.

using System;
using System.Net;
using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Azure.WebJobs;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;
using System.Linq;

namespace functionapp0915
{
    public static class HttpTrigger2
    {
        private static string key = TelemetryConfiguration.Active.InstrumentationKey = 
            System.Environment.GetEnvironmentVariable(
                "APPINSIGHTS_INSTRUMENTATIONKEY", EnvironmentVariableTarget.Process);

        private static TelemetryClient telemetryClient = 
            new TelemetryClient() { InstrumentationKey = key };

        [FunctionName("HttpTrigger2")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
            HttpRequestMessage req, ExecutionContext context, ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            DateTime start = DateTime.UtcNow;

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

            // Get request body
            dynamic data = await req.Content.ReadAsAsync<object>();

            // Set name to query string or body data
            name = name ?? data?.name;
         
            // Track an Event
            var evt = new EventTelemetry("Function called");
            UpdateTelemetryContext(evt.Context, context, name);
            telemetryClient.TrackEvent(evt);
            
            // Track a Metric
            var metric = new MetricTelemetry("Test Metric", DateTime.Now.Millisecond);
            UpdateTelemetryContext(metric.Context, context, name);
            telemetryClient.TrackMetric(metric);
            
            // Track a Dependency
            var dependency = new DependencyTelemetry
            {
                Name = "GET api/planets/1/",
                Target = "swapi.co",
                Data = "https://swapi.co/api/planets/1/",
                Timestamp = start,
                Duration = DateTime.UtcNow - start,
                Success = true
            };
            UpdateTelemetryContext(dependency.Context, context, name);
            telemetryClient.TrackDependency(dependency);
        }
        
        // Correlate all telemetry with the current Function invocation
        private static void UpdateTelemetryContext(TelemetryContext context, ExecutionContext functionContext, string userName)
        {
            context.Operation.Id = functionContext.InvocationId.ToString();
            context.Operation.ParentId = functionContext.InvocationId.ToString();
            context.Operation.Name = functionContext.FunctionName;
            context.User.Id = userName;
        }
    }    
}

Jangan panggil TrackRequest atau StartOperation<RequestTelemetry> karena Anda akan melihat permintaan duplikat untuk pemanggilan fungsi. Runtime Functions secara otomatis melacak permintaan.

Jangan atur telemetryClient.Context.Operation.Id. Pengaturan global ini menyebabkan korelasi yang salah ketika banyak fungsi berjalan secara bersamaan. Sebagai gantinya, buat instans telemetri baru (DependencyTelemetry, EventTelemetry) dan ubah Context propertinya. Kemudian lanjutkan dalam instance telemetri ke metode yang Track sesuai pada TelemetryClient (TrackDependency(), TrackEvent(), TrackMetric()). Metode ini memastikan bahwa telemetri memiliki rincian korelasi yang benar untuk pemanggilan fungsi saat ini.

Fungsi pengujian

Artikel berikut menunjukkan cara menjalankan fungsi pustaka kelas .NET Framework C# yang berada dalam proses secara lokal untuk tujuan pengujian:

Variabel lingkungan

Untuk mendapatkan variabel lingkungan atau nilai pengaturan aplikasi, gunakan System.Environment.GetEnvironmentVariable, seperti yang ditunjukkan dalam contoh kode berikut:

public static class EnvironmentVariablesExample
{
    [FunctionName("GetEnvironmentVariables")]
    public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, ILogger log)
    {
        log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
        log.LogInformation(GetEnvironmentVariable("AzureWebJobsStorage"));
        log.LogInformation(GetEnvironmentVariable("WEBSITE_SITE_NAME"));
    }

    private static string GetEnvironmentVariable(string name)
    {
        return name + ": " +
            System.Environment.GetEnvironmentVariable(name, EnvironmentVariableTarget.Process);
    }
}

Pengaturan aplikasi dapat dibaca dari variabel lingkungan baik saat mengembangkan secara lokal maupun saat berjalan di Azure. Saat mengembangkan secara lokal, pengaturan aplikasi berasal dari Values koleksi di file local.settings.json. Di kedua lingkungan, lokal dan Azure, GetEnvironmentVariable("<app setting name>") mengambil nilai pengaturan aplikasi yang diberi nama. Misalnya, ketika Anda menjalankan secara lokal, "Nama Situs Saya" akan dikembalikan jika file local.settings.json berisi { "Values": { "WEBSITE_SITE_NAME": "My Site Name" } }.

Properti System.Configuration.ConfigurationManager.AppSettings adalah API alternatif untuk mendapatkan nilai setelan aplikasi, tetapi kami sarankan Anda gunakan GetEnvironmentVariable seperti yang ditunjukkan di sini.

Pengikatan pada runtime

Dalam bahasa C# dan .NET lainnya, Anda dapat menggunakan pola pengikatan imperatif, dibandingkan dengan pengikatan deklaratif di atribut. Pengikatan imperatif berguna ketika parameter pengikatan perlu dihitung pada runtime alih-alih waktu desain. Dengan pola ini, Anda dapat mengikat ke pengikatan input dan output yang didukung secara langsung dalam kode fungsi Anda.

Tentukan pengikatan imperatif sebagai berikut:

Jangan sertakan atribut dalam tanda tangan fungsi untuk pengikatan imperatif yang Anda inginkan.
Lewatkan dalam parameter input Binder binder atau IBinder binder.
Gunakan pola C# berikut untuk melakukan pengikatan data.
```
using (var output = await binder.BindAsync<T>(new BindingTypeAttribute(...)))
{
    ...
}
```
BindingTypeAttribute adalah atribut .NET yang mendefinisikan pengikatan Anda dan T merupakan jenis input atau output yang didukung oleh jenis pengikatan tersebut. T tidak dapat menjadi out jenis parameter (seperti out JObject). Misalnya, pengikatan output tabel Mobile Apps mendukung enam jenis output, tetapi Anda hanya dapat menggunakan ICollector<T> atau IAsyncCollector<T> dengan pengikatan imperatif.

Contoh atribut tunggal

Contoh kode berikut membuat Penyimpanan blob pengikatan output dengan jalur blob yang ditentukan pada runtime, lalu menulis string ke blob.

public static class IBinderExample
{
    [FunctionName("CreateBlobUsingBinder")]
    public static void Run(
        [QueueTrigger("myqueue-items-source-4")] string myQueueItem,
        IBinder binder,
        ILogger log)
    {
        log.LogInformation($"CreateBlobUsingBinder function processed: {myQueueItem}");
        using (var writer = binder.Bind<TextWriter>(new BlobAttribute(
                    $"samples-output/{myQueueItem}", FileAccess.Write)))
        {
            writer.Write("Hello World!");
        };
    }
}

BlobAttribute mendefinisikan pengikatan input atau output penyimpanan blob, dan TextWriter adalah jenis pengikatan output yang didukung.

Contoh beberapa atribut

Contoh sebelumnya mendapatkan pengaturan aplikasi untuk string koneksi aplikasi fungsi akun Storage utama (yaitu AzureWebJobsStorage). Anda dapat menentukan pengaturan aplikasi kustom untuk akun Storage dengan menambahkan StorageAccountAttribute dan meneruskan array atribut ke dalam BindAsync<T>(). Gunakan parameter Binder, alih-alih IBinder. Contohnya:

public static class IBinderExampleMultipleAttributes
{
    [FunctionName("CreateBlobInDifferentStorageAccount")]
    public async static Task RunAsync(
            [QueueTrigger("myqueue-items-source-binder2")] string myQueueItem,
            Binder binder,
            ILogger log)
    {
        log.LogInformation($"CreateBlobInDifferentStorageAccount function processed: {myQueueItem}");
        var attributes = new Attribute[]
        {
        new BlobAttribute($"samples-output/{myQueueItem}", FileAccess.Write),
        new StorageAccountAttribute("MyStorageAccount")
        };
        using (var writer = await binder.BindAsync<TextWriter>(attributes))
        {
            await writer.WriteAsync("Hello World!!");
        }
    }
}

Pemicu dan pengikatan

Tabel ini memperlihatkan pengikatan yang didukung di versi utama runtime Azure Functions:

Jenis	1.x¹	2.x dan lebih tinggi²	Pemicu	Input	Output
Penyimpanan Blob	✔	✔	✔	✔	✔
Azure Cosmos DB	✔	✔	✔	✔	✔
Azure Data Explorer		✔		✔	✔
Azure SQL		✔	✔	✔	✔
Dapr⁴		✔	✔	✔	✔
Event Grid	✔	✔	✔		✔
Event Hubs	✔	✔	✔		✔
HTTP & webhook	✔	✔	✔		✔
Pusat IoT	✔	✔	✔
Kafka³		✔	✔		✔
Aplikasi Seluler	✔			✔	✔
Notification Hubs	✔				✔
Antrean Penyimpanan	✔	✔	✔		✔
Redis		✔	✔
RabbitMQ³		✔	✔		✔
SendGrid	✔	✔			✔
Service Bus	✔	✔	✔		✔
SignalR		✔	✔	✔	✔
Penyimpanan Tabel	✔	✔		✔	✔
Timer	✔	✔	✔
Twilio	✔	✔			✔

¹Dukungan akan berakhir untuk runtime Azure Functions versi 1.x pada 14 September 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke versi 4.x untuk dukungan penuh.

² Dimulai dengan runtime versi 2.x, semua pengikatan kecuali HTTP dan Timer harus didaftarkan. Lihat Mendaftarkan ekstensi pengikatan.

³ Pemicu tidak didukung dalam paket Konsumsi. Memerlukan pemicu yang digerakkan oleh runtime.

⁴ Hanya didukung di Kubernetes, IoT Edge, dan mode yang dihost sendiri lainnya saja.

Langkah berikutnya

Pelajari selengkapnya tentang pemicu dan pengikatan

Pelajari selengkapnya tentang praktik terbaik untuk Azure Functions

Mengembangkan fungsi pustaka kelas C# menggunakan Azure Functions

Versi yang didukung

Proyek pustaka kelas Functions

Metode yang dikenali sebagai fungsi

Parameter tanda tangan metode

Pengikatan output

Contoh ekspresi pengikatan

Function.json otomatis

Microsoft.NET.Sdk.Functions

Versi runtime lokal

ReadyToRun

Jenis yang didukung untuk pengikatan

Pengikatan ke nilai pengembalian metode

Menulis beberapa nilai output

Asinkron

Token pembatalan

Pencatatan

ILogger

Pengelogan terstruktur

Log telemetri kustom

Fungsi pengujian

Variabel lingkungan

Pengikatan pada runtime

Contoh atribut tunggal

Contoh beberapa atribut

Pemicu dan pengikatan

Langkah berikutnya

Sumber Daya Tambahan: