Samouczek: korzystanie z integracji komunikatów .NET Aspire w ASP.NET Core

Artykuł
12/13/2024

Aplikacje natywne dla chmury często wymagają skalowalnych rozwiązań do obsługi komunikatów, które zapewniają funkcje, takie jak kolejki komunikatów i tematy i subskrypcje. Integracje .NET Aspire upraszczają proces nawiązywania połączenia z różnymi dostawcami wiadomości, takimi jak Azure Service Bus. W tym samouczku utworzysz aplikację ASP.NET Core, korzystając z integracji .NET Aspire, aby połączyć się z Azure Service Bus i utworzyć system powiadomień. Przesłane komunikaty zostaną wysłane do tematu usługi Service Bus, aby mogli z nich korzystać subskrybenci. Dowiesz się, jak wykonywać następujące działania:

Tworzenie podstawowej aplikacji .NET skonfigurowanej do korzystania z integracji .NET Aspire
Dodaj integrację .NET Aspire, aby połączyć się z Azure Service Bus
Konfigurowanie i używanie funkcji integracji .NET.NET Aspire do wysyłania i odbierania danych

Warunki wstępne

Aby pracować z .NET.NET Aspire, potrzebne są następujące elementy zainstalowane lokalnie:

.NET 8.0 lub .NET 9.0
Środowisko uruchomieniowe kontenera zgodne ze standardem OCI, takie jak:
- Docker Desktop lub Podman. Aby uzyskać więcej informacji, zobacz Container runtime.
Zintegrowane środowisko deweloperskie (IDE) lub edytor kodu, takie jak:
- Visual Studio 2022 w wersji 17.9 lub nowszej (opcjonalnie)
- Visual Studio Code (opcjonalnie)
  - C# Dev Kit: Rozszerzenie (opcjonalnie)
- JetBrains Rider z wtyczką .NET.NET Aspire (opcjonalnie)

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire setup and toolingi .NET.NET Aspire SDK.

Oprócz poprzednich wymagań wstępnych należy również zainstalować Azure CLI. Aby zainstalować CLI Azure, postępuj zgodnie z instrukcjami w przewodniku instalacji CLI Azure.

Konfigurowanie konta Azure Service Bus

Na potrzeby tego samouczka będziesz potrzebować dostępu do przestrzeni nazw Azure Service Bus ze skonfigurowanym tematem i subskrypcją. Użyj jednej z następujących opcji, aby skonfigurować wymagane zasoby:

Azure portal: Utwórz konto usługi Service Bus z tematem i subskrypcją.

Ewentualnie:

Azure CLI: Wykonaj następujące polecenia w CLI Azure lub CloudShell, aby przygotować wymagane zasoby Azure Service Bus.

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

Notatka

Zastąp nazwę grupy zasobów i nazwę twojej przestrzeni nazw własnymi wartościami. Nazwy przestrzeni nazw usługi Service Bus muszą być globalnie unikatowe w ramach Azure.

Uwierzytelnianie Azure

Ten szybki start można ukończyć przy użyciu uwierzytelniania bez hasła lub ciągu połączenia. Połączenia bez hasła używają Azure usługi Active Directory i kontroli dostępu opartej na rolach (RBAC) w celu nawiązania połączenia z przestrzenią nazw usługi Service Bus. Nie musisz martwić się o zakodowane parametry połączenia w kodzie, pliku konfiguracji lub w bezpiecznym magazynie, takim jak Azure Key Vault.

Możesz również użyć parametrów połączenia, aby nawiązać połączenie z przestrzenią nazw usługi Service Bus, ale podejście bez hasła jest zalecane w przypadku rzeczywistych aplikacji i środowisk produkcyjnych. Aby uzyskać więcej informacji, przeczytaj Uwierzytelnianie i autoryzacja lub odwiedź stronę przeglądu bez hasła .

bez hasła (zalecane)
łańcuch połączenia

W przestrzeni nazw Service Bus przypisz następującą rolę do konta użytkownika, którym zalogowałeś się do Visual Studio lub CLI Azure:

Właściciel danych usługi Service Bus: , przypisz rolę RBAC Azure

Tworzenie przykładowego rozwiązania

Aby utworzyć nową aplikację startową .NET Aspire, możesz użyć Visual Studio, Visual Studio Codelub interfejsu wiersza polecenia .NET.

Visual Studio udostępnia szablony .NET Aspire, które obsługują niektóre początkowe konfiguracje. Wykonaj następujące kroki, aby utworzyć projekt w ramach tego przewodnika szybkiego startu.

Na górze Visual Studioprzejdź do File>New>Project.
W oknie dialogowym wyszukaj Aspire i wybierz pozycję .NET.NET Aspire Starter App. Wybierz pozycję Dalej.
Na ekranie Skonfiguruj swój nowy projekt:
- Wprowadź nazwę projektu z AspireSample.
- Pozostaw wartości przy ich ustawieniach domyślnych rest i wybierz opcję Dalej.
Na ekranie Dodatkowe informacje:
- Upewnij się, że wybrano .NET 9.0 (Standardowa Obsługa Terminów).
- Upewnij się, że opcja Użyj Redis do buforowania (wymaga obsługiwanego środowiska uruchomieniowego kontenera) jest zaznaczona i wybierz Utwórz.
- Opcjonalnie możesz wybrać Utwórz projekt testów. Aby uzyskać więcej informacji, zobacz Pisanie pierwszego testu .NET.NET Aspire.

Visual Studio tworzy nowe rozwiązanie, które zostało zaprojektowane do używania .NET Aspire.

Visual Studio Code udostępnia szablony projektów .NET Aspire, które zajmują się niektórymi początkowymi ustawieniami konfiguracyjnymi. Wykonaj następujące kroki, aby utworzyć projekt na potrzeby tego samouczka.

W nowym wystąpieniu Visual Studio Code (bez otwartego folderu) wybierz przycisk Utwórz projekt .NET.
Wybierz szablon .NET.NET Aspire Starter App.

Jeśli jeszcze nie zainstalowano szablonów .NET.NET Aspire, uruchom następujące polecenie dotnet new install:

dotnet new install Aspire.ProjectTemplates

Poprzednie polecenie interfejsu wiersza polecenia .NET zapewnia dostępność szablonów .NET Aspire. Aby utworzyć aplikację startową .NET.NET Aspire na podstawie szablonu, uruchom następujące polecenie dotnet new:

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

Aby uzyskać więcej informacji, zobacz dotnet new. Interfejs wiersza polecenia .NET tworzy nowe rozwiązanie, które ma strukturę do używania .NET Aspire.

Dodawanie projektu Worker Service

Następnie dodaj projekt Worker Service do rozwiązania w celu pobierania i przetwarzania komunikatów do i z Azure Service Bus.

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy węzeł rozwiązania AspireSample najwyższego poziomu i wybierz pozycję Dodaj>Nowy projekt.
Wyszukaj i wybierz szablon Worker Service, a następnie kliknij Dalej.
Dla nazwy projektu wprowadź AspireSample.WorkerService i wybierz Dalej.
Na ekranie Dodatkowe informacje:
- Upewnij się, że wybrano .NET 9.0.
- Upewnij się, że zaznaczono enlist in orchestration i wybierz pozycję Create(Utwórz).

Visual Studio dodaje projekt do rozwiązania i aktualizuje plik Program.cs projektu AspireSample.AppHost przy użyciu nowego wiersza kodu:

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

Visual Studio narzędzia dodały ten wiersz kodu w celu zarejestrowania nowego projektu za pomocą obiektu IDistributedApplicationBuilder, co umożliwia późniejsze eksplorowanie funkcji aranżacji.

W eksploratorze rozwiązań w Visual Studio Codewybierz przycisk + obok nazwy rozwiązania, aby dodać nowy projekt do rozwiązania:
Aby filtrować szablony projektów, wprowadź Worker w polu wyszukiwania i wybierz znaleziony szablon Worker Service:
Wybierz szablon Worker Service i wprowadź nazwę projektu jako AspireSample.WorkerService.
Wybierz domyślny katalog, aby utworzyć projekt w tym samym katalogu co rozwiązanie.
Wybierz pozycję Utwórz projekt, aby dodać projekt do rozwiązania.
Kliknij prawym przyciskiem myszy projekt AspireSample.AppHost w Eksploratorze rozwiązań i wybierz opcję Dodaj odwołanie do projektu:
Dodaj następujący wiersz kodu do pliku Program.cs w projekcie AspireSample.AppHost przed wywołaniem polecenia builder.Build().Run();:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

W katalogu głównym aplikacji użyj polecenia dotnet new, aby utworzyć nową aplikację Worker Service:
```
dotnet new worker --name AspireSample.WorkerService
```

Użyj polecenia dotnet sln, aby dodać projekt do rozwiązania:

dotnet sln AspireSample.sln add AspireSample.WorkerService/AspireSample.WorkerService.csproj

Użyj polecenia dotnet add, aby dodać odwołanie do projektu między . AppHost i . Projekt WorkerService:

dotnet add AspireSample.AppHost/AspireSample.AppHost.csproj reference AspireSample.WorkerService/AspireSample.WorkerService.csproj

Dodaj następujący wiersz kodu do pliku Program.cs w projekcie AspireSample.AppHost przed wywołaniem polecenia builder.Build().Run();:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

Ukończona struktura rozwiązania powinna przypominać następujące, zakładając, że katalog najwyższego poziomu nosi nazwę aspire-messaging:

└───📂 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

Dodaj integrację .NET.NET Aspire do API

Dodaj integrację .NET Aspire Azure Service Bus do aplikacji AspireSample.ApiService:

W eksploratorze rozwiązań kliknij dwukrotnie plik AspireSample.ApiService.csproj, aby otworzyć jego plik XML.

Dodaj następujący element <PackageReference> do elementu <ItemGroup>:

<ItemGroup>
    <PackageReference Include="Aspire.Azure.Messaging.ServiceBus"
                      Version="8.0.1" />
</ItemGroup>

W eksploratorze rozwiązań kliknij prawym przyciskiem myszy projekt AspireSample.ApiService i wybierz Dodaj pakiet NuGet:
Wprowadź Aspire.Azure. Messaging.ServiceBus w polu wyszukiwania i wybierz pakiet z listy.
Wybierz (najnowszą) wersję, aby zainstalować pakiet.

dotnet add package Aspire.Azure.Messaging.ServiceBus

W pliku Program.cs projektu AspireSample.ApiService dodaj wywołanie metody rozszerzenia AddAzureServiceBusClient — zastępując istniejące wywołanie AddServiceDefaults:

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

Aby uzyskać więcej informacji, zobacz AddAzureServiceBusClient.

Ta metoda wykonuje następujące zadania:

Rejestruje ServiceBusClient w kontenerze DI na potrzeby nawiązywania połączenia z usługą Azure Service Bus.
Automatycznie włącza odpowiednie kontrole kondycji, rejestrowanie i dane telemetryczne dla odpowiednich usług.

W pliku appsettings.json tego samego projektu dodaj odpowiednie informacje o połączeniu:

bez hasła (zalecane)
ciąg połączenia

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

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
          SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

Notatka

Pamiętaj, aby zastąpić {your_namespace} w URI usługi nazwą własnej przestrzeni nazw Service Bus.

Utwórz punkt końcowy interfejsu API

Interfejs API musi zapewnić punkt końcowy do odbierania danych oraz publikowania ich w temacie usługi Service Bus i transmitowania do subskrybentów. Dodaj następujący punkt końcowy do projektu AspireSample.ApiService, aby wysłać komunikat do tematu usługi Service Bus. Zastąp całą zawartość pliku Program.cs następującym kodem c#:

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();

Dodawanie integracji .NET Aspire do Worker Service

Dodaj integrację .NET Aspire Azure Service Bus do projektu AspireSample.WorkerService. Wykonaj te same kroki, co wcześniej po dodaniu pakietu NuGet Aspire.Azure. Messaging.ServiceBus do projektu AspireSample.ApiService . Po dodaniu można skonfigurować usługę pracownika do przetwarzania komunikatów z tematu usługi Service Bus.

W pliku Program.cs projektu AspireSample.WorkerService zamień istniejący kod na następujący:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

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

Metoda AddAzureServiceBusClient wykonuje następujące zadania:

Rejestruje ServiceBusClient w kontenerze DI w celu połączenia z Azure Service Bus.
Automatycznie włącza odpowiednie kontrole kondycji, rejestrowanie i dane telemetryczne dla odpowiednich usług.

W pliku appsettings.json projektu AspireSample.WorkerService dodaj odpowiednie informacje o połączeniu:

bez hasła (zalecane)
ciąg połączeniowy

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

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
        SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

Notatka

Pamiętaj, aby zastąpić {your_namespace} w identyfikatorach URI usługi nazwą własnej przestrzeni nazw usługi Service Bus.

Przetwarzanie komunikatu od subskrybenta

Po umieszczeniu nowego komunikatu w kolejce messages, usługa robocza powinna go pobrać, przetworzyć i usunąć. Zaktualizuj klasę Worker.cs, aby odpowiadała następującemu kodowi:

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;
    }
}

Uruchamianie i testowanie aplikacji lokalnie

Przykładowa aplikacja jest teraz gotowa do testowania. Sprawdź, czy dane przesłane do API są wysyłane do tematu Azure Service Bus i przetwarzane przez usługę pracownika subskrypcji.

Uruchom projekt .NET.NET Aspire, wybierając przycisk Rozpocznij debugowanie lub naciskając F5. Aplikacja pulpitu nawigacyjnego .NET.NET Aspire powinna zostać otwarta w przeglądarce.

Uruchom projekt .NET.NET Aspire, wybierając przycisk Rozpocznij debugowanie lub naciskając F5. Aplikacja pulpitu nawigacyjnego .NET.NET Aspire powinna zostać otwarta w przeglądarce.

Uruchom projekt .NET.NET Aspire, uruchamiając dotnet run --project AspireSample.AppHost. Aplikacja pulpitu nawigacyjnego .NET.NET Aspire powinna zostać otwarta w przeglądarce.

Na stronie zasobów w wierszu apiservice znajdź link w Endpoints, który otwiera punkt końcowy weatherforecast. Zanotuj numer portu HTTPS.
Na panelu sterowania .NET.NET Aspire przejdź do dzienników projektu aspiresample-workerservice.
W oknie terminalu użyj polecenia curl, aby wysłać komunikat testowy do interfejsu API:
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
Pamiętaj, aby zastąpić {port} numerem portu z wcześniejszego.
Wróć do dzienników aspiresample-workerservice. W dziennikach wyjściowych powinien zostać wyświetlony komunikat testowy.

Gratulacje! Utworzono i skonfigurowano interfejs API ASP.NET Core, który łączy się z Azure Service Bus przy użyciu integracji Aspire.

Czyszczenie zasobów

Uruchom następujące polecenie interfejsu wiersza polecenia Azure, aby usunąć grupę zasobów, gdy nie potrzebujesz już zasobów Azure, które utworzyłeś. Usunięcie grupy zasobów powoduje również usunięcie zawartych w niej zasobów.

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

Aby uzyskać więcej informacji, zobacz Oczyszczanie zasobów w Azure.

Udostępnij za pośrednictwem

Samouczek: korzystanie z integracji komunikatów .NET Aspire w ASP.NET Core

Warunki wstępne

Konfigurowanie konta Azure Service Bus

Uwierzytelnianie Azure

Tworzenie przykładowego rozwiązania

Dodawanie projektu Worker Service

Dodaj integrację .NET.NET Aspire do API

Utwórz punkt końcowy interfejsu API

Dodawanie integracji .NET Aspire do Worker Service

Przetwarzanie komunikatu od subskrybenta

Uruchamianie i testowanie aplikacji lokalnie

Czyszczenie zasobów

Dodatkowe zasoby