Bagikan melalui

Cara menggunakan Azure WebJobs SDK untuk pemrosesan latar belakang berbasis peristiwa

  • Artikel

Artikel ini memberikan panduan tentang cara bekerja dengan Azure WebJobs SDK. Untuk segera memulai dengan WebJobs, lihat Memulai dengan Azure WebJobs SDK.

Versi SDK WebJobs

Berikut adalah perbedaan utama antara versi 3.x dan versi 2.x WebJobs SDK:

  • Versi 3.x menambahkan dukungan untuk .NET Core.
  • Di versi 3.x, Anda perlu memasang ekstensi pengikatan Storage yang diperlukan oleh WebJobs SDK. Di versi 2.x, pengikatan Storage disertakan dalam SDK.
  • Alat Visual Studio 2019 untuk proyek .NET Core (3.x) berbeda dengan alat untuk proyek .NET Framework (2.x). Untuk mempelajari lebih lanjut, lihat Mengembangkan dan menyebarkan WebJobs menggunakan Visual Studio - Azure App Service.

Beberapa deskripsi dalam artikel ini memberikan contoh untuk kedua WebJobs versi 3. xdan WebJobs versi 2. x.

Azure Functions dibangun pada WebJobs SDK.

  • Azure Functions version 2. x dibangun di WebJobs SDK versi 3. x.
  • Azure Functions version 1.x dibangun di WebJobs SDK versi 2.x.

Repositori kode sumber untuk Azure Functions dan WebJobs SDK menggunakan penomoran SDK WebJobs. Beberapa bagian dari artikel panduan ini menautkan ke dokumentasi Azure Functions.

Untuk informasi selengkapnya, lihat Membandingkan SDK WebJobs dan Azure Functions

Host WebJobs

Host adalah wadah runtime untuk fungsi. Host mendengarkan fungsi pemicu dan panggilan. Dalam versi 3.x, host adalah implementasi dari IHost. Di versi 2.x, Anda menggunakan objek JobHost. Anda membuat instans host dalam kode Anda dan menulis kode untuk menyesuaikan perilakunya.

Ini adalah perbedaan utama antara menggunakan WebJobs SDK secara langsung dan menggunakannya secara tidak langsung melalui Azure Functions. Di Azure Functions, layanan mengontrol host, dan Anda tidak dapat mengkustomisasi host dengan menulis kode. Azure Functions memungkinkan Anda menyesuaikan perilaku host melalui pengaturan di file host.json. Setelan tersebut adalah untai, bukan kode, dan penggunaan untai ini membatasi jenis penyesuaian yang dapat Anda lakukan.

Koneksi host

WebJobs SDK mencari koneksi Azure Storage dan Azure Bus Layanan dalam file local.settings.json saat Anda menjalankan secara lokal atau di lingkungan WebJob saat Anda menjalankan di Azure. Secara default, WebJobs SDK memerlukan koneksi penyimpanan dengan nama AzureWebJobsStorage.

Saat nama koneksi menetapkan satu nilai yang pasti, runtime mengidentifikasi nilai sebagai string koneksi, yang biasanya menyertakan rahasia. Detail string koneksi bergantung pada layanan yang Anda sambungkan. Namun, nama koneksi juga dapat merujuk ke kumpulan beberapa item konfigurasi, berguna untuk mengonfigurasi koneksi berbasis-identitas. Variabel lingkungan dapat dianggap sebagai satu kesatuan dengan menggunakan prefiks bersama yang diakhiri dengan garis bawah ganda __. Grup tersebut kemudian dapat dirujuk dengan mengatur nama koneksi ke prefiks ini.

Misalnya, connection properti untuk definisi pemicu Azure Blob mungkin .Storage1 Selama tidak ada nilai string tunggal yang dikonfigurasi oleh variabel lingkungan bernama Storage1, variabel lingkungan bernama Storage1__blobServiceUri dapat digunakan untuk menginformasikan blobServiceUri properti koneksi. Properti koneksi berbeda-beda untuk setiap layanan. Lihat dokumentasi untuk komponen yang menggunakan koneksi.

Koneksi berbasis identitas

Untuk menggunakan koneksi berbasis identitas di WebJobs SDK, pastikan Anda menggunakan versi terbaru paket WebJobs dalam proyek Anda. Anda juga harus memastikan Anda memiliki referensi ke Microsoft.Azure.WebJobs.Host.Storage. Berikut ini adalah contoh seperti apa file proyek Anda setelah membuat pembaruan ini:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>
    <IsWebJobProject>true</IsWebJobProject>
    <WebJobName>$(AssemblyName)</WebJobName>
    <WebJobType>Continuous</WebJobType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs" Version="3.0.41" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.Storage.Queues" Version="5.3.1" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Host.Storage" Version="5.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="2.1.1" />
  </ItemGroup>

  <ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

Saat menyiapkan WebJobs dalam HostBuilder Anda, pastikan untuk menyertakan panggilan ke AddAzureStorageCoreServices, karena inilah yang memungkinkan AzureWebJobsStorage dan pemicu dan pengikatan Penyimpanan lainnya untuk menggunakan identitas:

    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        // other configurations...
    });

Kemudian, Anda dapat mengonfigurasi AzureWebJobsStorage koneksi dengan mengatur variabel lingkungan (atau Pengaturan Aplikasi saat dihosting di App Service):

Variabel lingkungan Deskripsi Contoh nilai
AzureWebJobsStorage__blobServiceUri URI data plane dari layanan blob akun penyimpanan, menggunakan skema HTTPS. https://<storage_account_name>.blob.core.windows.net
AzureWebJobsStorage__queueServiceUri URI data plane dari layanan antrean akun penyimpanan, menggunakan skema HTTPS. https://<storage_account_name>.queue.core.windows.net

Jika Anda menyediakan konfigurasi melalui cara apa pun selain variabel lingkungan, seperti dengan appsettings.json, Anda harus menyediakan konfigurasi terstruktur untuk koneksi dan propertinya:

{
    "AzureWebJobsStorage": {
        "blobServiceUri": "https://<storage_account_name>.blob.core.windows.net",
        "queueServiceUri": "https://<storage_account_name>.queue.core.windows.net"
    }
}

Anda dapat menghilangkan queueServiceUri properti jika Anda tidak berencana untuk menggunakan pemicu blob.

Saat kode Anda dijalankan secara lokal, ini akan default untuk menggunakan identitas pengembang Anda sesuai perilaku yang dijelaskan untuk DefaultAzureCredential.

Saat kode Anda dihosting di Azure App Service, konfigurasi yang ditunjukkan di atas akan default ke identitas terkelola yang ditetapkan sistem untuk sumber daya. Untuk menggunakan identitas yang ditetapkan pengguna yang telah ditetapkan ke aplikasi, Anda perlu menambahkan properti tambahan untuk koneksi Anda yang menentukan identitas mana yang harus digunakan. Properti credential (AzureWebJobsStorage__credential sebagai variabel lingkungan) harus diatur ke string "managedidentity". Properti clientId (AzureWebJobsStorage__clientId sebagai variabel lingkungan) harus diatur ke ID klien identitas terkelola yang ditetapkan pengguna untuk digunakan. Sebagai konfigurasi terstruktur, objek lengkapnya adalah:

{
    "AzureWebJobsStorage": {
        "blobServiceUri": "https://<storage_account_name>.blob.core.windows.net",
        "queueServiceUri": "https://<storage_account_name>.queue.core.windows.net",
        "credential": "managedidentity",
        "clientId": "<user-assigned-identity-client-id>"
    }
}

Identitas yang digunakan untuk AzureWebJobsStorage harus memiliki penetapan peran yang memberinya peran Pemilik Data Blob Penyimpanan, Kontributor Data Antrean Penyimpanan, dan Kontributor Akun Penyimpanan. Anda dapat menghilangkan Kontributor Data Antrean Penyimpanan dan Kontributor Akun Penyimpanan jika Anda tidak berencana untuk menggunakan pemicu blob.

Tabel berikut ini memperlihatkan peran bawaan yang direkomendasikan saat menggunakan pemicu dalam pengikatan dalam operasi normal. Aplikasi Anda mungkin memerlukan izin lebih lanjut berdasarkan kode yang Anda tulis.

Pengikatan Peran bawaan contoh
Pemicu blob Pemilik Data Blob Penyimpanan dan Kontributor Data Antrean Penyimpanan
Lihat di atas untuk persyaratan AzureWebJobsStorage juga.
Blob (input) Pembaca Data Blob Penyimpanan.
Blob (output) Pemilik Data Blob Penyimpanan
Pemicu antrean Pembaca Data Antrean Penyimpanan, Pemroses Pesan Data Antrean Penyimpanan
Antrean (output) Kontributor Data Antrean Penyimpanan, Pengirim Pesan Data Antrean Penyimpanan
pemicuBus Layanan 1 Penerima Data Azure Service Bus, Pemilik Data Azure Service Bus
Bus Layanan (output) Azure Service Bus Data Sender

1 Untuk memicu dari topik Bus Layanan, penetapan peran harus memiliki cakupan yang efektif atas sumber daya langganan Bus Layanan. Jika hanya topik yang disertakan, kesalahan akan terjadi. Beberapa klien, seperti portal Azure, tidak mengekspos sumber daya langganan Bus Layanan sebagai cakupan untuk penetapan peran. Dalam kasus seperti itu, Azure CLI dapat digunakan sebagai gantinya. Untuk mempelajari selengkapnya, lihat Peran bawaan Azure untuk Azure Service Bus.

String koneksi dalam versi 2.x

Versi 2.x SDK tidak memerlukan nama yang spesifik. Versi 2.x SDK memungkinkan Anda menggunakan nama Anda sendiri untuk string koneksi ini dan memungkinkan Anda untuk menyimpannya di tempat lain. Anda dapat mengatur nama dalam kode menggunakan JobHostConfiguration, seperti ini:

static void Main(string[] args)
{
    var _storageConn = ConfigurationManager
        .ConnectionStrings["MyStorageConnection"].ConnectionString;

    //// Dashboard logging is deprecated; use Application Insights.
    //var _dashboardConn = ConfigurationManager
    //    .ConnectionStrings["MyDashboardConnection"].ConnectionString;

    JobHostConfiguration config = new JobHostConfiguration();
    config.StorageConnectionString = _storageConn;
    //config.DashboardConnectionString = _dashboardConn;
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

Catatan

Karena versi 3.x menggunakan API konfigurasi .NET Core default, tidak ada API untuk mengubah nama string koneksi. Lihat Mengembangkan dan menyebarkan WebJobs menggunakan Visual Studio

Pengaturan pengembangan host

Anda dapat menjalankan host dalam mode pengembangan untuk membuat pengembangan lokal lebih efisien. Berikut adalah beberapa setelan yang berubah secara otomatis ketika Anda menjalankan dalam mode pengembangan:

Properti Pengaturan pengembangan
Tracing.ConsoleLevel TraceLevel.Verbose untuk memaksimalkan output log.
Queues.MaxPollingInterval Nilai rendah untuk memastikan metode antrean terpicu secara instan.
Singleton.ListenerLockPeriod 15 detik untuk membantu pengembangan berulang yang cepat.

Proses untuk mengaktifkan mode pengembangan bergantung pada versi SDK.

Versi 3.x

Versi 3.x menggunakan API Inti ASP.NET standar. Panggil metode UseEnvironment pada instans HostBuilder. Berikan untai bernama development, seperti dalam contoh ini:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment("development");
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Versi 2.x

Kelas JobHostConfiguration memiliki metode UseDevelopmentSettings yang mengaktifkan mode pengembangan. Contoh berikut menunjukkan cara menggunakan pengaturan pengembangan. Untuk membuat config.IsDevelopment kembali true saat dijalankan secara lokal, setel variabel lingkungan lokal bernama AzureWebJobsEnv dengan nilai Development.

static void Main()
{
    config = new JobHostConfiguration();

    if (config.IsDevelopment)
    {
        config.UseDevelopmentSettings();
    }

    var host = new JobHost(config);
    host.RunAndBlock();
}

Mengelola koneksi bersamaan (versi 2.x)

Di versi 3.x, batas sambungan default adalah sambungan tak terbatas. Jika karena alasan tertentu Anda perlu mengubah batas ini, Anda dapat menggunakan properti MaxConnectionsPerServer dari kelas WinHttpHandler.

Di versi 2.x, Anda mengontrol jumlah sambungan konkuren ke host dengan menggunakan ServicePointManager.DefaultConnectionLimit API. Di 2.x, Anda harus meningkatkan nilai ini dari default 2 sebelum memulai host WebJobs Anda.

Semua permintaan HTTP keluar yang Anda buat dari suatu fungsi dengan menggunakan HttpClient mengalir melalui ServicePointManager. Setelah Anda mencapai nilai yang ditetapkan di DefaultConnectionLimit, ServicePointManager mulai mengantrekan permintaan sebelum mengirimnya. Misalkan DefaultConnectionLimit Anda diatur ke 2 dan kode Anda membuat 1.000 permintaan HTTP. Awalnya, hanya dua permintaan yang diizinkan melalui OS. 998 lainnya diantrekan hingga ada ruang untuk mereka. Itu berarti HttpClient Anda mungkin kehabisan waktu karena tampaknya telah membuat permintaan, tetapi permintaan tersebut tidak pernah dikirim oleh OS ke server tujuan. Jadi, Anda mungkin melihat perilaku yang tampaknya tidak masuk akal: HttpClient lokal Anda membutuhkan waktu 10 detik untuk menyelesaikan permintaan, tetapi layanan Anda mengembalikan setiap permintaan dalam 200 md.

Nilai default untuk aplikasi ASP.NET adalah Int32.MaxValue, dan kemungkinan besar akan berfungsi dengan baik untuk WebJobs yang berjalan dalam Paket App Service Dasar atau yang lebih tinggi. WebJobs biasanya memerlukan setelan Grup Ketersediaan AlwaysOn, dan itu hanya didukung oleh App Service Plan Dasar dan yang lebih tinggi.

Jika WebJob Anda berjalan dalam Paket App Service Gratis atau Bersama, aplikasi Anda dibatasi oleh kotak pasir App Service, yang saat ini memiliki batas sambungan 300. Dengan batas sambungan tidak terikat di ServicePointManager, kemungkinan besar ambang sambungan kotak pasir akan tercapai dan situs akan ditutup. Dalam hal ini, menyetel DefaultConnectionLimit ke sesuatu yang lebih rendah, seperti 50 atau 100, dapat mencegah hal ini terjadi dan tetap memungkinkan throughput yang memadai.

Pengaturan harus dikonfigurasi sebelum permintaan HTTP dibuat. Untuk alasan ini, host WebJobs tidak harus menyesuaikan pengaturan secara otomatis. Mungkin ada permintaan HTTP yang terjadi sebelum host dimulai, yang dapat menyebabkan perilaku tidak terduga. Pendekatan terbaik adalah menyetel nilai segera dalam metode Main Anda sebelum menginisialisasi JobHost, seperti yang ditunjukkan di sini:

static void Main(string[] args)
{
    // Set this immediately so that it's used by all requests.
    ServicePointManager.DefaultConnectionLimit = Int32.MaxValue;

    var host = new JobHost();
    host.RunAndBlock();
}

Pemicu

WebJobs SDK mendukung set pemicu dan pengikatan yang sama yang digunakan oleh Azure Functions. Harap dicatat bahwa di SDK WebJobs, pemicunya spesifik fungsi dan tidak terkait dengan jenis penyebaran WebJob. WebJob dengan fungsi yang dipicu peristiwa yang dibuat menggunakan SDK harus selalu dipublikasikan sebagai WebJob berkelanjutan, dengan Grup Ketersediaan Always on diaktifkan.

Fungsi harus metode publik dan harus memiliki satu atribut pemicu atau atribut NoAutomaticTrigger.

Pemicu otomatis

Pemicu otomatis memanggil fungsi sebagai respons terhadap suatu peristiwa. Pertimbangkan contoh fungsi ini yang dipicu oleh pesan yang ditambahkan ke penyimpanan Azure Queue. Fungsi merespons dengan membaca blob dari penyimpanan Azure Blob:

public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

Atribut QueueTrigger memberi tahu waktu proses untuk memanggil fungsi setiap kali pesan antrean muncul di antrean myqueue-items. Atribut Blob memberi tahu waktu proses untuk menggunakan pesan antrean untuk membaca blob di kontainer sample-workitems. Nama item blob dalam kontainer samples-workitems diperoleh langsung dari pemicu antrean sebagai ekspresi pengikatan ({queueTrigger}).

Catatan

Sebuah aplikasi web dapat mengalami waktu habis setelah 20 menit tidak aktif, dan hanya permintaan ke aplikasi web yang sebenarnya dapat mengatur ulang timer. Melihat konfigurasi aplikasi di portal Microsoft Azure atau membuat permintaan ke situs alat lanjutan (https://<app_name>.scm.azurewebsites.net) tidak mengatur ulang timer. Jika Anda menyetel aplikasi web yang meng-host pekerjaan Anda untuk terus berjalan, berjalan sesuai jadwal, atau menggunakan pemicu berdasarkan peristiwa, aktifkan setelan Selalu aktif di laman Konfigurasi Azure aplikasi web Anda. Pengaturan Selalu aktif membantu memastikan bahwa Jenis WebJobs ini berjalan dengan andal. Fitur ini hanya tersedia di tingkat harga Dasar, Standar, dan Premium.

Pemicu manual

Untuk memicu fungsi secara manual, gunakan atribut NoAutomaticTrigger, seperti yang ditunjukkan di sini:

[NoAutomaticTrigger]
public static void CreateQueueMessage(
ILogger logger,
string value,
[Queue("outputqueue")] out string message)
{
    message = value;
    logger.LogInformation("Creating queue message: ", message);
}

Proses untuk memicu fungsi secara manual bergantung pada versi SDK.

Versi 3.x

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorage();
    });
    var host = builder.Build();
    using (host)
    {
        var jobHost = host.Services.GetService(typeof(IJobHost)) as JobHost;
        var inputs = new Dictionary<string, object>
        {
            { "value", "Hello world!" }
        };

        await host.StartAsync();
        await jobHost.CallAsync("CreateQueueMessage", inputs);
        await host.StopAsync();
    }
}

Versi 2.x

static void Main(string[] args)
{
    JobHost host = new JobHost();
    host.Call(typeof(Program).GetMethod("CreateQueueMessage"), new { value = "Hello world!" });
}

Pengikatan input dan output

Binding input menyediakan cara deklaratif untuk membuat data dari Azure atau layanan pihak ketiga tersedia untuk kode Anda. Pengikatan output menyediakan cara untuk memperbarui data. Artikel Memulai menunjukkan masing-masing contoh.

Anda dapat menggunakan nilai pengembalian metode untuk pengikatan output, dengan menerapkan atribut ke nilai pengembalian metode. Lihat contoh dalam Menggunakan nilai pengembalian Fungsi Azure.

Jenis pengikatan

Proses untuk memasang dan mengelola jenis penjilidan bergantung pada apakah Anda menggunakan SDK versi 3.x atau versi 2.x. Anda dapat menemukan paket yang akan dipasang untuk jenis penjilidan tertentu di bagian "Paket" dari artikel referensi Azure Functions dari jenis pengikatan tersebut. Pengecualian adalah pemicu dan pengikatan File (untuk sistem file lokal), yang tidak didukung oleh Azure Functions.

Versi 3.x

Di versi 3.x, pengikatan penyimpanan disertakan dalam paket Microsoft.Azure.WebJobs.Extensions.Storage. Panggil metode ekstensi AddAzureStorage dalam metode ConfigureWebJobs, seperti yang ditunjukkan di sini:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddAzureStorage();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk menggunakan jenis pemicu dan pengikatan lain, pasang paket NuGet yang berisi mereka dan panggil metode ekstensi Add<binding> yang diterapkan di ekstensi. Misalnya, jika Anda ingin menggunakan pengikatan Azure Cosmos DB, pasang Microsoft.Azure.WebJobs.Extensions.CosmosDB dan panggil AddCosmosDB, seperti ini:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddCosmosDB();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk menggunakan pemicu Timer atau pengikatan File, yang merupakan bagian dari layanan inti, panggil masing-masing metode ekstensi AddTimers atau AddFiles.

Versi 2.x

Jenis pemicu dan pengikatan ini disertakan dalam versi 2.x paket Microsoft.Azure.WebJobs:

  • Penyimpanan Blob
  • Antrean Penyimpanan
  • Penyimpanan Tabel

Untuk menggunakan jenis pemicu dan pengikatan lainnya, pasang paket NuGet yang berisi mereka dan panggil metode Use<binding> pada objek JobHostConfiguration. Misalnya, jika Anda ingin menggunakan pemicu Timer, pasang Microsoft.Azure.WebJobs.Extensions dan panggil UseTimers dalam metode Main, seperti yang ditunjukkan di sini:

static void Main()
{
    config = new JobHostConfiguration();
    config.UseTimers();
    var host = new JobHost(config);
    host.RunAndBlock();
}

Untuk menggunakan pengikatan File, pasang Microsoft.Azure.WebJobs.Extensions dan panggil UseFiles.

ExecutionContext

WebJobs memungkinkan Anda mengikat ke ExecutionContext. Dengan pengikatan ini, Anda dapat mengakses ExecutionContext sebagai parameter di tanda tangan fungsi Anda. Misalnya, kode berikut menggunakan objek konteks untuk mengakses ID pemanggilan, yang dapat Anda gunakan untuk menyambungkan semua log yang dihasilkan oleh pemanggilan fungsi tertentu.

public class Functions
{
    public static void ProcessQueueMessage([QueueTrigger("queue")] string message,
        ExecutionContext executionContext,
        ILogger logger)
    {
        logger.LogInformation($"{message}\n{executionContext.InvocationId}");
    }
}

Proses pengikatan ke ExecutionContext bergantung pada versi SDK Anda.

Versi 3.x

Panggil metode ekstensi AddExecutionContextBinding dalam metode ConfigureWebJobs, seperti yang ditunjukkan di sini:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddExecutionContextBinding();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Versi 2.x

Paket Microsoft.Azure.WebJobs.Extensions yang disebutkan sebelumnya juga menyediakan jenis pengikatan khusus yang dapat Anda daftarkan dengan memanggil metode UseCore. Pengikatan ini memungkinkan Anda menentukan parameter ExecutionContext di tanda tangan fungsi Anda, yang diaktifkan seperti ini:

class Program
{
    static void Main()
    {
        config = new JobHostConfiguration();
        config.UseCore();
        var host = new JobHost(config);
        host.RunAndBlock();
    }
}

Konfigurasi pengikatan

Anda dapat mengonfigurasi perilaku beberapa pemicu dan pengikatan. Proses untuk mengonfigurasinya bergantung pada versi SDK.

  • Versi 3.x: Setel konfigurasi saat metode Add<Binding> dipanggil di ConfigureWebJobs.
  • Versi 2.x: Setel konfigurasi dengan menyetel properti di objek konfigurasi yang Anda berikan ke JobHost.

Pengaturan khusus pengikatan ini setara dengan pengaturan di file proyek host.json di Azure Functions.

Anda dapat mengonfigurasi pengikatan berikut:

Konfigurasi pemicu Azure Cosmos DB (versi 3.x)

Contoh ini memperlihatkan cara mengonfigurasi pemicu Azure Cosmos DB:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddCosmosDB(a =>
        {
            a.ConnectionMode = ConnectionMode.Gateway;
            a.Protocol = Protocol.Https;
            a.LeaseOptions.LeasePrefix = "prefix1";

        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk informasi selengkapnya, lihat artikel pengikatan Azure Cosmos DB.

Konfigurasi pemicu Azure Event Hubs (versi 3.x)

Contoh ini menunjukkan cara mengonfigurasi pemicu Azure Event Hubs:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddEventHubs(a =>
        {
            a.BatchCheckpointFrequency = 5;
            a.EventProcessorOptions.MaxBatchSize = 256;
            a.EventProcessorOptions.PrefetchCount = 512;
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk informasi selengkapnya, lihat artikel pengikatan Azure Event Hubs.

Konfigurasi pemicu penyimpanan antrean

Contoh berikut menunjukkan cara mengonfigurasi pemicu penyimpanan Antrean.

Versi 3.x

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorage(a => {
            a.BatchSize = 8;
            a.NewBatchThreshold = 4;
            a.MaxDequeueCount = 4;
            a.MaxPollingInterval = TimeSpan.FromSeconds(15);
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk detail selengkapnya, lihat artikel pengikatan penyimpanan Antrean.

Versi 2.x

static void Main(string[] args)
{
    JobHostConfiguration config = new JobHostConfiguration();
    config.Queues.BatchSize = 8;
    config.Queues.NewBatchThreshold = 4;
    config.Queues.MaxDequeueCount = 4;
    config.Queues.MaxPollingInterval = TimeSpan.FromSeconds(15);
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

Untuk informasi selengkapnya, lihat referensi host.json v1.x.

Konfigurasi pengikatan SendGrid (versi 3.x)

Contoh ini menunjukkan cara mengonfigurasi pengikatan output SendGrid:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddSendGrid(a =>
        {
            a.FromAddress.Email = "samples@functions.com";
            a.FromAddress.Name = "Azure Functions";
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk informasi selengkapnya, lihat artikel pengikatan SendGrid.

Konfigurasi pemicu Bus Layanan (versi 3.x)

Contoh ini menunjukkan cara mengonfigurasi pemicu Azure Service Bus:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddServiceBus(sbOptions =>
        {
            sbOptions.MessageHandlerOptions.AutoComplete = true;
            sbOptions.MessageHandlerOptions.MaxConcurrentCalls = 16;
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Untuk detail selengkapnya, lihat artikel Pengikatan Azure Service Bus.

Konfigurasi untuk pengikatan lain

Beberapa jenis pemicu dan pengikatan menentukan jenis konfigurasi khusus mereka sendiri. Misalnya, pemicu File memungkinkan Anda menentukan jalur root untuk memantau, seperti dalam contoh berikut.

Versi 3.x

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddFiles(a => a.RootPath = @"c:\data\import");
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Versi 2.x

static void Main()
{
    config = new JobHostConfiguration();
    var filesConfig = new FilesConfiguration
    {
        RootPath = @"c:\data\import"
    };
    config.UseFiles(filesConfig);
    var host = new JobHost(config);
    host.RunAndBlock();
}

Ekspresi pengikatan

Dalam parameter konstruktor atribut, Anda dapat menggunakan ekspresi yang menyelesaikan ke nilai dari berbagai sumber. Misalnya, dalam kode berikut, jalur untuk atribut BlobTrigger membuat ekspresi bernama filename. Saat digunakan untuk pengikatan output, filename diselesaikan dengan nama blob pemicu.

public static void CreateThumbnail(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger logger)
{
    logger.Info($"Blob trigger processing: {filename}");
    // ...
}

Untuk informasi selengkapnya tentang mengikat ekspresi, lihat Mengikat ekspresi dan pola dalam dokumentasi Azure Functions.

Ekspresi pengikatan khusus

Terkadang Anda ingin menentukan nama antrean, nama blob atau kontainer, atau nama tabel dalam kode daripada mengodekannya secara permanen. Misalnya, Anda mungkin ingin menentukan nama antrean untuk atribut QueueTrigger dalam file konfigurasi atau variabel lingkungan.

Anda dapat melakukannya dengan meneruskan pemecah masalah nama kustom selama konfigurasi. Anda menyertakan tempat penampung dalam parameter konstruktor atribut pemicu atau pengikatan, dan kode resolver Anda menyediakan nilai aktual yang akan digunakan sebagai pengganti tempat penampung tersebut. Anda mengidentifikasi placeholder dengan mengelilinginya dengan tanda persen (%), seperti yang ditunjukkan di sini:

public static void WriteLog([QueueTrigger("%logqueue%")] string logMessage)
{
    Console.WriteLine(logMessage);
}

Kode ini memungkinkan Anda menggunakan antrean bernama logqueuetest di lingkungan pengujian dan antrean bernama logqueueprod dalam produksi. Alih-alih nama antrean dikodekan secara permanen, Anda menentukan nama entri dalam koleksi appSettings.

Ada pemecah masalah default yang berlaku jika Anda tidak menyediakan penyelesai kustom. Defaultnya mendapatkan nilai dari pengaturan aplikasi atau variabel lingkungan.

Mulai dari .NET Core 3.1, yang ConfigurationManager Anda gunakan memerlukan paket NuGet System.Configuration.ConfigurationManager. Sampel memerlukan pernyataan berikut using :

using System.Configuration;

Kelas Anda NameResolver mendapatkan nama antrean dari pengaturan aplikasi, seperti yang ditunjukkan di sini:

public class CustomNameResolver : INameResolver
{
    public string Resolve(string name)
    {
        return ConfigurationManager.AppSettings[name].ToString();
    }
}

Versi 3.x

Anda mengkonfigurasi penyelesai konflik dengan menggunakan injeksi ketergantungan. Contoh ini memerlukan pernyataan using berikut:

using Microsoft.Extensions.DependencyInjection;

Anda menambahkan penyelesai dengan memanggil metode ekstensi ConfigureServices di HostBuilder, seperti dalam contoh ini:

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    var resolver = new CustomNameResolver();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureServices(s => s.AddSingleton<INameResolver>(resolver));
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Versi 2.x

Teruskan kelas NameResolver Anda ke objek JobHost, seperti yang ditunjukkan di sini:

 static void Main(string[] args)
{
    JobHostConfiguration config = new JobHostConfiguration();
    config.NameResolver = new CustomNameResolver();
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

Azure Functions mengimplementasikan INameResolver untuk mendapatkan nilai dari pengaturan aplikasi, seperti yang ditunjukkan pada contoh. Saat Anda menggunakan WebJobs SDK secara langsung, Anda dapat menulis implementasi khusus yang mendapatkan nilai pengganti tempat penampung dari sumber apa pun yang Anda inginkan.

Pengikatan pada runtime

Jika Anda perlu melakukan beberapa pekerjaan dalam fungsi Anda sebelum menggunakan atribut pengikatan seperti Queue, Blob, atau Table, Anda dapat menggunakan antarmuka IBinder.

Contoh berikut mengambil pesan antrean input dan membuat pesan baru dengan konten yang sama dalam antrean output. Nama antrian keluaran diatur oleh kode di badan fungsi.

public static void CreateQueueMessage(
    [QueueTrigger("inputqueue")] string queueMessage,
    IBinder binder)
{
    string outputQueueName = "outputqueue" + DateTime.Now.Month.ToString();
    QueueAttribute queueAttribute = new QueueAttribute(outputQueueName);
    CloudQueue outputQueue = binder.Bind<CloudQueue>(queueAttribute);
    outputQueue.AddMessageAsync(new CloudQueueMessage(queueMessage));
}

Untuk informasi selengkapnya, lihat Mengikat saat runtime dalam dokumentasi Azure Functions.

Informasi referensi yang pengikatan

Dokumentasi Azure Functions menyediakan informasi referensi tentang setiap jenis pengikatan. Anda akan menemukan informasi berikut di setiap artikel referensi pengikatan. (Contoh ini didasarkan pada antrian Storage.)

  • Paket. Paket yang perlu Anda pasang untuk menyertakan dukungan untuk pengikatan dalam proyek WebJobs SDK.
  • Contoh. Sampel kode. Contoh pustaka kelas C# berlaku untuk WebJobs SDK. Abaikan saja atribut FunctionName.
  • Atribut. Atribut yang akan digunakan untuk jenis pengikatan.
  • Konfigurasi. Penjelasan tentang properti atribut dan parameter konstruktor.
  • Penggunaan. Jenis yang dapat Anda ikat dan informasi tentang cara kerja pengikatan. Misalnya: algoritme pengumpulan, pemrosesan antrean racun.

Catatan

Pengikatan HTTP, Webhooks, dan Event Grid hanya didukung oleh Azure Functions, bukan oleh WebJobs SDK.

Untuk daftar lengkap pengikatan yang didukung dalam runtime bahasa umum Azure Functions, lihat pengikatan yang Didukung.

Atribut untuk Nonaktifkan, Timeout, dan Database tunggal

Dengan atribut ini, Anda dapat mengontrol pemicu fungsi, membatalkan fungsi, dan memastikan bahwa hanya satu instans fungsi yang berjalan.

Menonaktifkan atribut

Atribut Disable memungkinkan Anda mengontrol apakah suatu fungsi dapat dipicu.

Dalam contoh berikut, jika pengaturan aplikasi Disable_TestJob memiliki nilai 1 atau True (tidak sensitif huruf besar/kecil), fungsi tidak akan berjalan. Dalam hal ini, runtime membuat pesan log Function 'Functions.TestJob' dinonaktifkan.

[Disable("Disable_TestJob")]
public static void TestJob([QueueTrigger("testqueue2")] string message)
{
    Console.WriteLine("Function with Disable attribute executed!");
}

Saat Anda mengubah nilai pengaturan aplikasi di portal Azure, WebJob dimulai ulang untuk mengambil pengaturan baru.

Atribut dapat dideklarasikan pada parameter, metode, atau tingkat kelas. Nama pengaturan juga dapat berisi ekspresi pengikatan.

Batas waktu atribut

Atribut Timeout menyebabkan suatu fungsi dibatalkan jika tidak selesai dalam jangka waktu tertentu. Dalam contoh berikut, fungsi akan berjalan selama satu hari tanpa atribut Batas Waktu. Batas waktu menyebabkan fungsi dibatalkan setelah 15 detik. Ketika parameter "throwOnError" atribut Timeout diatur ke "true", pemanggilan fungsi dihentikan dengan memiliki pengecualian yang dilemparkan oleh webjobs SDK ketika interval batas waktu terlampaui. Nilai default "throwOnError" adalah "false". Ketika atribut Timeout digunakan, perilaku default membatalkan pemanggilan fungsi dengan mengatur token pembatalan sambil memungkinkan pemanggilan berjalan tanpa batas waktu sampai kode fungsi kembali atau diberikan pengecualian.

[Timeout("00:00:15")]
public static async Task TimeoutJob(
    [QueueTrigger("testqueue2")] string message,
    CancellationToken token,
    TextWriter log)
{
    await log.WriteLineAsync("Job starting");
    await Task.Delay(TimeSpan.FromDays(1), token);
    await log.WriteLineAsync("Job completed");
}

Anda dapat menerapkan atribut Batas Waktu di tingkat kelas atau metode, dan Anda dapat menentukan batas waktu global dengan menggunakan JobHostConfiguration.FunctionTimeout. Batas waktu tingkat kelas atau tingkat metode menggantikan batas waktu global.

Atribut Singleton

Atribut Singleton memastikan bahwa hanya satu fungsi yang berjalan, meskipun ada beberapa aplikasi web host. Atribut Database tunggal menggunakan penguncian terdistribusi untuk memastikan bahwa satu instans berjalan.

Dalam contoh ini, hanya satu contoh fungsi ProcessImage yang berjalan pada waktu tertentu:

[Singleton]
public static async Task ProcessImage([BlobTrigger("images")] Stream image)
{
     // Process the image.
}

SingletonMode.Listener

Beberapa pemicu memiliki dukungan bawaan untuk manajemen konkurensi:

  • QueueTrigger. Atur JobHostConfiguration.Queues.BatchSize ke 1.
  • ServiceBusTrigger. Atur ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls ke 1.
  • FileTrigger. Atur FileProcessor.MaxDegreeOfParallelism ke 1.

Anda dapat menggunakan pengaturan ini untuk memastikan bahwa fungsi Anda berjalan sebagai singleton pada satu instans. Untuk memastikan bahwa hanya satu instans fungsi yang berjalan saat aplikasi web diskalakan ke beberapa instans, terapkan kunci tunggal tingkat listener pada fungsi ([Singleton(Mode = SingletonMode.Listener)]). Kunci listener diperoleh saat JobHost dimulai. Jika tiga instans yang diskalakan semuanya dimulai pada waktu yang sama, hanya satu instans yang memperoleh kunci dan hanya satu listener yang memulai.

Catatan

Lihat Repo GitHub ini untuk mempelajari lebih lanjut tentang cara kerja SingletonMode.Function.

Nilai cakupan

Anda dapat menentukan ekspresi cakupan/nilai pada satu orang. Ekspresi/nilai memastikan bahwa semua eksekusi fungsi pada cakupan tertentu akan diserialisasi. Menerapkan penguncian yang lebih terperinci dengan cara ini dapat memungkinkan beberapa tingkat paralelisme untuk fungsi Anda sambil membuat tahapan pemanggilan lain seperti yang ditentukan oleh kebutuhan Anda. Misalnya, dalam kode berikut, ekspresi cakupan mengikat nilai Region dari pesan masuk. Saat antrean berisi tiga pesan pada wilayah Timur, Timur, dan Barat, pesan yang memiliki wilayah Timur berjalan secara serial. Pesan dengan wilayah Barat dijalankan secara paralel dengan yang ada di wilayah Timur.

[Singleton("{Region}")]
public static async Task ProcessWorkItem([QueueTrigger("workitems")] WorkItem workItem)
{
     // Process the work item.
}

public class WorkItem
{
     public int ID { get; set; }
     public string Region { get; set; }
     public int Category { get; set; }
     public string Description { get; set; }
}

SingletonScope.Host

Cakupan default untuk kunci adalah SingletonScope.Function, artinya cakupan kunci (jalur sewa blob) terkait dengan nama fungsi yang sepenuhnya memenuhi syarat. Untuk mengunci seluruh fungsi, tentukan SingletonScope.Host dan gunakan nama ID cakupan yang sama di semua fungsi yang tidak ingin Anda jalankan secara bersamaan. Dalam contoh berikut, hanya satu contoh AddItem atau RemoveItem yang berjalan pada satu waktu:

[Singleton("ItemsLock", SingletonScope.Host)]
public static void AddItem([QueueTrigger("add-item")] string message)
{
     // Perform the add operation.
}

[Singleton("ItemsLock", SingletonScope.Host)]
public static void RemoveItem([QueueTrigger("remove-item")] string message)
{
     // Perform the remove operation.
}

Melihat blob sewa

WebJobs SDK menggunakan sewa blob Azure untuk menerapkan penguncian terdistribusi. Blob sewa yang digunakan oleh Singleton dapat ditemukan di wadah azure-webjobs-host di akun penyimpanan AzureWebJobsStorage pada jalur "kunci". Misalnya, jalur blob sewa untuk contoh ProcessImage pertama yang ditampilkan sebelumnya mungkin locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage. Semua jalur menyertakan ID JobHost, dalam hal ini 061851c758f04938a4426aa9ab3869c0.

Fungsi Asinkron

Untuk informasi tentang cara membuat kode fungsi asinkron, lihat dokumentasi Azure Functions.

Token pembatalan

Untuk informasi tentang cara menangani token pembatalan, lihat dokumentasi Azure Functions di token pembatalan dan penonaktifan yang lancar.

Berbagai instans

Jika aplikasi web Anda berjalan di beberapa instans, WebJob berkelanjutan berjalan di setiap instans, mendengarkan pemicu dan memanggil fungsi. Berbagai binding pemicu dirancang untuk secara efisien berbagi pekerjaan secara kolaboratif di seluruh instans, sehingga penskalaan ke lebih banyak instans memungkinkan Anda menangani lebih banyak beban.

Sementara beberapa pemicu dapat mengakibatkan pemrosesan ganda, pemicu antrean dan penyimpanan blob secara otomatis mencegah fungsi memproses pesan antrean atau blob lebih dari sekali. Untuk informasi selengkapnya, lihat Merancang untuk input yang identik dalam dokumentasi Azure Functions.

Pemicu pengatur waktu secara otomatis memastikan bahwa hanya satu contoh timer yang berjalan, sehingga Anda tidak menjalankan lebih dari satu contoh fungsi pada waktu yang dijadwalkan.

Jika Anda ingin memastikan bahwa hanya satu fungsi yang berjalan meskipun ada beberapa aplikasi web host, Anda dapat menggunakan atribut Singleton.

Filter

Filter Fungsi (pratinjau) menyediakan cara untuk menyesuaikan alur eksekusi WebJobs dengan logika Anda sendiri. Filter mirip dengan filter ASP.NET Core. Anda dapat mengimplementasikannya sebagai atribut deklaratif yang diterapkan ke fungsi atau kelas Anda. Untuk informasi selengkapnya, lihat Filter Fungsi.

Pengelogan dan pemantauan

Kami merekomendasikan kerangka pengelogan yang dikembangkan untuk ASP.NET. Artikel Memulai menunjukkan cara menggunakannya.

Pemfilteran log

Setiap log yang dibuat oleh instans ILogger memiliki Category dan Level yang terkait. LogLevel adalah enumerasi, dan kode bilangan bulat menunjukkan tingkat kepentingan relatif:

LogLevel Kode
Trace 0
Debug 1
Informasi 2
Peringatan 3
Kesalahan 4
Kritis 5
Tidak 6

Anda dapat memfilter sendiri setiap kategori ke LogLevel tertentu. Misalnya, Anda mungkin ingin melihat semua log untuk pemrosesan pemicu gumpalan tetapi hanya Error dan lebih tinggi untuk yang lainnya.

Versi 3.x

Versi 3.x SDK bergantung pada pemfilteran yang ada di dalam .NET Core. Kelas LogCategories memungkinkan Anda menentukan kategori untuk fungsi, pemicu, atau pengguna tertentu. Ini juga menentukan filter untuk status host tertentu, seperti Startup dan Results. Ini memungkinkan Anda untuk menyetel output pengelogan. Jika tidak ada kecocokan yang ditemukan dalam kategori yang ditentukan, filter akan kembali ke nilai Default saat memutuskan apakah akan memfilter pesan.

LogCategories memerlukan pernyataan penggunaan berikut:

using Microsoft.Azure.WebJobs.Logging;

Contoh berikut membuat filter yang, secara default, memfilter semua log pada tingkat Warning. Kategori Function dan results (setara dengan Host.Results di versi 2.x) difilter pada tingkat Error. Filter membandingkan kategori saat ini dengan semua level yang terdaftar di instans LogCategories dan memilih kecocokan terlama. Ini berarti level Debug yang terdaftar untuk Host.Triggers cocok dengan Host.Triggers.Queue atau Host.Triggers.Blob. Ini memungkinkan Anda untuk mengontrol kategori yang lebih luas tanpa perlu menambahkan masing-masing kategori.

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureLogging(logging =>
            {
                logging.SetMinimumLevel(LogLevel.Warning);
                logging.AddFilter("Function", LogLevel.Error);
                logging.AddFilter(LogCategories.CreateFunctionCategory("MySpecificFunctionName"),
                    LogLevel.Debug);
                logging.AddFilter(LogCategories.Results, LogLevel.Error);
                logging.AddFilter("Host.Triggers", LogLevel.Debug);
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Versi 2.x

Di SDK versi 2.x, Anda menggunakan kelas LogCategoryFilter untuk mengontrol pemfilteran. LogCategoryFilter memiliki properti Default dengan nilai awal Information, artinya setiap pesan di tingkat Information, Warning, Error, atau Critical dicatat, tetapi pesan apa pun di tingkat Debug atau Trace difilter.

Seperti halnya LogCategories di versi 3.x, properti CategoryLevels memungkinkan Anda menentukan tingkat log untuk kategori tertentu sehingga Anda dapat menyetel output pengelogan. Jika tidak ditemukan kecocokan dalam kamus CategoryLevels, filter akan kembali ke nilai Default saat memutuskan apakah akan memfilter pesan.

Contoh berikut membuat filter yang secara default memfilter semua log pada tingkat Warning. Kategori Function dan Host.Results difilter pada tingkat Error. LogCategoryFilter membandingkan kategori saat ini dengan semua CategoryLevels yang terdaftar dan memilih kecocokan terlama. Jadi tingkat Debug yang terdaftar untuk Host.Triggers akan cocok dengan Host.Triggers.Queue atau Host.Triggers.Blob. Ini memungkinkan Anda untuk mengontrol kategori yang lebih luas tanpa perlu menambahkan masing-masing kategori.

var filter = new LogCategoryFilter();
filter.DefaultLevel = LogLevel.Warning;
filter.CategoryLevels[LogCategories.Function] = LogLevel.Error;
filter.CategoryLevels[LogCategories.Results] = LogLevel.Error;
filter.CategoryLevels["Host.Triggers"] = LogLevel.Debug;

config.LoggerFactory = new LoggerFactory()
    .AddApplicationInsights(instrumentationKey, filter.Filter)
    .AddConsole(filter.Filter);

Telemetri khusus untuk Application Insights

Proses penerapan telemetri khusus untuk Application Insights bergantung pada versi SDK. Untuk mempelajari cara mengonfigurasi Application Insights, lihat Menambahkan pencatatan Application Insights.

Versi 3.x

Karena versi 3.x WebJobs SDK bergantung pada host generik .NET Core, pabrik telemetri khusus tidak lagi disediakan. Tetapi Anda dapat menambahkan telemetri khusus ke alur dengan menggunakan injeksi dependensi. Contoh di bagian ini memerlukan pernyataan using berikut:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Channel;

Penerapan khusus ITelemetryInitializer berikut memungkinkan Anda menambahkan ITelemetry Anda sendiri ke TelemetryConfiguration default.

internal class CustomTelemetryInitializer : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        // Do something with telemetry.
    }
}

Hubungi ConfigureServices di penyusun untuk menambahkan ITelemetryInitializer khusus Anda ke saluran.

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureLogging((context, b) =>
    {
        // Add logging providers.
        b.AddConsole();

        // If this key exists in any config, use it to enable Application Insights.
        string appInsightsKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
        if (!string.IsNullOrEmpty(appInsightsKey))
        {
            // This uses the options callback to explicitly set the instrumentation key.
            b.AddApplicationInsights(o => o.InstrumentationKey = appInsightsKey);
        }
    });
    builder.ConfigureServices(services =>
        {
            services.AddSingleton<ITelemetryInitializer, CustomTelemetryInitializer>();
        });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Saat TelemetryConfiguration dibuat, semua jenis ITelemetryInitializer yang terdaftar akan disertakan. Untuk mempelajari lebih lanjut, lihat API Application Insights untuk peristiwa dan metrik khusus.

Di versi 3.x, Anda tidak perlu lagi membersihkan TelemetryClient saat host berhenti. Sistem injeksi ketergantungan .NET Core secara otomatis membuang ApplicationInsightsLoggerProvider terdaftar, yang membersihkan TelemetryClient.

Versi 2.x

Dalam versi 2.x, TelemetryClient yang dibuat secara internal oleh penyedia Application Insights untuk WebJobs SDK menggunakan ServerTelemetryChannel. Bila titik akhir Application Insights tidak tersedia atau membatasi permintaan masuk, saluran ini menyimpan permintaan dalam sistem file aplikasi web dan mengirimkannya kembali nanti.

TelemetryClient dibuat oleh kelas yang mengimplementasikan ITelemetryClientFactory. Secara default, ini adalah DefaultTelemetryClientFactory.

Jika Anda ingin mengubah bagian mana pun dari saluran Application Insights, Anda dapat menyediakan ITelemetryClientFactory Anda sendiri, dan host akan menggunakan kelas Anda untuk membuat TelemetryClient. Misalnya, kode ini mengambil alih DefaultTelemetryClientFactory untuk mengubah properti ServerTelemetryChannel:

private class CustomTelemetryClientFactory : DefaultTelemetryClientFactory
{
    public CustomTelemetryClientFactory(string instrumentationKey, Func<string, LogLevel, bool> filter)
        : base(instrumentationKey, new SamplingPercentageEstimatorSettings(), filter)
    {
    }

    protected override ITelemetryChannel CreateTelemetryChannel()
    {
        ServerTelemetryChannel channel = new ServerTelemetryChannel();

        // Change the default from 30 seconds to 15 seconds.
        channel.MaxTelemetryBufferDelay = TimeSpan.FromSeconds(15);

        return channel;
    }
}

Objek SamplingPercentageEstimatorSettings mengonfigurasi pengambilan sampel adaptif. Ini berarti bahwa dalam skenario volume tinggi tertentu, Applications Insights mengirimkan subset data telemetri yang dipilih ke server.

Setelah Anda membuat pabrik telemetri, Anda meneruskannya ke penyedia logging Application Insights:

var clientFactory = new CustomTelemetryClientFactory(instrumentationKey, filter.Filter);

config.LoggerFactory = new LoggerFactory()
    .AddApplicationInsights(clientFactory);

Langkah berikutnya

Artikel ini telah menyediakan cuplikan kode yang menunjukkan cara menangani skenario umum untuk bekerja dengan WebJobs SDK. Untuk sampel lengkap, lihat azure-webjobs-sdk-samples.