Esercitazione: Utilizzare le integrazioni di messaggistica di .NET Aspire in ASP.NET Core

Articolo
12/15/2024

Le applicazioni cloud-native spesso richiedono soluzioni di messaggistica scalabili che offrono funzionalità come code di messaggi, temi e abbonamenti. Le integrazioni .NET Aspire semplificano il processo di connessione ai vari provider di messaggistica, come Azure Service Bus. In questa esercitazione si creerà un'app ASP.NET Core che usa integrazioni .NET Aspire per connettersi a Azure Service Bus per creare un sistema di notifica. I messaggi inviati verranno spediti a un topic di Service Bus affinché gli abbonati possano consumarli. Si apprenderà come:

Creare un’app di base .NET configurata per utilizzare le integrazioni .NET Aspire
Aggiungere un'integrazione .NET Aspire per connettersi a Azure Service Bus
Configurare e utilizzare le funzionalità di integrazione .NET.NET Aspire per inviare e ricevere dati

Prerequisiti

Per usare .NET.NET Aspire, è necessario che il codice seguente sia installato in locale:

.NET 8.0 o .NET 9.0
Un runtime conforme a OCI per i contenitori, ad esempio:
- Docker Desktop o Podman. Per ulteriori informazioni, vedere Runtime del container.
Un ambiente di sviluppo integrato (IDE) o un editor di codice, ad esempio:
- Visual Studio 2022 versione 17.9 o successiva (opzionale)
- Visual Studio Code (facoltativo)
  - C# Dev Kit: Estensione (Facoltativo)
- JetBrains Rider con .NET.NET Aspire plugin (facoltativo)

Per altre informazioni, vedere .NET.NET Aspire configurazione e strumentie .NET.NET Aspire SDK.

Oltre ai prerequisiti precedenti, è anche necessario installare l'interfaccia della riga di comando Azure. Per installare l'interfaccia della riga di comando di Azure, seguire le istruzioni riportate nella guida all'installazione dell'interfaccia della riga di comando di Azure.

Configurare l'account Azure Service Bus

Per questa esercitazione è necessario accedere a uno spazio dei nomi Azure Service Bus con un argomento e una sottoscrizione configurati. Usare una delle opzioni seguenti per configurare le risorse necessarie:

Azure portale: Creare un account del bus di servizio con un argomento e una sottoscrizione.

Alternativamente:

Azure CLI: eseguire i seguenti comandi nella CLI di Azure o in CloudShell per configurare le risorse necessarie 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

Nota

Sostituire i segnaposto your-resource-group-name e your-namespace-name con i propri valori. I nomi dei namespace di Service Bus devono essere univoci a livello globale in Azure.

autenticazione Azure

Questa rapida introduzione può essere completata utilizzando l'autenticazione senza password o una stringa di connessione. Le connessioni senza password usano Azure Active Directory e il controllo degli accessi basato su ruoli (RBAC) per connettersi a uno spazio dei nomi di Service Bus. Non è necessario preoccuparsi di avere una stringa di connessione codificata nel codice, in un file di configurazione o nell'archiviazione sicura, come ad esempio Azure Key Vault.

È anche possibile usare una stringa di connessione per connettersi a uno spazio dei nomi del bus di servizio, ma l'approccio senza password è consigliato per applicazioni e ambienti di produzione reali. Per ulteriori informazioni, leggere sulla autenticazione e autorizzazione oppure visitare la pagina panoramica senza password .

senza password (scelta consigliata)
stringa di connessione

Nel namespace del Service Bus, assegna il seguente ruolo all'account utente a cui hai effettuato l'accesso con Visual Studio o con il CLI Azure:

Proprietario dati del bus di servizio: assegnare un ruolo RBAC Azure

Creare la soluzione di esempio

Per creare una nuova applicazione .NET Aspire Starter, è possibile utilizzare Visual Studio, Visual Studio Codeo il CLI di .NET.

Visual Studio fornisce modelli di .NET Aspire che gestiscono automaticamente alcune configurazioni di installazione iniziali. Completare i passaggi seguenti per creare un progetto per questa guida introduttiva:

Nella parte superiore di Visual Studiopassare a File>Nuovo progetto>.
Nella finestra di dialogo cercare Aspire e selezionare .NET.NET Aspire Starter App. Selezionare Avanti.
Nella schermata Configura il tuo nuovo progetto:
- Immettere un Nome Progetto di AspireSample.
- Lasciare i valori predefiniti rimanenti e selezionare Avanti.
Nella schermata Informazioni aggiuntive:
- Assicurarsi che sia selezionato .NET 9.0 (Assistenza Termini Standard).
- Assicurarsi che Utilizzare Redis per il caching (richiede un runtime di contenitori supportato) sia spuntato e selezionare Crea.
- Facoltativamente, è possibile selezionare Creare un progetto di test. Per ulteriori informazioni, vedere Scrivi il tuo primo test .NET.NET Aspire.

Visual Studio crea una nuova soluzione progettata per utilizzare .NET Aspire.

Visual Studio Code fornisce .NET Aspire modelli di progetto che gestiscono automaticamente alcune configurazioni di installazione iniziali. Completare i passaggi seguenti per creare un progetto per questa guida introduttiva:

Da una nuova istanza di Visual Studio Code (senza aprire una cartella), selezionare il pulsante Crea progetto .NET.
Selezionare il modello .NET.NET Aspire app Starter.

Se non hai già installato i modelli .NET.NET Aspire, esegui il seguente comando dotnet new install:

dotnet new install Aspire.ProjectTemplates

Il comando CLI .NET precedente garantisce la disponibilità dei modelli .NET Aspire. Per creare l'app starter .NET.NET Aspire dal modello, eseguire il comando dotnet new seguente:

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

Per ulteriori informazioni, vedere dotnet new. L'interfaccia della riga di comando .NET crea una nuova soluzione strutturata per utilizzare .NET Aspire.

Aggiungere il progetto Worker Service

Aggiungere quindi un progetto Worker Service alla soluzione per recuperare ed elaborare i messaggi da e verso Azure Service Bus.

In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo della soluzione di primo livello AspireSample e selezionare Aggiungi>Nuovo progetto.
Cerca e seleziona il modello Worker Service e scegli Avanti.
Per nome progetto immettere AspireSample.WorkerService e selezionare Avanti.
Nella schermata Informazioni aggiuntive:
- Assicurarsi che sia selezionato .NET 9.0.
- Assicurati che sia selezionata Enlist in .NET.NET Aspire Orchestrazione e seleziona Crea.

Visual Studio aggiunge il progetto alla soluzione e aggiorna il file Program.cs del progetto AspireSample.AppHost con una nuova riga di codice:

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

Lo strumento Visual Studio ha aggiunto questa riga di codice per registrare il tuo nuovo progetto con l'oggetto IDistributedApplicationBuilder, il che permette le funzionalità di orchestrazione che esplorerai successivamente.

Nella Esplora soluzioni in Visual Studio Code, selezionare il pulsante + accanto al nome della soluzione per aggiungere un nuovo progetto alla soluzione.
Per filtrare i modelli di progetto, immettere Worker nella casella di ricerca e selezionare il modello di Worker Service trovato:
Scegliere il modello di Worker Service e immettere il nome del progetto come AspireSample.WorkerService.
Selezionare Directory predefinita per creare il progetto nella stessa directory della soluzione.
Selezionare Crea progetto per aggiungere il progetto alla soluzione.
Fare clic con il pulsante destro del mouse sul progetto di Aspiraresample.AppHost nel esplora soluzioni di e selezionare Aggiungiriferimento al progetto:
Aggiungi la seguente riga di codice nel file Program.cs del progetto AspireSample.AppHost prima della chiamata a builder.Build().Run();:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

Nella directory radice dell'app, utilizza il comando dotnet new per creare una nuova app Worker Service:
```
dotnet new worker --name AspireSample.WorkerService
```

Usare il comando dotnet sln per aggiungere il progetto alla soluzione:

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

Utilizzare il comando dotnet add per aggiungere un riferimento tra i progetti .AppHost e .WorkerService.

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

Aggiungi la seguente riga di codice nel file Program.cs del progetto AspireSample.AppHost prima della chiamata a builder.Build().Run();:
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

La struttura della soluzione completata dovrebbe essere simile alla seguente, supponendo che la directory principale sia denominata 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

Aggiungere l'integrazione .NET.NET Aspire all'API

Aggiungi l'integrazione .NET Aspire Azure Service Bus all'app AspireSample.ApiService:

In Esplora soluzioni , fare doppio clic sul file AspireSample.ApiService.csproj in modo da aprire il relativo file XML.

Aggiungere l'elemento <PackageReference> seguente all'elemento <ItemGroup>:

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

In Esplora soluzioni, fai clic con il tasto destro sul progetto AspireSample.ApiService e seleziona Aggiungi pacchetto NuGet:
Immettere Aspire.Azure. Messaging.ServiceBus nella casella di ricerca e selezionare il pacchetto dall'elenco.
Selezionare la versione (più recente) per installare il pacchetto.

dotnet add package Aspire.Azure.Messaging.ServiceBus

Nel file Program.cs del progetto AspireSample.ApiService aggiungere una chiamata al metodo di estensione AddAzureServiceBusClient, sostituendo la chiamata esistente a AddServiceDefaults:

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

Per altre informazioni, vedere AddAzureServiceBusClient.

Questo metodo esegue le attività seguenti:

Registra un ServiceBusClient nel contenitore DI per connettersi a Azure Service Bus.
Abilita automaticamente i controlli di integrità, la registrazione e i dati di telemetria corrispondenti per i rispettivi servizi.

Nel file appsettings.json dello stesso progetto aggiungere le informazioni di connessione corrispondenti:

senza password (scelta consigliata)
stringa di connessione

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

Nota

Assicurarsi di sostituire {your_namespace} negli URI del servizio con il nome del proprio namespace del Service Bus.

Creare l'endpoint API

L'API deve fornire un endpoint per ricevere i dati e pubblicarli nell'argomento del bus di servizio e trasmettere ai sottoscrittori. Aggiungere l'endpoint seguente al progetto AspireSample.ApiService per inviare un messaggio all'argomento del bus di servizio. Sostituire tutto il contenuto del file Program.cs con il codice C# seguente:

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

Aggiungi l'integrazione .NET Aspire al Worker Service

Aggiungi l'integrazione .NET Aspire Azure Service Bus al progetto AspireSample.WorkerService. Segui la stessa procedura eseguita in precedenza quando hai aggiunto il pacchetto NuGet Aspire.Azure.Messaging.ServiceBus al progetto AspireSample.ApiService. Una volta aggiunto, è possibile configurare il servizio di lavoro per elaborare i messaggi dall'argomento del Service Bus.

Nel file Program.cs del progetto AspireSample.WorkerService sostituire il codice esistente con quanto segue:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

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

Il metodo AddAzureServiceBusClient esegue le attività seguenti:

Registra un ServiceBusClient nel contenitore DI per connettersi a Azure Service Bus.
Abilita automaticamente i controlli di integrità, la registrazione e i dati di telemetria corrispondenti per i rispettivi servizi.

Nel file appsettings.json del progetto AspireSample.WorkerService, aggiungere le corrispondenti informazioni di connessione.

senza password (scelta consigliata)
stringa di connessione

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

Nota

Assicurarsi di sostituire {your_namespace} negli URI del servizio con il nome del proprio Service Bus.

Elaborare il messaggio dall'abbonato

Quando viene inserito un nuovo messaggio nella coda messages, il servizio di lavoro deve recuperare, elaborare ed eliminare il messaggio. Aggiornare la classe Worker.cs in modo che corrisponda al codice seguente:

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

Eseguire e testare l'app in locale

L'app di esempio è ora pronta per il test. Verificare che i dati inviati all'API vengano inviati all'argomento Azure Service Bus e utilizzati dal servizio di lavoro sottoscrittore:

Avvia il progetto .NET.NET Aspire selezionando il pulsante Avvia debug, oppure premendo F5. L'app dashboard .NET.NET Aspire deve essere aperta nel browser.

Avvia il progetto .NET.NET Aspire selezionando il pulsante Avvia debug, oppure premendo F5. L'app dashboard .NET.NET Aspire deve essere aperta nel browser.

Avvia il progetto .NET.NET Aspire eseguendo dotnet run --project AspireSample.AppHost. L'app dashboard .NET.NET Aspire deve essere aperta nel browser.

Nella pagina delle risorse, nella riga apiservice, individuare il collegamento negli Endpoints che apre l'endpoint weatherforecast. Prendere nota del numero di porta HTTPS.
Nel dashboard .NET.NET Aspire navigare ai log per il progetto aspiresample-workerservice.
In una finestra del terminale usare il comando curl per inviare un messaggio di test all'API:
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
Assicurarsi di sostituire {port} con il numero di porta precedente.
Tornare ai log aspiresample-workerservice. Dovresti vedere il messaggio di test riportato nei log di output.

Felicitazioni! È stata creata e configurata un'API ASP.NET Core che si connette a Azure Service Bus usando le integrazioni di Aspire.

Pulire le risorse

Esegui il seguente comando CLI di Azure per eliminare il gruppo di risorse quando le risorse Azure che hai creato non sono più necessarie. L'eliminazione del gruppo di risorse comporta anche l'eliminazione delle risorse contenute all'interno di essa.

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

Per ulteriori informazioni, consultare Pulizia delle risorse in Azure.

Condividi tramite

Esercitazione: Utilizzare le integrazioni di messaggistica di .NET Aspire in ASP.NET Core

Prerequisiti

Configurare l'account Azure Service Bus

autenticazione Azure

Creare la soluzione di esempio

Aggiungere il progetto Worker Service

Aggiungere l'integrazione .NET.NET Aspire all'API

Creare l'endpoint API

Aggiungi l'integrazione .NET Aspire al Worker Service

Elaborare il messaggio dall'abbonato

Eseguire e testare l'app in locale

Pulire le risorse

Risorse aggiuntive