Handledning: Att använda .NET Aspire meddelandeintegreringar i ASP.NET Core

Artikel
12/15/2024

Molnbaserade appar kräver ofta skalbara meddelandelösningar som tillhandahåller funktioner som meddelandeköer, ämnen och prenumerationer. .NET Aspire integreringar förenklar processen med att ansluta till olika meddelandeleverantörer, till exempel Azure Service Bus. I den här självstudien skapar du en ASP.NET Core-app som använder .NET Aspire-integreringar för att ansluta till Azure Service Bus för att skapa ett meddelandesystem. Skickade meddelanden skickas till ett Servicebuss-ämne för användning av prenumeranter. Du får lära dig att:

Skapa en grundläggande .NET app som är konfigurerad för att använda .NET Aspire integreringar
Lägg till en .NET Aspire-integrering för att ansluta till Azure Service Bus
Konfigurera och använda .NET.NET Aspire integreringsfunktioner för att skicka och ta emot data

Förutsättningar

Om du vill arbeta med .NET.NET Aspirebehöver du följande installerat lokalt:

.NET 8,0 eller .NET 9,0
En OCI-kompatibel containermiljö, till exempel:
- Docker Desktop eller Podman. Mer information finns i Container Runtime.
En IDE (Integrated Developer Environment) eller kodredigerare, till exempel:
- Visual Studio 2022 version 17.9 eller senare (valfritt)
- Visual Studio Code (valfritt)
  - C# Dev Kit: Tillägg (valfritt)
- JetBrains Rider med .NET.NET Aspire plugin- (valfritt)

Mer information finns i .NET.NET Aspire installation och verktygoch .NET.NET Aspire SDK.

Förutom de föregående kraven måste du även installera Azure CLI. Om du vill installera Azure CLI följer du anvisningarna i installationsguiden för Azure CLI.

Konfigurera Azure Service Bus-kontot

I den här guiden behöver du åtkomst till ett Azure Service Bus-namnområde där ett ämne och en prenumeration är konfigurerade. Använd något av följande alternativ för att konfigurera de resurser som krävs:

Azure portalen: Skapa ett Service Bus-konto med ett ämne och en prenumeration.

Alternativt:

Azure CLI: Kör följande kommandon i Azure CLI eller CloudShell för att konfigurera nödvändiga Azure Service Bus resurser:

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

Observera

Ersätt platshållarna ditt resursgrupp-namn och ditt namnutrymme med dina egna värden. Namn på Service Bus-namnområden måste vara globalt unika för Azure.

Azure autentisering

Den här snabbstarten kan slutföras med antingen lösenordslös autentisering eller en anslutningssträng. Lösenordslösa anslutningar använder Azure Active Directory och rollbaserad åtkomstkontroll (RBAC) för att ansluta till ett Service Bus-namnområde. Du behöver inte bekymra dig om att ha hårdkodad anslutningssträng i koden, en konfigurationsfil eller i säker lagring som Azure Key Vault.

Du kan också använda en anslutningssträng för att ansluta till ett Service Bus-namnområde, men den lösenordslösa metoden rekommenderas för verkliga program och produktionsmiljöer. Mer information finns i autentisering och auktorisering eller besök översiktssidan för lösenordsfri inloggning .

lösenordsfri (rekommenderas)
Anslutningssträng

I Service Bus-namnområdet tilldelar du följande roll till det användarkonto som du loggade in på Visual Studio eller Azure CLI med:

Service Bus-dataägare: Tilldela RBAC-roll Azure

Skapa exempellösningen

Om du vill skapa ett nytt .NET Aspire Startprogram kan du använda antingen Visual Studio, Visual Studio Codeeller .NET CLI.

Visual Studio innehåller .NET Aspire mallar som hanterar vissa inledande konfigurationer åt dig. Slutför följande steg för att skapa ett projekt för den här snabbstarten:

Överst i Visual Studionavigerar du till File>New>Project.
I dialogrutan söker du efter Aspire och väljer .NET.NET Aspire Starter App. Välj Nästa.
På skärmen Konfigurera ditt nya projekt:
- Ange ett projektnamn för AspireSample.
- Låt värdenas rest vara som standard och välj Nästa.
På skärmen Ytterligare information:
- Kontrollera att .NET 9.0 (Standard Term Support) har valts.
- Kontrollera att Använd Redis för cachelagring (kräver en stödd container-runtime) är vald och välj Skapa.
- Du kan också välja Skapa ett testprojekt. För mer information, se Skriv din första .NET.NET Aspire test.

Visual Studio skapar en ny lösning som är strukturerad för att använda .NET Aspire.

Visual Studio Code innehåller .NET Aspire projektmallar som hanterar vissa inledande konfigurationer åt dig. Slutför följande steg för att skapa ett projekt för den här snabbstarten:

Från en ny instans av Visual Studio Code (utan en öppen mapp) väljer du knappen Skapa projekt .NET.
Välj mallen .NET.NET Aspire Starter App.

Om du inte redan har installerat .NET.NET Aspire mallarkör du följande dotnet new install kommando:

dotnet new install Aspire.ProjectTemplates

Föregående .NET CLI-kommando ser till att du har .NET Aspire mallar tillgängliga. Om du vill skapa .NET.NET Aspire Starter-appen från mallen kör du följande dotnet new kommando:

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

Mer information finns i dotnet new. .NET CLI skapar en ny lösning som är strukturerad för att använda .NET Aspire.

Lägg till projektet Worker Service

Lägg sedan till ett Worker Service projekt i lösningen för att hämta och bearbeta meddelanden till och från Azure Service Bus.

Högerklicka på den översta nivån AspireSample lösningsnoden i Solution Explorer och välj Lägg till>Nytt projekt.
Sök efter och välj mallen Worker Service och välj Nästa.
För projektnamnet anger du AspireSample.WorkerService och väljer Nästa.
På skärmen Ytterligare information:
- Kontrollera att .NET 9.0 är markerat.
- Kontrollera att Registrera dig till .NET.NET Aspire orkestrering är markerad och välj Skapa.

Visual Studio lägger till projektet i din lösning och uppdaterar Program.cs filen i AspireSample.AppHost-projektet med en ny kodrad:

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

Visual Studio verktyg har lagt till den här kodraden för att registrera ditt nya projekt med IDistributedApplicationBuilder-objektet, vilket möjliggör orkestreringsfunktioner som du kommer att utforska senare.

I Solution Explorer i Visual Studio Codeväljer du knappen + bredvid lösningsnamnet för att lägga till ett nytt projekt i lösningen:
Om du vill filtrera projektmallarna anger du Worker- i sökrutan och väljer den Worker Service mall som finns:
Välj mallen Worker Service och ange projektnamnet som AspireSample.WorkerService.
Välj Standardkatalog för att skapa projektet i samma katalog som lösningen.
Välj Skapa projekt för att lägga till projektet i lösningen.
Högerklicka på projektet AspireSample.AppHost i Solution Explorer och välj Lägg till projektreferens:
Lägg till följande kodrad i filen Program.cs i projektet AspireSample.AppHost innan anropet till builder.Build().Run();:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

I appens rotkatalog använder du kommandot dotnet new för att skapa en ny Worker Service app:
```
dotnet new worker --name AspireSample.WorkerService
```

Använd kommandot dotnet sln för att lägga till projektet i lösningen:

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

Använd kommandot dotnet add för att lägga till en projektreferens mellan . AppHost och . WorkerService projekt:

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

Lägg till följande kodrad i filen Program.cs i projektet AspireSample.AppHost innan anropet till builder.Build().Run();:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

Den färdiga lösningsstrukturen bör likna följande, förutsatt att katalogen på den översta nivån heter 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

Lägg till .NET.NET Aspire-integreringen i API:et

Lägg till .NET Aspire Azure Service Bus-integreringen i AspireSample.ApiService-appen:

I Solution Explorerdubbelklickar du på filen AspireSample.ApiService.csproj för att öppna XML-filen.

Lägg till följande <PackageReference> objekt i elementet <ItemGroup>:

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

I Solution Explorerhögerklickar du på projektet AspireSample.ApiService och väljer Lägg till NuGet-paket:
Ange Aspire.Azure. Messaging.ServiceBus i sökrutan och välj paketet i listan.
Välj den (senaste)-versionen för att installera paketet.

dotnet add package Aspire.Azure.Messaging.ServiceBus

I Program.cs-filen i projektet AspireSample.ApiService lägger du till ett anrop till AddAzureServiceBusClient-tilläggsmetoden och ersätter det befintliga anropet till AddServiceDefaults:

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

Mer information finns i AddAzureServiceBusClient.

Den här metoden utför följande uppgifter:

Registrerar en ServiceBusClient med DI-containern för att ansluta till Azure Service Bus.
Aktiverar automatiskt motsvarande hälsokontroller, loggning och telemetri för respektive tjänster.

Lägg till motsvarande anslutningsinformation i den appsettings.json filen för samma projekt:

lösenordsfri (rekommenderas)
anslutningssträng

{
  // 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"
  }
}

Notera

Ersätt {your_namespace} i tjänstens URI:er med namnet på ditt eget Service Bus-namnområde.

Skapa API-slutpunkten

API:et måste tillhandahålla en slutpunkt för att ta emot data och publicera dem i Service Bus-ämnet och sända dem till prenumeranter. Lägg till följande slutpunkt i projektet AspireSample.ApiService för att skicka ett meddelande till Service Bus-ämnet. Ersätt allt innehåll i Program.cs-filen med följande C#-kod:

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

Lägg till .NET Aspire-integreringen i Worker Service

Lägg till .NET Aspire Azure Service Bus-integreringen i projektet AspireSample.WorkerService. Följ samma steg som du gjorde tidigare när du lade till Aspire.Azure. Messaging.ServiceBus NuGet-paketet till projektet AspireSample.ApiService. När den har lagts till kan du konfigurera arbetstjänsten för att bearbeta meddelanden från Service Bus-ämnet.

I Program.cs-filen i projektet AspireSample.WorkerService kan du ange den befintliga koden på nytt med följande:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

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

Metoden AddAzureServiceBusClient utför följande uppgifter:

Registrerar en ServiceBusClient i DI-behållaren för att ansluta till Azure Service Bus.
Aktiverar automatiskt motsvarande hälsokontroller, loggning och telemetri för respektive tjänster.

Lägg till motsvarande anslutningsinformation i appsettings.json-filen i projektet AspireSample.WorkerService:

lösenordsfri (rekommenderas)
anslutningssträng

{
  // 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"
  }
}

Not

Ersätt {your_namespace} i tjänst-URI:erna med namnet på ditt eget Service Bus-namnområde.

Bearbeta meddelandet från prenumeranten

När ett nytt meddelande placeras i kön messages ska arbetstjänsten hämta, bearbeta och ta bort meddelandet. Uppdatera klassen Worker.cs så att den matchar följande kod:

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

Köra och testa appen lokalt

Exempelappen är nu redo för testning. Kontrollera att data som är skickade till API:et skickas till Azure Service Bus ämnesområdet och används av prenumerantjänstens arbetare.

Starta projektet .NET.NET Aspire genom att välja knappen Starta felsökning eller genom att trycka på F5. Appen .NET.NET Aspire instrumentpanelsapp bör öppnas i webbläsaren.

Starta .NET.NET Aspire genom att välja knappen Starta felsökning eller genom att trycka på F5. Den .NET.NET Aspire dashboard-applikation bör öppnas i webbläsaren.

Starta .NET.NET Aspire-projektet genom att köra dotnet run --project AspireSample.AppHost. Appen .NET.NET Aspire instrumentpanel bör öppnas i webbläsaren.

På resurssidan går du till raden apiservice och letar upp länken i Slutpunkter som öppnar weatherforecast slutpunkten. Observera HTTPS-portnumret.
På instrumentpanelen .NET.NET Aspire navigerar du till loggarna för aspiresample-workerservice-projektet.
I ett terminalfönster använder du kommandot curl för att skicka ett testmeddelande till API:et:
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
Ersätt {port} med portnumret från tidigare.
Växla tillbaka till aspiresample-workerservice loggar. Du bör se testmeddelandet som skrivs ut i utdataloggarna.

Grattis! Du har skapat och konfigurerat ett ASP.NET Core API som ansluter till Azure Service Bus med hjälp av Aspire integreringar.

Rensa resurser

Kör följande Azure CLI-kommando för att ta bort resursgruppen när du inte längre behöver de Azure resurser som du skapade. Om du tar bort resursgruppen tas även de resurser som ingår i den bort.

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

Mer information finns i Rensa resurser i Azure.

Dela via