Mulai cepat: Mengirim peristiwa ke dan menerima peristiwa dari Azure Event Hubs menggunakan .NET

Azure Event Hubs adalah platform streaming data real time yang dapat menerima dan memproses jutaan peristiwa per detik. Jika Anda membangun aplikasi .NET yang perlu menyerap atau bereaksi terhadap aliran peristiwa volume tinggi, Azure Event Hubs menyediakan infrastruktur yang dapat diskalakan untuk melakukannya.

Dalam memulai cepat ini, Anda membuat aplikasi konsol .NET yang mengirim peristiwa ke hub peristiwa dan menerimanya menggunakan pustaka Azure.Messaging.EventHubs. Pada akhirnya, Anda akan memiliki kode kerja yang dapat Disesuaikan untuk skenario berbasis peristiwa Anda sendiri.

Prasyarat

Jika Anda baru menggunakan Azure Event Hubs, lihat ikhtisar Event Hubs sebelum Anda menyelesaikan panduan memulai cepat ini.

Catatan

Jika Anda sudah terbiasa dengan layanan ini, Anda dapat melihat sampel .NET untuk Event Hubs di repositori SDK .NET kami di GitHub: sampel Event Hubs di GitHub, sampel prosesor event di GitHub.

Untuk menyelesaikan panduan memulai cepat ini, Anda memerlukan:

  • Langganan Microsoft Azure. Untuk menggunakan layanan Azure, termasuk Azure Event Hubs, Anda memerlukan langganan. Jika Anda tidak memiliki akun Azure yang sudah ada, Anda dapat mendaftar untuk coba gratis.
  • Microsoft Visual Studio 2022. Pustaka klien Azure Event Hubs menggunakan fitur baru yang diperkenalkan di C# 8.0. Anda masih dapat menggunakan pustaka dengan versi bahasa C# sebelumnya, tetapi sintaks baru tidak tersedia. Untuk menggunakan sintaks penuh, kami sarankan Anda mengkompilasi dengan .NET Core SDK 3.0 atau lebih tinggi dan versi language diatur ke latest. Jika Anda menggunakan Visual Studio, versi sebelum Visual Studio 2022 tidak kompatibel dengan alat yang diperlukan untuk membangun proyek C# 8.0. Visual Studio 2022, termasuk edisi Komunitas gratis, dapat diunduh di sini.
  • Membuat ruang nama Azure Event Hubs dan pusat aktivitas. Gunakan portal Azure untuk membuat namespace Event Hubs dan event hub di dalam namespace tersebut. Kemudian, dapatkan kredensial manajemen yang perlu dikomunikasikan oleh aplikasi Anda dengan pusat aktivitas. Untuk membuat namespace dan hub peristiwa, lihat Mulai Cepat: Membuat hub peristiwa menggunakan portal Azure.

Mengautentikasi aplikasi ke Azure

Panduan mulai cepat ini menunjukkan kepada Anda dua cara menyambungkan ke Azure Event Hubs.

  • Tanpa kata sandi (autentikasi Microsoft Entra)
  • String koneksi

Opsi pertama menunjukkan kepada Anda cara menggunakan prinsip keamanan Anda di ID Microsoft Entra Azure dan kontrol akses berbasis peran (RBAC) untuk menyambungkan ke namespace layanan Azure Event Hubs. Anda tidak perlu khawatir tentang memiliki string koneksi yang dikodekan secara permanen dalam kode Anda atau dalam file konfigurasi atau dalam penyimpanan aman seperti Azure Key Vault.

Opsi kedua menunjukkan cara menggunakan string koneksi untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Jika Anda baru menggunakan Azure, Anda mungkin menemukan opsi string koneksi lebih mudah diikuti. Sebaiknya gunakan opsi tanpa kata sandi di aplikasi dunia nyata dan lingkungan produksi. Untuk informasi selengkapnya, lihat Autentikasi dan otorisasi. Anda juga dapat membaca selengkapnya tentang autentikasi tanpa kata sandi di halaman gambaran umum.

Menetapkan peran ke pengguna Microsoft Entra Anda

Saat Anda mengembangkan secara lokal, pastikan akun pengguna yang tersambung ke Azure Event Hubs memiliki izin yang benar. Anda memerlukan peran Pemilik Data Azure Event Hubs untuk mengirim dan menerima pesan. Untuk menetapkan sendiri peran ini, Anda memerlukan peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write. Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Untuk informasi selengkapnya, lihat Memahami cakupan untuk halaman Azure RBAC .

Contoh berikut mengaitkan peran Azure Event Hubs Data Owner dengan akun pengguna Anda, yang memberikan akses penuh ke sumber daya Azure Event Hubs. Dalam skenario nyata, ikuti Prinsip Hak Istimewa Paling Sedikit untuk memberi pengguna hanya izin minimum yang diperlukan untuk lingkungan produksi yang lebih aman.

Peran bawaan Azure untuk Azure Event Hubs

Untuk Azure Event Hubs, pengelolaan namespace layanan dan semua sumber daya terkait melalui portal Azure dan API manajemen sumber daya Azure sudah dilindungi menggunakan model Azure RBAC. Azure menyediakan peran bawaan berikut untuk mengotorisasi akses ke namespace Layanan Pusat Aktivitas:

Jika Anda ingin membuat peran kustom, lihat Hak yang diperlukan untuk operasi Azure Event Hubs.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure. Dalam kasus yang jarang terjadi, mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan namespace Layanan Pusat Aktivitas Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Pada halaman gambaran umum, pilih Kontrol akses (IAM) dari menu sebelah kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas. Lalu pilih Tambahkan penetapan peran.

    Cuplikan layar memperlihatkan cara menetapkan peran.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Azure Event Hubs Data Owner dan pilih hasil yang cocok. Kemudian pilih Berikutnya.

  6. Di bawah Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan. Lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda). Pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir. Pilih Tinjau + tetapkan lagi untuk menyelesaikan proses.

Luncurkan Visual Studio dan masuk ke Azure

Anda dapat mengotorisasi akses ke namespace bus layanan menggunakan langkah-langkah berikut:

  1. Luncurkan Visual Studio. Jika Anda melihat jendela Mulai , pilih tautan Lanjutkan tanpa kode di panel kanan.

  2. Pilih tombol Masuk di kanan atas Visual Studio.

    Cuplikan layar memperlihatkan tombol untuk masuk ke Azure menggunakan Visual Studio.

  3. Masuk menggunakan akun Microsoft Entra yang Anda tetapkan perannya sebelumnya.

    Cuplikan layar yang menampilkan pemilihan akun.

Mengirim peristiwa ke hub peristiwa

Bagian ini menunjukkan kepada Anda cara membuat aplikasi konsol .NET Core untuk mengirim peristiwa ke pusat aktivitas yang Anda buat.

Membuat aplikasi konsol

  1. Jika Visual Studio 2022 sudah terbuka, pilih File pada menu, pilih Baru, lalu pilih Project. Jika tidak, luncurkan Visual Studio 2022 dan pilih Buat proyek baru jika Anda melihat jendela popup.

  2. Dalam Buat kotak dialog project baru, selesaikan langkah-langkah berikut: Jika Anda tidak melihat kotak dialog ini, pilih File pada menu, pilih Baru, lalu pilih Project.

    1. Pilih C# sebagai bahasa pemrograman.

    2. Pilih Konsol untuk jenis aplikasi.

    3. Pilih Aplikasi Konsol dari daftar hasil.

    4. Pilih Selanjutnya.

      Gambar yang menunjukkan kotak dialog Proyek Baru

  3. Masukkan EventHubsSender untuk nama proyek, EventHubsQuickStart untuk nama solusi, lalu pilih Berikutnya.

    Gambar yang menunjukkan halaman tempat Anda memasukkan nama solusi dan proyek

  4. Di halaman Informasi tambahan, pilih Buat.

Menambahkan paket NuGet ke proyek

  1. Pilih Alat>NuGet Package Manager>Package Manager Console dari menu.

  2. Jalankan perintah berikut untuk menginstal Azure. Messaging.EventHubs dan Azure. Identitas paket NuGet. Tekan ENTER untuk menjalankan perintah kedua.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Identity

Menulis kode untuk mengirim peristiwa ke pusat aktivitas

  1. Ganti kode yang ada dalam Program.cs file dengan kode sampel berikut. Kemudian, ganti <EVENT_HUB_NAMESPACE> dan <HUB_NAME> nilai penampung untuk parameter EventHubProducerClient dengan nama namespace Event Hubs dan pusat aktivitas Anda. Misalnya: "spehubns0309.servicebus.windows.net" dan "spehub".

    Berikut langkah-langkah penting dari kode:

    1. Membuat objek EventHubProducerClient menggunakan namespace layanan dan nama hub peristiwa.
    2. Memanggil metode CreateBatchAsync pada objek EventHubProducerClient untuk membuat objek EventDataBatch .
    3. Menambahkan peristiwa ke batch menggunakan metode EventDataBatch.TryAdd .
    4. Mengirim batch peristiwa ke pusat aktivitas menggunakan metode EventHubProducerClient.SendAsync .
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;
using System.Text;

// number of events to be sent to the event hub
int numOfEvents = 3;

// The Event Hubs client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when events are being published or read regularly.
// TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
EventHubProducerClient producerClient = new EventHubProducerClient(
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Create a batch of events 
using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

for (int i = 1; i <= numOfEvents; i++)
{
    if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
    {
        // if it is too large for the batch
        throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
    }
}

try
{
    // Use the producer client to send the batch of events to the event hub
    await producerClient.SendAsync(eventBatch);
    Console.WriteLine($"A batch of {numOfEvents} events has been published.");
    Console.ReadLine();
}
finally
{
    await producerClient.DisposeAsync();
}

  1. Bangun program, dan pastikan tidak ada kesalahan.

  2. Jalankan program dan tunggu pesan konfirmasi.

    A batch of 3 events has been published.

    Catatan

    Jika Anda mendapatkan kesalahan "InvalidIssuer: Penerbit token tidak valid" saat menggunakan autentikasi Microsoft Entra, itu mungkin karena ID Penyewa Microsoft Entra yang salah sedang digunakan. Dalam kode Anda, ganti 'new DefaultAzureCredential()' dengan 'new DefaultAzureCredential(new DefaultAzureCredentialOptions {TenantId = "xxxxxxxx-xxxx-xxxx-xxxx-xxx"})' untuk secara eksplisit menentukan ID Penyewa Microsoft Entra.

    Penting

    Jika Anda menggunakan autentikasi Tanpa Kata Sandi (kontrol akses berbasis peran Microsoft Entra), pilih Tools, lalu pilih Options. Di jendela Opsi , perluas Autentikasi Layanan Azure, dan pilih Pilihan Akun. Konfirmasikan bahwa Anda menggunakan akun yang ditambahkan ke peran Pemilik Data Azure Event Hubs di namespace layanan Azure Event Hubs.

  3. Pada halaman namespace layanan Azure Event Hubs di portal Microsoft Azure, Anda akan melihat tiga pesan masuk di bagan Pesan . Refresh halaman untuk memperbarui bagan jika diperlukan. Mungkin perlu beberapa detik agar pesan diterima.

    Gambar halaman portal Microsoft Azure untuk memverifikasi bahwa pusat aktivitas telah menerima peristiwa

    Catatan

    Untuk kode sumber lengkap dengan komentar informasi selengkapnya, lihat file ini di GitHub

Menerima peristiwa dari event hub

Bagian ini menunjukkan cara menulis aplikasi konsol .NET Core yang menerima acara dari pusat aktivitas menggunakan prosesor acara. Pemroses peristiwa menyederhanakan penerimaan peristiwa dari hub peristiwa.

Membuat akun Azure Storage dan kontainer blob

Dalam panduan memulai cepat ini, Anda menggunakan Azure Storage sebagai checkpoint. Gunakan langkah-langkah berikut untuk membuat akun Azure Storage:

  1. Membuat akun Microsoft Azure Storage
  2. Membuat kontainer blob
  3. Autentikasi ke kontainer blob dengan menggunakan autentikasi Microsoft Entra ID (tanpa kata sandi) atau string koneksi ke namespace.

Ikuti rekomendasi ini saat Anda menggunakan Azure Blob Storage sebagai penyimpanan titik pemeriksaan:

  • Gunakan kontainer terpisah untuk setiap grup konsumen. Anda dapat menggunakan akun penyimpanan yang sama, tetapi menggunakan satu kontainer per setiap grup.
  • Jangan gunakan akun penyimpanan untuk hal lain.
  • Jangan gunakan kontainer untuk hal lain.
  • Buat akun penyimpanan di wilayah yang sama dengan aplikasi yang disebarkan. Jika aplikasi lokal, coba pilih wilayah terdekat yang mungkin.

Pada halaman Akun penyimpanan di portal Azure, di bagian Blob service, pastikan bahwa pengaturan berikut dinonaktifkan.

  • Namespace hierarkis
  • Penghapusan sementara blob
  • Pembuatan Versi

Saat Anda mengembangkan secara lokal, pastikan akun pengguna yang mengakses data blob memiliki izin yang benar. Anda memerlukan Kontributor Penyimpanan Data Blob untuk membaca dan menulis data blob. Untuk menetapkan peran ini pada diri Anda sendiri, Anda perlu diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write. Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Untuk informasi selengkapnya, lihat Memahami cakupan untuk Azure RBAC.

Dalam skenario ini, Anda menetapkan izin ke akun pengguna Anda, yang cakupannya terbatas pada akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa yang Paling Sedikit. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure. Dalam kasus yang jarang terjadi, mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Pada halaman akun penyimpanan, pilih Kontrol akses (IAM) dari menu sebelah kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas. Lalu pilih Tambahkan penetapan peran.

    Cuplikan layar memperlihatkan cara menetapkan peran akun penyimpanan.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Pengelola Data Blob Penyimpanan. Pilih hasil yang cocok lalu pilih Berikutnya.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir. Pilih Tinjau + tetapkan lagi untuk menyelesaikan proses.

Membuat proyek untuk penerima

  1. Di jendela Penjelajah Solusi, klik kanan solusi EventHubQuickStart, arahkan ke Tambahkan, dan pilih Proyek Baru.
  2. Pilih Aplikasi konsol, lalu pilih Selanjutnya.
  3. Masukkan EventHubsReceiver untuk nama Proyek, dan pilih Buat.
  4. Di jendela Penjelajah Solusi, klik kanan EventHubsReceiver, lalu pilih Atur sebagai Proyek Startup.

Menambahkan paket NuGet ke proyek

  1. Pilih Alat>NuGet Package Manager>Package Manager Console dari menu.

  2. Di jendela Konsol Manajer Paket, konfirmasikan bahwa EventHubsReceiver dipilih sebagai proyek Default. Jika tidak, gunakan daftar drop-down untuk memilih EventHubsReceiver.

  3. Jalankan perintah berikut untuk menginstal Azure. Messaging.EventHubs dan Azure. Identitas paket NuGet. Tekan ENTER untuk menjalankan perintah terakhir.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Messaging.EventHubs.Processor
Install-Package Azure.Identity

Memperbarui kode

Ganti konten Program.cs dengan kode berikut:

  1. Ganti kode yang ada dalam Program.cs file dengan kode sampel berikut. Kemudian, ganti nilai tempat penampung <STORAGE_ACCOUNT_NAME> dan <BLOB_CONTAINER_NAME> untuk URI BlobContainerClient. Ganti nilai <EVENT_HUB_NAMESPACE> dan <HUB_NAME> untuk EventProcessorClient juga.

    Berikut langkah-langkah penting dari kode:

    1. Membuat objek EventProcessorClient menggunakan namespace Layanan Pusat Aktivitas dan nama hub peristiwa. Anda perlu membangun objek BlobContainerClient untuk kontainer di penyimpanan Azure yang Anda buat sebelumnya.
    2. Menentukan penangan untuk peristiwa ProcessEventAsync dan ProcessErrorAsync dari objek EventProcessorClient.
    3. Mulai memproses peristiwa dengan meminta StartProcessingAsync pada objek EventProcessorClient.
    4. Berhenti memproses peristiwa setelah 30 detik dengan memanggil StopProcessingAsync pada objek EventProcessorClient .
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;
using Azure.Storage.Blobs;
using System.Text;

// Create a blob container client that the event processor will use
// TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTAINER_NAME> with actual names
BlobContainerClient storageClient = new BlobContainerClient(
    new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
    new DefaultAzureCredential());

// Create an event processor client to process events in the event hub
// TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
var processor = new EventProcessorClient(
    storageClient,
    EventHubConsumerClient.DefaultConsumerGroupName,
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Register handlers for processing events and handling errors
processor.ProcessEventAsync += ProcessEventHandler;
processor.ProcessErrorAsync += ProcessErrorHandler;

// Start the processing
await processor.StartProcessingAsync();

// Wait for 30 seconds for the events to be processed
await Task.Delay(TimeSpan.FromSeconds(30));

// Stop the processing
await processor.StopProcessingAsync();

Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
    // Write the body of the event to the console window
    Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
    Console.ReadLine();
    return Task.CompletedTask;
}

Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
{
    // Write details about the error to the console window
    Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
    Console.WriteLine(eventArgs.Exception.Message);
    Console.ReadLine();
    return Task.CompletedTask;
}

  1. Bangun program, dan pastikan tidak ada kesalahan.

    Catatan

    Untuk kode sumber lengkap dengan komentar informasi selengkapnya, lihat file ini di GitHub.

  2. Jalankan aplikasi penerima.

  3. Anda melihat pesan bahwa peristiwa diterima. Tekan ENTER setelah Anda melihat pesan peristiwa yang diterima.

    Received event: Event 1
Received event: Event 2
Received event: Event 3

    Acara ini adalah tiga acara yang Anda kirim ke hub acara sebelumnya dengan menjalankan program pengirim.

  4. Dalam portal Azure, Anda dapat memverifikasi bahwa ada tiga pesan keluar, yang dikirim Azure Event Hubs ke aplikasi penerima. Refresh halaman untuk memperbarui bagan. Mungkin perlu beberapa detik agar pesan diterima.

    Gambar halaman portal Azure untuk memverifikasi bahwa Event Hub mengirimkan peristiwa ke aplikasi penerima

Validasi skema untuk aplikasi berbasis Azure Event Hubs SDK

Anda dapat menggunakan Azure Schema Registry untuk melakukan validasi skema saat melakukan streaming data dengan aplikasi berbasis Event Hubs SDK Anda. Azure Schema Registry of Event Hubs menyediakan repositori terpusat untuk mengelola skema, dan Anda dapat menghubungkan aplikasi baru atau yang sudah ada dengan mulus dengan Schema Registry.

Untuk mempelajari selengkapnya, lihat Memvalidasi skema dengan Event Hubs SDK.

Sampel dan referensi

Panduan cepat ini menyediakan instruksi langkah demi langkah untuk mengimplementasikan skenario pengiriman batch acara ke pusat acara dan kemudian menerimanya. Untuk sampel lainnya, pilih tautan berikut.

Untuk referensi pustaka .NET lengkap, lihat dokumentasi SDK kami.

Membersihkan sumber daya

Hapus grup sumber daya yang memiliki namespace Layanan Pusat Aktivitas atau hapus hanya namespace jika Anda ingin menyimpan grup sumber daya.

Konten terkait

Lihat tutorial berikut:

Tutorial: Memvisualisasikan anomali data dalam peristiwa real time yang dikirim ke Azure Event Hubs

  • Last updated on