Anleitung: Nutzung von .NET Aspire-Messaging-Integrationen in ASP.NET Core
Cloud-native-Apps erfordern häufig skalierbare Messaging-Lösungen, die Funktionen wie Messagingwarteschlangen sowie Themen und Abonnements umfassen. .NET Aspire Integrationen vereinfachen die Verbindung mit verschiedenen Messaging-Anbietern, z. B. Azure Service Bus. In diesem Tutorial erstellen Sie eine ASP.NET Core App, die .NET Aspire Integrationen verwendet, um eine Verbindung mit Azure Service Bus herzustellen und ein Benachrichtigungssystem zu erstellen. Gesendete Nachrichten werden an ein Service Bus-Thema gesendet, das von Abonnenten verwendet werden kann. Hier erfahren Sie, wie Sie:
- Erstellen Sie eine einfache .NET-App, die eingerichtet ist, um .NET Aspire-Integrationen zu verwenden.
- Hinzufügen einer .NET Aspire Integration zum Herstellen einer Verbindung mit Azure Service Bus
- Konfigurieren Sie und verwenden Sie .NET.NET Aspire Integrationsfeatures zum Senden und Empfangen von Daten
Voraussetzungen
Um mit .NET.NET Aspirezu arbeiten, benötigen Sie folgendes lokal installiert:
- .NET 8.0 oder .NET 9,0
- Eine OCI-kompatible Container-Runtime, zum Beispiel:
- Docker Desktop oder Podman. Weitere Informationen finden Sie unter container runtime.
- Eine integrierte Entwicklerumgebung (Integrated Developer Environment, IDE) oder ein Code-Editor, z. B.:
- Visual Studio 2022 Version 17.9 oder höher (optional)
-
Visual Studio Code (optional)
- C# Dev Kit: Erweiterung (Optional)
- JetBrains Rider mit .NET.NET Aspire Plug-in (Optional)
Weitere Informationen finden Sie unter .NET.NET Aspire Setup und Toolingund .NET.NET Aspire SDK-.
Zusätzlich zu den vorherigen Voraussetzungen müssen Sie auch die Azure CLI installieren. Um die Azure CLI zu installieren, befolgen Sie die Anweisungen im Azure CLI-Installationshandbuch.
Einrichten des Kontos Azure Service Bus
Für dieses Tutorial benötigen Sie Zugriff auf einen „Azure Service Bus-Namespace“ mit konfiguriertem Thema und einem Abonnement. Verwenden Sie eine der folgenden Optionen, um die erforderlichen Ressourcen einzurichten:
- Azure Portal-: Erstellen eines Servicebuskontos mit einem Thema und Abonnement.
Alternativ:
Azure CLI-: Führen Sie die folgenden Befehle in der Azure CLI oder in CloudShell aus, um die erforderlichen Azure Service Bus-Ressourcen einzurichten.
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 mobileAnmerkung
Ersetzen Sie die Platzhalter your-resource-group-name und your-namespace-name durch Ihre eigenen Werte. ServiceBus-Namensraum-Namen müssen global eindeutig für Azuresein.
Azure Authentifizierung
Dieser Schnellstart kann mit entweder kennwortloser Authentifizierung oder einer Verbindungszeichenfolge abgeschlossen werden. Passwortlose Verbindungen verwenden Azure Active Directory und rollenbasierte Zugriffssteuerung (RBAC), um sich mit einem Service Bus-Namespace zu verbinden. Sie müssen sich keine Gedanken darüber machen, dass Sie eine hartcodierte Verbindungszeichenfolge im Code, in einer Konfigurationsdatei oder in sicherem Speicher wie Azure Key Vaulthaben.
Sie können auch eine Verbindungszeichenfolge verwenden, um eine Verbindung mit einem Service Bus-Namespace herzustellen, aber der kennwortlose Ansatz wird für reale Anwendungen und Produktionsumgebungen empfohlen. Weitere Informationen finden Sie unter Authentifizierung und Autorisierung oder besuchen Sie die kennwortlose Übersichtsseite.
Weisen Sie dem Benutzerkonto, mit dem Sie sich bei Visual Studio angemeldet haben, oder der Azure CLI auf Ihrem Service Bus-Namespace die folgende Rolle zu:
- Service Bus-Datenbesitzer: Zuweisen einer Azure RBAC-Rolle
Erstellen der Beispiellösung
Um eine neue .NET Aspire Starter-Anwendung zu erstellen, können Sie entweder Visual Studio, Visual Studio Codeoder die .NET CLI verwenden.
Visual Studio stellt .NET Aspire Vorlagen bereit, die einige anfängliche Konfigurationen für Sie übernehmen. Führen Sie die folgenden Schritte aus, um ein Projekt für diesen Schnellstart zu erstellen.
Navigieren Sie oben in Visual Studiozu Datei>Neues>Projekt.
Suchen Sie im Dialogfeld nach Aspire, und wählen Sie .NET.NET Aspire Starter-Appaus. Wählen Sie Weiteraus.
Auf dem Bildschirm "Konfigurieren des neuen Projekts":
- Geben Sie einen Projektnamen vom AspireSampleein.
- Behalten Sie den rest der Werte bei ihren Standardwerten bei, und wählen Sie Weiteraus.
Auf dem Bildschirm Zusätzliche Informationen:
- Stellen Sie sicher, dass .NET 9.0 (Standard-Term-Support) ausgewählt ist.
- Stellen Sie sicher, dass Redis für die Zwischenspeicherung verwenden (erfordert eine unterstützte Containerlaufzeit), aktiviert ist, und wählen Sie Erstellenaus.
- Optional können Sie Erstellen eines Testprojektsauswählen. Weitere Informationen finden Sie unter Schreiben des ersten .NET.NET Aspire Tests.
Visual Studio erstellt eine neue Lösung, die dafür ausgelegt ist, .NET Aspirezu verwenden.
Visual Studio Code stellt .NET Aspire Projektvorlagen bereit, die einige anfängliche Erstkonfigurationen für Sie übernehmen. Führen Sie die folgenden Schritte aus, um ein Projekt für diesen Schnellstart zu erstellen.
Wählen Sie in einer neuen Instanz von Visual Studio Code (Ohne einen Ordner geöffnet) die Schaltfläche Projekt .NET erstellen aus.
Wählen Sie die Vorlage .NET.NET Aspire Starter App aus.
Wenn Sie die .NET.NET Aspire Vorlagennoch nicht installiert haben, führen Sie den folgenden dotnet new install Befehl aus:
dotnet new install Aspire.ProjectTemplates
Der obige .NET CLI-Befehl stellt sicher, dass die .NET Aspire Vorlagen verfügbar sind. Führen Sie den folgenden dotnet new Befehl aus, um die .NET.NET Aspire Starter-App aus der Vorlage zu erstellen:
dotnet new aspire-starter --use-redis-cache --output AspireSample
Weitere Informationen finden Sie unter dotnet new. Die .NET CLI erstellt eine neue Lösung, die so strukturiert ist, dass sie .NET Aspireverwendet.
Fügen Sie das Projekt Worker Service hinzu
Fügen Sie als Nächstes der Lösung ein Projekt Worker Service hinzu, um Nachrichten an und von Azure Service Busabzurufen und zu verarbeiten.
- Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Knoten der obersten Ebene
AspireSampleLösung, und wählen Sie Hinzufügen>Neues Projektaus. - Suchen und wählen Sie die Worker Service Vorlage aus, und wählen Sie Weiteraus.
- Geben Sie für den ProjektnamenAspireSample.WorkerService ein, und wählen Sie Nextaus.
- Auf dem Bildschirm Zusätzliche Informationen:
- Stellen Sie sicher, dass .NET 9,0 ausgewählt ist.
- Stellen Sie sicher, dass Enlist in .NET.NET Aspire Orchestrierung aktiviert ist, und wählen Sie Createaus.
Visual Studio fügt das Projekt zu Ihrer Lösung hinzu und aktualisiert die Program.cs Datei des AspireSample.AppHost Projekts mit einer neuen Codezeile:
builder.AddProject<Projects.AspireSample_WorkerService>(
"aspiresample-workerservice");
Das Visual Studio-Werkzeug fügte diese Codezeile hinzu, um Ihr neues Projekt mit dem IDistributedApplicationBuilder-Objekt zu registrieren, wodurch Orchestrierungsfunktionen aktiviert werden, die Sie später erkunden werden.
Wählen Sie im Lösungsexplorer in Visual Studio Codedie Schaltfläche + neben dem Namen der Lösung aus, um der Lösung ein neues Projekt hinzuzufügen:
Um die Projektvorlagen zu filtern, geben Sie Worker - in das Suchfeld ein und wählen Sie die Worker Service Vorlage aus, die gefunden wurde.
Wählen Sie die Worker Service Vorlage aus, und geben Sie den Projektnamen als AspireSample.WorkerServiceein.
Wählen Sie Standardverzeichnis aus, um das Projekt im selben Verzeichnis wie die Lösung zu erstellen.
Wählen Sie Projekt erstellen aus, um das Projekt der Lösung hinzuzufügen.
Klicken Sie mit der rechten Maustaste auf das Projekt AspireSample.AppHost im Projektmappen-Explorer und wählen Sie Projektverweis hinzufügenaus.
Fügen Sie der Datei Program.cs im AspireSample.AppHost--Projekt vor dem Aufruf von
builder.Build().Run();die folgende Code-Zeile hinzu.builder.AddProject<Projects.AspireSample_WorkerService>( "aspiresample-workerservice");
Verwenden Sie im Stammverzeichnis der App den Befehl dotnet new, um eine neue Worker Service-App zu erstellen.
dotnet new worker --name AspireSample.WorkerServiceVerwenden Sie den Befehl
dotnet sln, um das Projekt der Projektmappe hinzuzufügen:dotnet sln AspireSample.sln add AspireSample.WorkerService/AspireSample.WorkerService.csprojVerwenden Sie den Befehl
dotnet add, um einen Projektverweis zwischen dem .AppHost und dem .WorkerService Projekt hinzuzufügen.dotnet add AspireSample.AppHost/AspireSample.AppHost.csproj reference AspireSample.WorkerService/AspireSample.WorkerService.csprojFügen Sie der Datei Program.cs im AspireSample.AppHost--Projekt vor dem Aufruf von
builder.Build().Run();die folgende Codezeile hinzu.builder.AddProject<Projects.AspireSample_WorkerService>( "aspiresample-workerservice");
Die fertige Lösungsstruktur sollte wie folgt aussehen, vorausgesetzt, das Verzeichnis der obersten Ebene heißt 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
Fügen Sie die .NET.NET Aspire-Integration zur API hinzu.
Fügen Sie die .NET Aspire Azure Service Bus-Integration zu Ihrer AspireSample.ApiService-Anwendung hinzu.
Doppelklicken Sie im Projektmappen-Explorerauf die Datei AspireSample.ApiService.csproj, um deren XML-Datei zu öffnen.
Fügen Sie dem
<ItemGroup>-Element das folgende<PackageReference>-Element hinzu.<ItemGroup> <PackageReference Include="Aspire.Azure.Messaging.ServiceBus" Version="8.0.1" /> </ItemGroup>
Klicken Sie im Projektmappen-Explorermit der rechten Maustaste auf das Projekt AspireSample.ApiService, und wählen Sie NuGet-Paket hinzufügenaus:
Geben Sie Aspire.Azure. Messaging.ServiceBus im Suchfeld ein und wählen Sie das Paket aus der Liste aus.
Wählen Sie die (neueste) Version aus, um das Paket zu installieren.
dotnet add package Aspire.Azure.Messaging.ServiceBus
Fügen Sie in der datei Program.cs des Projekts AspireSample.ApiService einen Aufruf der AddAzureServiceBusClient Erweiterungsmethode hinzu, wobei der vorhandene Aufruf von AddServiceDefaultsersetzt wird:
// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");
Weitere Informationen finden Sie unter AddAzureServiceBusClient.
Diese Methode erledigt die folgenden Aufgaben:
- Registriert eine ServiceBusClient mit dem DI-Container, um eine Verbindung mit Azure Service Busherzustellen.
- Aktiviert automatisch entsprechende Gesundheitsprüfungen, Protokollierung und Telemetrie für die jeweiligen Dienste.
Fügen Sie in der datei appsettings.json desselben Projekts die entsprechenden Verbindungsinformationen hinzu:
{
// Existing configuration is omitted for brevity.
"ConnectionStrings": {
"serviceBusConnection": "{your_namespace}.servicebus.windows.net"
}
}
Anmerkung
Ersetzen Sie unbedingt {your_namespace} in den Dienst-URIs durch den Namen Ihres eigenen Service Bus-Namespace.
Erstellen des API-Endpunkts
Die API muss einen Endpunkt bereitstellen, um Daten zu empfangen, sie im Service Bus Topic zu veröffentlichen und an Abonnenten zu übertragen. Fügen Sie den folgenden Endpunkt zum AspireSample.ApiService Projekt hinzu, um eine Nachricht an das Thema ServiceBus zu senden. Ersetzen Sie den gesamten Inhalt der datei Program.cs durch den folgenden C#-Code:
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();
Hinzufügen der .NET Aspire-Integration zum Worker Service
Fügen Sie die .NET Aspire Azure Service Bus Integration zu Ihrem AspireSample.WorkerService Projekt hinzu. Führen Sie die gleichen Schritte wie zuvor aus, als Sie das NuGet-Paket Aspire.Azure.Messaging.ServiceBus zum Projekt AspireSample.ApiService hinzugefügt hatten. Nachdem er hinzugefügt wurde, können Sie den Workerdienst so konfigurieren, dass Nachrichten aus dem Thema "Service Bus" verarbeitet werden.
Ersetzen Sie im Program.cs-Datei des AspireSample.WorkerService Projekts den vorhandenen Code durch den folgenden.
using AspireSample.WorkerService;
var builder = Host.CreateApplicationBuilder(args);
builder.AddAzureServiceBusClient("serviceBusConnection");
builder.Services.AddHostedService<Worker>();
var host = builder.Build();
host.Run();
Die AddAzureServiceBusClient-Methode führt die folgenden Aufgaben aus:
- Registriert ServiceBusClient beim DI-Container, um eine Verbindung zu Azure Service Busherzustellen.
- Automatisch werden die entsprechenden Gesundheitsprüfungen, die Protokollierung und die Telemetrie für die jeweiligen Dienste aktiviert.
Fügen Sie in der Datei appsettings.json des Projekts AspireSample.WorkerService die entsprechenden Verbindungsinformationen hinzu.
{
// Existing configuration is omitted for brevity.
"ConnectionStrings": {
"serviceBusConnection": "{your_namespace}.servicebus.windows.net"
}
}
Anmerkung
Ersetzen Sie unbedingt {your_namespace} in den Dienst-URIs durch den Namen Ihres eigenen Service Bus-Namespace.
Verarbeite die Nachricht vom Abonnenten
Wenn eine neue Nachricht in der Warteschlange messages platziert wird, soll der Workerdienst die Nachricht abrufen, verarbeiten und löschen. Aktualisieren Sie die Worker.cs Klasse so, dass sie dem folgenden Code entspricht:
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;
}
}
Lokales Ausführen und Testen der App
Die Beispiel-App kann jetzt getestet werden. Stellen Sie sicher, dass die an die API übermittelten Daten an das Thema Azure Service Bus gesendet und vom Abonnenten-Workerdienst genutzt werden:
- Starten Sie das .NET.NET Aspire Projekt, indem Sie die Schaltfläche Debugging starten auswählen, oder indem Sie F5drücken. Die .NET.NET Aspire Dashboard-App sollte im Browser geöffnet werden.
- Starten Sie das .NET.NET Aspire-Projekt, indem Sie die Schaltfläche Debuggen starten auswählen oder F5drücken. Die .NET.NET Aspire Dashboard-App sollte im Browser geöffnet werden.
- Starten Sie das .NET.NET Aspire Projekt, indem Sie
dotnet run --project AspireSample.AppHostausführen. Die .NET.NET Aspire Dashboard-App sollte im Browser geöffnet werden.
Suchen Sie auf der Ressourcenseite in der Zeile des apiservice den Link in dem Endpoint, der den
weatherforecastEndpunkt öffnet. Notieren Sie sich die HTTPS-Portnummer.Navigieren Sie im dashboard .NET.NET Aspire zu den Protokollen für das aspiresample-workerservice Projekt.
Verwenden Sie in einem Terminalfenster den Befehl
curl, um eine Testnachricht an die API zu senden:curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspireErsetzen Sie unbedingt {port} mit der zuvor angegebenen Portnummer.
Wechseln Sie zurück zu den aspiresample-workerservice Protokoll. Die Testmeldung soll in den Ausgabeprotokollen angezeigt werden.
Glückwunsch! Sie haben eine ASP.NET Core-API erstellt und konfiguriert, die mithilfe von Aspire Integrationen eine Verbindung mit Azure Service Bus herstellt.
Bereinigen von Ressourcen
Führen Sie den folgenden Azure CLI-Befehl aus, um die Ressourcengruppe zu löschen, wenn Sie die von Ihnen erstellten Azure Ressourcen nicht mehr benötigen. Durch das Löschen der Ressourcengruppe werden auch die darin enthaltenen Ressourcen gelöscht.
az group delete --name <your-resource-group-name>
Weitere Informationen finden Sie unter Ressourcen bereinigen in Azure.
