Tutorial: Menggunakan integrasi olahpesan .NET Aspire di ASP.NET Core

Aplikasi cloud-native sering memerlukan solusi olahpesan yang dapat diskalakan yang menyediakan kemampuan seperti antrean dan topik olahpesan serta langganan. .NET Aspire integrasi menyederhanakan proses menghubungkan dengan berbagai penyedia olahpesan, seperti Azure Service Bus. Dalam tutorial ini, Anda akan membuat aplikasi ASP.NET Core yang menggunakan integrasi .NET Aspire untuk terhubung ke Azure Service Bus untuk membuat sistem pemberitahuan. Pesan yang dikirimkan akan dikirim ke topik Service Bus untuk dikonsumsi oleh pelanggan berlangganan. Anda akan mempelajari cara:

Prasyarat

Untuk bekerja dengan .NET.NET Aspire, Anda memerlukan hal berikut yang diinstal secara lokal:

• .NET 8.0 atau .NET 9.0
• Runtime kontainer yang sesuai dengan OCI, seperti:
  • Docker Desktop atau Podman. Untuk informasi selengkapnya, lihat Container runtime .
• Lingkungan Pengembang Terintegrasi (IDE) atau editor kode, seperti:
  • Visual Studio 2022 versi 17.9 atau lebih tinggi (Opsional)
  • Visual Studio Code (Opsional)
    • C# Dev Kit: Ekstensi (Opsional)
  • JetBrains Rider dengan plugin .NET.NET Aspire (Opsional)

Untuk informasi selengkapnya, lihat penyiapan dan alat .NET.NET Aspire, dan .NET.NET Aspire SDK.

Selain prasyarat sebelumnya, Anda juga perlu menginstal CLI Azure. Untuk menginstal CLI Azure, ikuti instruksi dalam panduan penginstalan CLI Azure.

Menyiapkan akun Azure Service Bus

Untuk tutorial ini, Anda memerlukan akses ke namespace Azure Service Bus dengan topik dan langganan yang dikonfigurasi. Gunakan salah satu opsi berikut untuk menyiapkan sumber daya yang diperlukan:

• Azure portal: Membuat akun bus layanan dengan topik dan langganan.

Atau:

• Azure CLI: Jalankan perintah berikut di Azure CLI atau CloudShell untuk menyiapkan sumber daya Azure Service Bus yang diperlukan:

  az group create -n <your-resource-group-name> --location eastus
  az servicebus namespace create -g <your-resource-group-name> --name <your-namespace-name> --location eastus
  az servicebus topic create -g <your-resource-group-name> --namespace-name <your-namespace-name> --name notifications
  az servicebus topic subscription create -g <your-resource-group-name> --namespace-name <your-namespace-name> --topic-name notifications --name mobile
  

  Nota

  Ganti nama grup sumber daya Anda dan placeholder nama namespace Anda dengan nilai Anda sendiri. Nama namespace Service Bus harus unik secara global di seluruh Azure.

autentikasi Azure

Mulai cepat ini dapat diselesaikan menggunakan autentikasi tanpa kata sandi atau string koneksi. Koneksi tanpa kata sandi menggunakan Azure Active Directory dan kontrol akses berbasis peran (RBAC) untuk menyambungkan ke namespace Service Bus. Anda tidak perlu khawatir memiliki string koneksi yang dikodekan secara permanen dalam kode Anda, file konfigurasi, atau dalam penyimpanan aman seperti Azure Key Vault.

Anda juga dapat menggunakan string koneksi untuk menyambungkan ke namespace Service Bus, tetapi pendekatan tanpa kata sandi direkomendasikan untuk aplikasi dunia nyata dan lingkungan produksi. Untuk informasi selengkapnya, baca tentang Autentikasi dan otorisasi atau kunjungi halaman gambaran umum tanpa kata sandi.

Membuat solusi sampel

Untuk membuat Aplikasi Pemula .NET Aspire baru, Anda dapat menggunakan Visual Studio, Visual Studio Code, atau CLI .NET.

dotnet new install Aspire.ProjectTemplates

dotnet new aspire-starter --use-redis-cache --output AspireSample

Menambahkan proyek Worker Service

Selanjutnya, tambahkan proyek Worker Service ke solusi untuk mengambil dan memproses pesan ke dan dari Azure Service Bus.

builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");

Struktur solusi yang lengkap harus menyerupai berikut, dengan asumsi direktori tingkat atas diberi nama aspire-pesan:

└───📂 aspire-messaging
     ├───📂 AspireSample.WorkerService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.WorkerService.csproj
     │    ├─── Program.cs
     │    └─── Worker.cs
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

Menambahkan integrasi .NET.NET Aspire ke API

Tambahkan integrasi .NET Aspire Azure Service Bus ke aplikasi AspireSample.ApiService Anda:

dotnet add package Aspire.Azure.Messaging.ServiceBus

Dalam file Program.cs dari proyek AspireSample.ApiService, tambahkan panggilan ke metode ekstensi AddAzureServiceBusClient segera setelah panggilan yang ada ke AddServiceDefaults:

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

Untuk informasi selengkapnya, lihat AddAzureServiceBusClient.

Metode ini menyelesaikan tugas-tugas berikut:

• Mendaftarkan ServiceBusClient dengan kontainer DI untuk menyambungkan ke Azure Service Bus.
• Secara otomatis mengaktifkan pemeriksaan kesehatan, pengelogan, dan telemetri yang sesuai untuk masing-masing layanan.

Dalam file appsettings.json proyek yang sama, tambahkan informasi koneksi yang sesuai:

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_connection_string}"
  }
}

Membuat titik akhir API

API harus menyediakan endpoint untuk menerima data, menerbitkannya ke topik Service Bus, dan menyiarkannya kepada pelanggan. Tambahkan titik akhir berikut ke proyek AspireSample.ApiService untuk mengirim pesan ke topik Service Bus. Ganti semua konten file Program.cs dengan kode C# berikut:

using Azure.Messaging.ServiceBus;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

// Add services to the container.
builder.Services.AddProblemDetails();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

app.MapPost("/notify", static async (ServiceBusClient client, string message) =>
{
    var sender = client.CreateSender("notifications");

    // Create a batch
    using ServiceBusMessageBatch messageBatch =
        await sender.CreateMessageBatchAsync();

    if (messageBatch.TryAddMessage(
            new ServiceBusMessage($"Message {message}")) is false)
    {
        // If it's too large for the batch.
        throw new Exception(
            $"The message {message} is too large to fit in the batch.");
    }

    // Use the producer client to send the batch of
    // messages to the Service Bus topic.
    await sender.SendMessagesAsync(messageBatch);

    Console.WriteLine($"A message has been published to the topic.");
});

app.MapDefaultEndpoints();

app.Run();

Menambahkan integrasi .NET Aspire ke Worker Service

Tambahkan integrasi ke proyek AspireSample.WorkerService Anda. Ikuti langkah-langkah yang sama seperti yang Anda lakukan sebelumnya ketika Anda menambahkan .. Paket Messaging.ServiceBus NuGet ke proyek AspireSample.ApiService. Setelah ditambahkan, Anda dapat mengkonfigurasikan layanan pekerja untuk memproses pesan dari topik pada Service Bus.

Dalam file Program.cs proyek AspireSample.WorkerService, ganti kode yang ada dengan yang berikut ini:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

Metode AddAzureServiceBusClient menyelesaikan tugas-tugas berikut:

• Mendaftarkan ServiceBusClient dengan kontainer DI untuk menyambungkan ke Azure Service Bus.
• Secara otomatis mengaktifkan pemeriksaan kesehatan, pengelogan, dan telemetri yang sesuai untuk masing-masing layanan.

Dalam file appsettings.json dari proyek AspireSample.WorkerService, tambahkan informasi koneksi yang sesuai:

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_connection_string}"
  }
}

Memproses pesan dari pelanggan

Saat pesan baru ditempatkan pada antrean messages, layanan pekerja harus mengambil, memproses, dan menghapus pesan. Perbarui kelas Worker.cs agar sesuai dengan kode berikut:

using Azure.Messaging.ServiceBus;

namespace AspireSample.WorkerService;

public sealed class Worker(
    ILogger<Worker> logger,
    ServiceBusClient client) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var processor = client.CreateProcessor(
                "notifications",
                "mobile",
                new ServiceBusProcessorOptions());

            // Add handler to process messages
            processor.ProcessMessageAsync += MessageHandler;

            // Add handler to process any errors
            processor.ProcessErrorAsync += ErrorHandler;

            // Start processing
            await processor.StartProcessingAsync();

            logger.LogInformation("""
                Wait for a minute and then press any key to end the processing
                """);

            Console.ReadKey();

            // Stop processing
            logger.LogInformation("""

                Stopping the receiver...
                """);

            await processor.StopProcessingAsync();

            logger.LogInformation("Stopped receiving messages");
        }
    }

    async Task MessageHandler(ProcessMessageEventArgs args)
    {
        string body = args.Message.Body.ToString();

        logger.LogInformation("Received: {Body} from subscription.", body);

        // Complete the message. messages is deleted from the subscription.
        await args.CompleteMessageAsync(args.Message);
    }

    // Handle any errors when receiving messages
    Task ErrorHandler(ProcessErrorEventArgs args)
    {
        logger.LogError(args.Exception, "{Error}", args.Exception.Message);
        
        return Task.CompletedTask;
    }
}

Menjalankan dan menguji aplikasi secara lokal

Aplikasi sampel sekarang siap untuk pengujian. Verifikasi bahwa data yang dikirimkan ke API dikirim ke topik Azure Service Bus dan digunakan oleh layanan pekerja pelanggan:

2. Pada halaman sumber daya, di baris apiservice, temukan tautan di Endpoints yang membuka titik akhir weatherforecast. Perhatikan nomor port HTTPS.

3. Di dasbor .NET.NET Aspire, pergi ke log untuk proyek aspiresample-workerservice.

4. Di jendela terminal, gunakan perintah curl untuk mengirim pesan pengujian ke API:

   curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire
   

   Pastikan untuk mengganti {port} dengan nomor port yang Anda catat sebelumnya.

5. Beralih kembali ke log aspiresample-workerservice. Anda akan melihat pesan pengujian yang dicetak di log output.

Selamat! Anda membuat dan mengonfigurasi API ASP.NET Core yang tersambung ke Azure Service Bus menggunakan integrasi Aspire.

Membersihkan sumber daya

Jalankan perintah CLI Azure berikut untuk menghapus grup sumber daya saat Anda tidak lagi memerlukan sumber daya Azure yang Anda buat. Menghapus grup sumber daya juga menghapus sumber daya yang terkandung di dalamnya.

az group delete --name <your-resource-group-name>

Untuk informasi selengkapnya, lihat Membersihkan sumber daya di Azure.