Kurz: Použití integrace zasílání zpráv .NET Aspire v ASP.NET Core

Článek
12/15/2024

Nativní cloudové aplikace často vyžadují škálovatelná řešení zasílání zpráv, která poskytují možnosti, jako jsou fronty zpráv a témata a odběry. .NET Aspire integrace zjednodušují proces připojování k různým poskytovatelům zasílání zpráv, například Azure Service Bus. V tomto kurzu vytvoříte aplikaci ASP.NET Core, která k vytvoření systému oznámení používá integrace .NET Aspire pro připojení k Azure Service Bus. Odeslané zprávy se odesílají do tématu služby Service Bus, aby je mohli používat předplatitelé. Naučíte se:

Vytvořte základní .NET aplikaci, která je nastavená pro použití integrací .NET Aspire
Přidání integrace .NET Aspire pro připojení k Azure Service Bus
Konfigurace a používání funkcí integrace .NET.NET Aspire k odesílání a příjmu dat

Požadavky

Pokud chcete pracovat s .NET.NET Aspire, potřebujete místně nainstalovat následující:

.NET 8.0 nebo .NET 9.0
Modul runtime kontejneru kompatibilní s OCI, například:
- Docker desktopové nebo Podman. Pro více informací viz runtime kontejneru.
Integrované vývojové prostředí (IDE) nebo editor kódu, například:
- Visual Studio 2022 verze 17.9 nebo novější (volitelné)
- Visual Studio Code (volitelné)
  - C# Dev Kit: Rozšíření (volitelné)
- JetBrains Rider s .NET.NET Aspire pluginem (volitelně)

Další informace najdete v tématu .NET.NET Aspire nastavení a nástrojea .NET.NET Aspire SDK.

Kromě předchozích požadavků musíte také nainstalovat Azure rozhraní příkazového řádku. Pokud chcete nainstalovat rozhraní příkazového řádku Azure, postupujte podle pokynů v průvodci instalací rozhraní příkazového řádku Azure.

Nastavení účtu Azure Service Bus

Pro účely tohoto kurzu budete potřebovat přístup k oboru názvů Azure Service Bus s nakonfigurovaným tématem a předplatným. K nastavení požadovaných prostředků použijte jednu z následujících možností:

portál : Vytvořte účet služby Service Bus s tématem a předplatným.

Alternativně:

Azure rozhraní příkazového řádku: Pro nastavení požadovaných Azure Service Bus prostředků spusťte následující příkazy v Azure CLI nebo v CloudShell:

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

Poznámka

Nahraďte zástupné symboly název skupiny prostředků a název oboru názvů vlastními hodnotami. Názvy služby Service Bus musí být globálně jedinečné v rámci Azure.

ověřování Azure

Tento rychlý start je možné dokončit pomocí ověřování bez hesla nebo připojovacího řetězce. Připojení bez hesla používají Azure Active Directory a řízení přístupu na základě role (RBAC) pro připojení k oboru názvů služby Service Bus. Nemusíte si dělat starosti s pevně zakódovaným připojovacím řetězcem v kódu, konfiguračním souborem nebo v zabezpečeném úložišti, jako je Azure Key Vault.

Můžete také použít připojovací řetězec pro připojení k oboru názvů služby Service Bus, ale pro reálné aplikace a produkční prostředí se doporučuje přístup bez hesla. Další informace najdete v tématu o ověřování a autorizaci nebo navštivte stránku přehledu bez hesla.

bez hesla (doporučeno)
připojovacího řetězce

Ve vašem oboru názvů služby Service Bus přiřaďte následující roli uživatelskému účtu, se kterým jste se přihlásili pomocí Visual Studio nebo rozhraní příkazového řádku Azure:

Vlastník dat služby Service Bus: Přiřazení role Azure RBAC

Vytvoření ukázkového řešení

Pokud chcete vytvořit novou úvodní aplikaci .NET Aspire, můžete použít Visual Studio, Visual Studio Codenebo rozhraní příkazového řádku .NET.

Visual Studio poskytuje šablony .NET Aspire, které za vás zpracovávají některé počáteční konfigurace nastavení. Pomocí následujících kroků vytvořte projekt pro tento rychlý start:

V horní části Visual Studiopřejděte na Soubor>Nový projekt>.
V dialogovém okně vyhledejte Aspire a vyberte .NET.NET Aspire úvodní aplikaci. Vyberte Další.
Na obrazovce Konfigurujte svůj nový projekt:
- Zadejte název projektu AspireSample .
- Ponechte rest hodnot ve výchozím nastavení a vyberte Další.
Na obrazovce Další informace:
- Ujistěte se, že je vybraná .NET 9.0 (standardní podpora termínů).
- Ujistěte se, že je zaškrtnuté políčko Použít Redis pro ukládání do mezipaměti (vyžaduje podporovaný modul runtime kontejneru) a vyberte Vytvořit.
- Volitelně můžete vybrat Vytvořit projekt testů. Další informace viz Napište svůj první .NET.NET Aspire test.

Visual Studio vytvoří nové řešení strukturované pro použití .NET Aspire.

Visual Studio Code poskytuje .NET Aspire šablony projektu, které zpracovávají některé počáteční konfigurace nastavení za vás. Pomocí následujících kroků vytvořte projekt pro tento rychlý start:

V nové instanci Visual Studio Code (bez otevřené složky) vyberte tlačítko Vytvořit projekt .NET.
Vyberte šablonu .NET.NET Aspire Starter App.

Pokud jste ještě nenainstalovali šablony .NET.NET Aspire, spusťte příkaz dotnet new install:

dotnet new install Aspire.ProjectTemplates

Předchozí příkaz rozhraní příkazového řádku .NET zajistí, že máte k dispozici .NET Aspire šablony. Pokud chcete ze šablony vytvořit .NET.NET Aspire úvodní aplikaci, spusťte následující příkaz dotnet new:

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

Další informace najdete v tématu dotnet new. Rozhraní příkazového řádku .NET vytvoří nové řešení, které je strukturováno pro použití .NET Aspire.

Přidání projektu Worker Service

Dále do řešení přidejte projekt Worker Service pro načtení a zpracování zpráv do a z Azure Service Bus.

V Průzkumníku řešení klikněte pravým tlačítkem na uzel AspireSample řešení nejvyšší úrovně a vyberte Přidat>Nový projekt.
Vyhledejte a vyberte šablonu Worker Service a zvolte Další.
Jakonázev projektu zadejte AspireSample.WorkerService a vyberte Další.
Na obrazovce Další informace:
- Ujistěte se, že je vybraná .NET 9.0.
- Ujistěte se, že máte zaškrtnuté Zařazení do .NET.NET Aspire orchestrace a vyberte Vytvořit.

Visual Studio projekt přidá do řešení a aktualizuje soubor Program.cs projektu AspireSample.AppHost novým řádkem kódu:

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

Visual Studio nástroji přidali tento řádek kódu pro registraci nového projektu do objektu IDistributedApplicationBuilder, který umožňuje funkce orchestrace, které prozkoumáte později.

V průzkumníku řešení v Visual Studio Codevyberte tlačítko + vedle názvu řešení a přidejte do řešení nový projekt:
Pokud chcete filtrovat šablony projektů, zadejte do vyhledávacího pole Worker a vyberte šablonu, která se našla:
Zvolte šablonu Worker Service a zadejte název projektu jako AspireSample.WorkerService.
Vyberte Výchozí adresář a vytvořte projekt ve stejném adresáři jako řešení.
Vyberte Vytvořit projekt a přidejte projekt do řešení.
Klikněte pravým tlačítkem na projekt AspireSample.AppHost v Průzkumníku Řešení a vyberte Přidat referenci projektu:
Před voláním builder.Build().Run();přidejte následující řádek kódu do souboru Program.cs v AspireSample.AppHost projektu:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

V kořenovém adresáři aplikace pomocí příkazu dotnet new vytvořte novou aplikaci Worker Service:
```
dotnet new worker --name AspireSample.WorkerService
```

Pomocí příkazu dotnet sln přidejte projekt do řešení:

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

Pomocí příkazu dotnet add přidejte referenci mezi projektem .AppHost a projektem .WorkerService.

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

Před voláním builder.Build().Run();přidejte následující řádek kódu do souboru Program.cs v AspireSample.AppHost projektu:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

Dokončená struktura řešení by měla vypadat podobně jako následující, za předpokladu, že adresář nejvyšší úrovně má název 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

Přidání integrace .NET.NET Aspire do rozhraní API

Přidejte integraci .NET Aspire Azure Service Bus do aplikace AspireSample.ApiService:

Ve Průzkumníku řešení dvakrát klikněte na soubor AspireSample.ApiService.csproj, čímž se otevře jeho XML obsah.

Do elementu <ItemGroup> přidejte následující položku <PackageReference>:

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

V Průzkumníku řešeníklikněte pravým tlačítkem na projekt AspireSample.ApiService a vyberte Přidat balíček NuGet:
Zadejte Aspire.Azure. Messaging.ServiceBus do vyhledávacího pole a vyberte balíček ze seznamu.
Vyberte (nejnovější) verzi a nainstalujte balíček.

dotnet add package Aspire.Azure.Messaging.ServiceBus

V souboru Program.cs projektu AspireSample.ApiService přidejte volání metody rozšíření AddAzureServiceBusClient – nahraďte stávající volání AddServiceDefaults.

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

Další informace najdete v tématu AddAzureServiceBusClient.

Tato metoda provádí následující úlohy:

Zaregistruje ServiceBusClient v kontejneru DI pro připojení k Azure Service Bus.
Automaticky povolí odpovídající kontroly stavu, protokolování a telemetrii pro příslušné služby.

Do souboru appsettings.json stejného projektu přidejte odpovídající informace o připojení:

bez hesla (doporučeno)
Připojovací řetězec

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

Poznámka

Nezapomeňte v identifikátorech URI služby nahradit {your_namespace} názvem vašeho vlastního oboru názvů pro Service Bus.

Vytvoření koncového bodu rozhraní API

Rozhraní API musí poskytnout koncový bod pro příjem dat, jejich publikování do tématu v Service Bus a jejich vysílání odběratelům. Do projektu AspireSample.ApiService přidejte následující koncový bod, který odešle zprávu do tématu služby Service Bus. Veškerý obsah souboru Program.cs nahraďte následujícím kódem jazyka 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();

Přidání integrace .NET Aspire do Worker Service

Přidejte integraci .NET Aspire Azure Service Bus do projektu AspireSample.WorkerService. Postupujte stejně jako předtím, když jste přidali Aspire.Azure. Messaging.ServiceBus balíček NuGet do projektu AspireSample.ApiService. Po přidání můžete službu pracovního procesu nakonfigurovat tak, aby zpracovávala zprávy z tématu služby Service Bus.

V souboru Program.cs projektu AspireSample.WorkerService znovu vytvořte existující kód následujícím kódem:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

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

Metoda AddAzureServiceBusClient provádí následující úlohy:

Zaregistruje ServiceBusClient v kontejneru DI pro připojení k Azure Service Bus.
Automaticky povolí odpovídající kontroly stavu, protokolování a telemetrii pro příslušné služby.

Do souboru appsettings.json projektu AspireSample.WorkerService přidejte odpovídající informace o připojení:

bez hesla (doporučeno)
Připojovací řetězec

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

Poznámka

Nezapomeňte nahradit {your_namespace} v URI služby názvem vašeho vlastního oboru názvů ve službě Service Bus.

Zpracování zprávy od odběratele

Když se do fronty messages umístí nová zpráva, měla by pracovní služba načíst, zpracovat a odstranit zprávu. Aktualizujte třídu Worker.cs tak, aby odpovídala následujícímu kódu:

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

Místní spuštění a otestování aplikace

Ukázková aplikace je teď připravená k testování. Ověřte, že se data odesílaná do rozhraní API dostávají do tématu Azure Service Bus a jsou zpracovávána službou odběratele pracovníka.

Spusťte projekt .NET.NET Aspire výběrem tlačítka ladění Spustit nebo stisknutím klávesy F5. Aplikace řídicího panelu .NET.NET Aspire by se měla otevřít v prohlížeči.

Spusťte projekt .NET.NET Aspire výběrem tlačítka ladění Spustit nebo stisknutím klávesy F5. Aplikace řídicího panelu .NET.NET Aspire by se měla otevřít v prohlížeči.

Spusťte projekt .NET.NET Aspire spuštěním dotnet run --project AspireSample.AppHost. Aplikace řídicího panelu .NET.NET Aspire by se měla otevřít v prohlížeči.

Na stránce zdrojů v řádku apiservice vyhledejte odkaz v koncových bodech, který otevře koncový bod weatherforecast. Poznamenejte si číslo portu HTTPS.
Na řídicím panelu .NET.NET Aspire přejděte do protokolů pro aspiresample-workerservice projektu.
V okně terminálu použijte příkaz curl k odeslání testovací zprávy do rozhraní API:
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
Nezapomeňte nahradit {port} číslem portu z předchozích verzí.
Přepněte zpět na protokoly aspiresample-workerservice. Ve výstupních protokolech by se měla zobrazit testovací zpráva.

Blahopřejeme! Vytvořili jste a nakonfigurovali rozhraní API ASP.NET Core, které se připojuje k Azure Service Bus pomocí integrace Aspire.

Vyčištění prostředků

Spuštěním následujícího příkazu rozhraní příkazového řádku Azure odstraňte skupinu prostředků, pokud už nepotřebujete Azure prostředky, které jste vytvořili. Odstraněním skupiny prostředků se odstraní také prostředky obsažené v této skupině.

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

Další informace najdete v tématu Vyčištění prostředků v Azure.

Sdílet prostřednictvím

Kurz: Použití integrace zasílání zpráv .NET Aspire v ASP.NET Core

Požadavky

Nastavení účtu Azure Service Bus

ověřování Azure

Vytvoření ukázkového řešení

Přidání projektu Worker Service

Přidání integrace .NET.NET Aspire do rozhraní API

Vytvoření koncového bodu rozhraní API

Přidání integrace .NET Aspire do Worker Service

Zpracování zprávy od odběratele

Místní spuštění a otestování aplikace

Vyčištění prostředků

Další materiály