Tutorial: Conectar um aplicativo ASP.NET Core a integrações de armazenamento .NET Aspire

Para este artigo, você precisará de acesso de contribuidor de dados a uma conta de armazenamento Azure com um contêiner de blob e fila de armazenamento. Certifique-se de ter os seguintes recursos e configurações disponíveis:

Para este artigo, você precisará criar um contêiner de blob e um recurso de fila de armazenamento em seu ambiente de desenvolvimento local usando um emulador. Para fazer isso, use Azurite. O Azurite é um server (emulador) gratuito, de código aberto e compatível com a API de armazenamento Azure multiplataforma que é executado em um contêiner Docker.

Para usar o emulador, você precisa instalar o Azurite.

1. Uma conta de armazenamento Azure - Crie uma conta de armazenamento.
2. Um contêiner de Armazenamento de Blob chamado fileuploads - Criar um contêiner de armazenamento de blob.
3. Uma fila de armazenamento nomeada - Criar uma fila de armazenamento.

Execute os seguintes comandos na CLI do Azure ou no CloudShell para configurar os recursos necessários do Azure Storage:

az group create --name aspirestorage --location eastus2
az storage account create -n aspirestorage -g aspirestorage -l eastus2
az storage container create -n fileuploads --account-name aspirestorage
az storage queue create -n tickets --account-name aspirestorage

Você também precisa atribuir as seguintes funções à conta de usuário com a qual você está conectado em Visual Studio:

• Contribuidor de Dados de Blob de Armazenamento - Atribuir uma função RBAC Azure
• Contribuidor de Dados da Fila de Armazenamento - Atribuir uma função RBAC Azure

O Azure Developer CLI permite provisionar e implantar recursos Azure usando um sistema de modelos. Este tutorial fornece um modelo completo que provisiona os recursos de Azure necessários e inclui o código de aplicativo de exemplo concluído. Execute os seguintes comandos para inicializar e executar o modelo:

1. Execute azd auth login para iniciar sessão no Azure:

   azd auth login
   

2. Execute azd init para clonar e inicializar o modelo de exemplo:

   azd init --template dotnet-aspire-connect-storage
   

3. Execute azd up para provisionar os recursos Azure:

   azd up
   

4. Quando solicitado, selecione a assinatura e a região Azure para os recursos provisionados. O modelo é executado e conclui as seguintes tarefas para você:

   • Cria uma conta de armazenamento Azure com os serviços de blob e fila ativados
   • Cria um contêiner de armazenamento de blob chamado fileUploads
   • Cria uma fila chamada tickets
   • Atribui as seguintes funções à conta de usuário que executou o modelo.
     • Contribuidor de dados de Blob de armazenamento
     • Contribuidor de dados da fila de armazenamento

Depois que a operação for concluída com êxito, você terá duas opções para avançar:

• Opção 1: Execute o aplicativo de exemplo .NET no diretório de modelo src para experimentar o aplicativo concluído.
• Opção 2: Crie o aplicativo de exemplo passo a passo usando as seções à frente e conecte-o aos recursos de Azure provisionados pelo azd.

using AspireStorage.Web;
using AspireStorage.Web.Components;

using Azure.Storage.Blobs;
using Azure.Storage.Queues;

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureBlobClient("BlobConnection");
builder.AddAzureQueueClient("QueueConnection");

// Add service defaults & Aspire components.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddOutputCache();

builder.Services.AddHttpClient<WeatherApiClient>(client =>
    {
        // This URL uses "https+http://" to indicate HTTPS is preferred over HTTP.
        // Learn more about service discovery scheme resolution at https://aka.ms/dotnet/sdschemes.
        client.BaseAddress = new("https+http://apiservice");
    });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}
else
{
    // In development, create the blob container and queue if they don't exist.
    var blobService = app.Services.GetRequiredService<BlobServiceClient>();
    var docsContainer = blobService.GetBlobContainerClient("fileuploads");

    await docsContainer.CreateIfNotExistsAsync();

    var queueService = app.Services.GetRequiredService<QueueServiceClient>();
    var queueClient = queueService.GetQueueClient("tickets");

    await queueClient.CreateIfNotExistsAsync();
}

app.UseHttpsRedirection();

app.UseStaticFiles();
app.UseAntiforgery();

app.UseOutputCache();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.MapDefaultEndpoints();

app.Run();

using AspireStorage.Web;
using AspireStorage.Web.Components;

using Azure.Storage.Blobs;
using Azure.Storage.Queues;

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureBlobClient("BlobConnection");
builder.AddAzureQueueClient("QueueConnection");

// Add service defaults & Aspire components.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddOutputCache();

builder.Services.AddHttpClient<WeatherApiClient>(client =>
    {
        // This URL uses "https+http://" to indicate HTTPS is preferred over HTTP.
        // Learn more about service discovery scheme resolution at https://aka.ms/dotnet/sdschemes.
        client.BaseAddress = new("https+http://apiservice");
    });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();
app.UseAntiforgery();

app.UseOutputCache();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.MapDefaultEndpoints();

app.Run();

Quando o projeto AspireStorage.Web for iniciado, ele criará um contêiner de fileuploads no Azurite Blob Storage e uma fila de tickets no Azurite Queue Storage. Isso é condicional quando o aplicativo está sendo executado em um ambiente de desenvolvimento. Quando o aplicativo está sendo executado em um ambiente de produção, presume-se que o contêiner e a fila já tenham sido criados.

using Microsoft.Extensions.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("Storage");

if (builder.Environment.IsDevelopment())
{
    storage.RunAsEmulator();
}

var blobs = storage.AddBlobs("BlobConnection");
var queues = storage.AddQueues("QueueConnection");

var apiService = builder.AddProject<Projects.AspireStorage_ApiService>("apiservice");

builder.AddProject<Projects.AspireStorage_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(apiService)
    .WithReference(blobs)
    .WithReference(queues); 

builder.AddProject<Projects.AspireStorage_WorkerService>("aspirestorage-workerservice")
    .WithReference(queues);

builder.Build().Run();

O código anterior adiciona armazenamento Azure, blobs e filas e, quando no modo de desenvolvimento, usa o emulador. Cada projeto define referências para esses recursos dos quais depende.

using Microsoft.Extensions.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("Storage");

var blobs = storage.AddBlobs("BlobConnection");
var queues = storage.AddQueues("QueueConnection");

var apiService = builder.AddProject<Projects.AspireStorage_ApiService>("apiservice");

builder.AddProject<Projects.AspireStorage_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(apiService)
    .WithReference(blobs)
    .WithReference(queues); 

builder.AddProject<Projects.AspireStorage_WorkerService>("aspirestorage-workerservice")
    .WithReference(queues);

builder.Build().Run();

O código anterior adiciona Azure armazenamento, blobs e filas e define referências para esses recursos dentro de cada projeto que dependem deles.

using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;

namespace AspireStorage.WorkerService;

public sealed class WorkerService(
    QueueServiceClient client,
    ILogger<WorkerService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var queueClient = client.GetQueueClient("tickets");
        await queueClient.CreateIfNotExistsAsync(cancellationToken: stoppingToken);

        while (!stoppingToken.IsCancellationRequested)
        {
            QueueMessage[] messages =
                await queueClient.ReceiveMessagesAsync(
                    maxMessages: 25, cancellationToken: stoppingToken);

            foreach (var message in messages)
            {
                logger.LogInformation(
                    "Message from queue: {Message}", message.MessageText);

                await queueClient.DeleteMessageAsync(
                    message.MessageId,
                    message.PopReceipt,
                    cancellationToken: stoppingToken);
            }

            // TODO: Determine an appropriate time to wait 
            // before checking for more messages.
            await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);
        }
    }
}

Antes que o serviço de trabalho possa processar mensagens, ele precisa ser capaz de se conectar à fila de armazenamento Azure. Com o Azurite, você precisa garantir que a fila esteja disponível antes que o serviço de trabalho comece a executar o processamento da fila de mensagens.

using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;

namespace AspireStorage.WorkerService;

public sealed class WorkerService(
    QueueServiceClient client,
    ILogger<WorkerService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var queueClient = client.GetQueueClient("tickets");
        while (!stoppingToken.IsCancellationRequested)
        {
            QueueMessage[] messages =
                await queueClient.ReceiveMessagesAsync(
                    maxMessages: 25, cancellationToken: stoppingToken);

            foreach (var message in messages)
            {
                logger.LogInformation(
                    "Message from queue: {Message}", message.MessageText);

                await queueClient.DeleteMessageAsync(
                    message.MessageId,
                    message.PopReceipt,
                    cancellationToken: stoppingToken);
            }

            // TODO: Determine an appropriate time to wait 
            // before checking for more messages.
            await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);
        }
    }
}

O serviço de trabalho processa mensagens conectando-se à fila de armazenamento de Azure e retirando mensagens da fila.

Configurar as cadeias de conexão

O projeto AspireStorage e o projeto AspireStorage.Worker devem ser configurados para se conectar à correta Conta de Armazenamento Azure que você criou anteriormente. Pode especificar os endpoints para os serviços de blob e fila na conta de armazenamento, utilizando o ficheiro appsettings.json em cada projeto.

1. No projeto AspireStorage, adicione a seguinte configuração ao arquivo appsettings.Development.json:

     "ConnectionStrings": {
       "BlobConnection": "https://<your-storage-account-name>.blob.core.windows.net/",
       "QueueConnection": "https://<your-storage-account-name>.queue.core.windows.net/"
     }
   

2. No projeto AspireStorage.Worker, adicione a seguinte configuração ao arquivo appsettings.Development.json:

     "ConnectionStrings": {
       "QueueConnection": "https://<your-storage-account-name>.queue.core.windows.net/"
     }
   

Como você opta por usar o Azurite, não há necessidade de limpar esses recursos quando terminar de testá-los, pois você os criou localmente no contexto de um emulador. O emulador permitiu que você testasse seu aplicativo localmente sem incorrer em custos, já que nenhum Azure recursos foram provisionados ou criados.

Limpar recursos

Execute o seguinte comando Azure CLI para excluir o grupo de recursos quando não precisar mais dos recursos Azure criados. A exclusão do grupo de recursos também exclui os recursos contidos nele.

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

Para mais informações, veja Limpeza de recursos em Azure.