Integração do .NET AspireAzure Queue Storage

Inclui: de integraçãoHosting e integração

Azure Queue Storage é um serviço para armazenar um grande número de mensagens que podem ser acessadas de qualquer lugar do mundo por meio de chamadas autenticadas. A integração do .NET AspireAzure Queue Storage permite que você se conecte a instâncias existentes do Azure Queue Storage ou crie novas instâncias a partir de aplicativos .NET.

Integração de hospedagem

A integração de hospedagem do .NET.NET AspireAzure Storage modela os vários recursos de armazenamento nos seguintes tipos:

• AzureStorageResource: Representa um recurso de armazenamento Azure.
• AzureStorageEmulatorResource: Representa um recurso de emulador de armazenamento Azure (Azurite).
• AzureBlobStorageResource: Representa um recurso de armazenamento de Blob Azure.
• AzureQueueStorageResource: Representa um recurso de armazenamento em fila de Azure.
• AzureTableStorageResource: Representa um recurso de armazenamento Azure Tabela.

Para aceder a esses tipos e APIs para os expressar, adicione o pacote NuGet 📦Aspire.Hosting.Azure.Storage no projeto do aplicativo host .

dotnet add package Aspire.Hosting.Azure.Storage

<PackageReference Include="Aspire.Hosting.Azure.Storage"
                  Version="*" />

Para obter mais informações, consulte dotnet add package ou Manage package dependencies in .NET applications.

Adicionar Azure recurso de armazenamento

No seu projeto anfitrião de aplicação, chame AddAzureStorage para adicionar e retornar um construtor de recurso de armazenamento Azure.

var builder = DistributedApplication.CreateBuilder(args);

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

// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.

// After adding all resources, run the app...

Quando adicionas um AzureStorageResource ao host da aplicação, ele expõe outras APIs úteis para adicionar Azure recursos de armazenamento Blob, Queue e Table. Em outras palavras, você deve adicionar um AzureStorageResource antes de adicionar qualquer um dos outros recursos de armazenamento.

Provisionamento gerado Bicep

Se for novo no Bicep, trata-se de uma linguagem específica de domínio para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, as APIs de provisionamento geram Bicep para você. Quando publica a sua aplicação, o Bicep gerado é disponibilizado juntamente com o ficheiro de manifesto. Quando adiciona um recurso de armazenamento Azure, é gerado o seguinte Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

O Bicep anterior é um módulo que provisiona uma conta de armazenamento Azure com os seguintes padrões:

• kind: O tipo de conta de armazenamento. O padrão é StorageV2.
• sku: O SKU da conta de armazenamento. O padrão é Standard_GRS.
• properties: As propriedades da conta de armazenamento:
  • accessTier: A camada de acesso da conta de armazenamento. O padrão é Hot.
  • allowSharedKeyAccess: Um valor booleano que indica se a conta de armazenamento permite que as solicitações sejam autorizadas com a chave de acesso da conta. O padrão é false.
  • minimumTlsVersion: A versão TLS mínima suportada para a conta de armazenamento. O padrão é TLS1_2.
  • networkAcls: As ACLs de rede para a conta de armazenamento. O padrão é { defaultAction: 'Allow' }.

Além da conta de armazenamento, ele também provisiona um contêiner de blob.

As seguintes atribuições de função são adicionadas à conta de armazenamento para conceder acesso ao aplicativo. Consulte a funções internas de controle de acesso baseado em função Azure (RBACAzure) para obter mais informações:

O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a personalização do Bicep gerado fornecendo uma API fluente para configurar os recursos Azure — usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o kind, sku, propertiese muito mais. O exemplo a seguir demonstra como personalizar o recurso de armazenamento Azure:

builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var storageAccount = infra.GetProvisionableResources()
                                  .OfType<StorageAccount>()
                                  .Single();

        storageAccount.AccessTier = StorageAccountAccessTier.Cool;
        storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
        storageAccount.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

• Encadeia uma chamada para a API ConfigureInfrastructure:
  • O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
  • Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
  • O elemento único StorageAccount é recuperado.
  • O StorageAccount.AccessTier é atribuído a StorageAccountAccessTier.Cool.
  • O StorageAccount.Sku é atribuído a um novo StorageSku com um Name de PremiumZrs.
  • Uma tag é adicionada à conta de armazenamento com uma chave de ExampleKey e um valor de Example value.

Há muito mais opções de configuração disponíveis para personalizar o recurso de armazenamento Azure. Para obter mais informações, consulte Azure.Provisioning.Storage.

Conectar-se a uma conta existente do Azure Storage

Você pode ter uma conta existente do Azure Storage à qual deseja se conectar. Em vez de representar um novo recurso de armazenamento de Azure, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a uma conta existente do Azure Storage, chame o método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

// After adding all resources, run the app...

A cadeia de ligação é configurada na configuração do anfitrião da aplicação, normalmente em Segredos do Utilizador , na seção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

{
    "ConnectionStrings": {
        "blobs": "https://{account_name}.blob.core.windows.net/"
    }
}

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como parâmetro, neste caso "blobs". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Adicionar recurso de emulador de armazenamento Azure

Para adicionar um recurso de emulador de Azure Storage, encadeie uma chamada em um IResourceBuilder<AzureStorageResource> à API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

// After adding all resources, run the app...

Quando você chama RunAsEmulator, ele configura seus recursos de armazenamento para serem executados localmente usando um emulador. O emulador, neste caso, é Azurite. O emulador de código aberto Azurite fornece um ambiente local gratuito para testar seus aplicativos Azure Blob, Queue Storage e Table Storage e é um companheiro perfeito para a integração de hospedagem .NET AspireAzure. O Azurite não está instalado; em vez disso, é acessível para .NET.NET Aspire como um contentor. Quando você adiciona um contêiner ao host do aplicativo, como mostrado no exemplo anterior com a imagem mcr.microsoft.com/azure-storage/azurite, ele cria e inicia o contêiner quando o host do aplicativo é iniciado. Para obter mais informações, consulte Ciclo de vida do recurso de contêiner.

Configurar contêiner do Azurite

Há várias configurações disponíveis para recursos de contentor, por exemplo, pode-se configurar as portas do contentor, variáveis de ambiente, a sua duraçãoe muito mais.

Configurar portas de contêiner do Azurite

Por predefinição, o contentor Azurite, quando configurado pelo .NET.NET Aspire, expõe os seguintes endereços:

A porta na qual eles estão escutando é dinâmica por padrão. Quando o contêiner é iniciado, as portas são mapeadas para uma porta aleatória na máquina host. Para configurar as portas de terminal, encadeie as chamadas no construtor de recursos do contentor fornecido pelo método RunAsEmulator, conforme mostrado no exemplo a seguir.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithBlobPort("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 27002);
                     });

// After adding all resources, run the app...

O código anterior configura os pontos de extremidade blob, queuee table existentes do contêiner Azurite para escutar nas portas 27000, 27001e 27002, respectivamente. As portas do contêiner Azurite são mapeadas para as portas do host, conforme mostrado na tabela a seguir:

Configurar o contêiner Azurite com tempo de vida persistente

Para configurar o contêiner Azurite com um tempo de vida persistente, chame o método WithLifetime no recurso de contêiner Azurite e passe ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithLifetime(ContainerLifetime.Persistent);
                     });

// After adding all resources, run the app...

Para obter mais informações, consulte Ciclo de vida do recurso de contêiner.

Configurar o contêiner Azurite com volume de dados

Para adicionar um volume de dados ao recurso do emulador de Armazenamento de Azure, chame o método WithDataVolume no recurso do emulador de Armazenamento Azure:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataVolume();
                     });

// After adding all resources, run the app...

O volume de dados é usado para manter os dados do Azurite fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /data no contêiner Azurite e, quando um parâmetro name não é fornecido, o nome é formatado como .azurite/{resource name}. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em relação a montagens de ligação , consulte Docker docs: Volumes.

Configurar o contêiner Azurite com a montagem de associação de dados

Para adicionar uma montagem bind de dados ao recurso de emulação de armazenamento Azure, chame o método WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataBindMount("../Azurite/Data");
                     });

// After adding all resources, run the app...

As montagens de associação de dados dependem do sistema de arquivos da máquina host para persistir os dados do Azurite nas reinicializações do contêiner. A montagem de associação de dados é montada no caminho ../Azurite/Data na máquina host em relação ao diretório host do aplicativo (IDistributedApplicationBuilder.AppHostDirectory) no contêiner Azurite. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Conectar-se a recursos de armazenamento

Quando o host do aplicativo .NET.NET Aspire é executado, os recursos de armazenamento podem ser acessados por ferramentas externas, como o Azure Storage Explorer. Se o seu recurso de armazenamento estiver sendo executado localmente usando o Azurite, ele será automaticamente coletado pelo Azure Storage Explorer.

Para ligar ao recurso de armazenamento a partir do Azure Storage Explorer, siga estes passos:

1. Execute o host de aplicativo .NET.NET Aspire.

2. Abra o Azure Storage Explorer.

3. Veja o painel Explorer.

4. Selecione o link Atualizar tudo para atualizar a lista de contas de armazenamento.

5. Expanda o nó Emulador Anexado &.

6. Expanda o nó Contas de Armazenamento.

7. Você verá uma conta de armazenamento com o nome do recurso como um prefixo:

   

Você é livre para explorar a conta de armazenamento e seu conteúdo usando o Azure Storage Explorer. Para obter mais informações sobre como usar o Azure Storage Explorer, consulte Introdução ao Storage Explorer.

Adicionar Azure recurso de Armazenamento em Fila

Em seu projeto de host de aplicativo, registre a integração do Azure Queue Storage encadeando uma chamada para AddQueues na instância de IResourceBuilder<IAzureStorageResource> retornada por AddAzureStorage. O exemplo a seguir demonstra como adicionar um recurso de armazenamento de fila de Azure chamado storage e um recurso de fila chamado queues:

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(queues);

// After adding all resources, run the app...

O código anterior:

• Adiciona um recurso de armazenamento Azure chamado storage.
• Adiciona uma fila chamada queues ao recurso de armazenamento.
• Adiciona o recurso storage ao ExampleProject e aguarda que ele esteja pronto antes de iniciar o projeto.

Verificações de estado da integração de hospedagem

A integração de hospedagem do Azure Storage adiciona automaticamente uma verificação de integridade para o recurso de armazenamento. Ele é adicionado somente quando executado como um emulador e verifica se o contêiner do Azurite está em execução e se uma conexão pode ser estabelecida com ele. A integração de hospedagem depende do 📦 AspNetCore.HealthChecks.Azure. Storage.Blobs pacote NuGet.

Client integração

Para começar com a integração do .NET AspireAzure Queue Storage client, instale o pacote NuGet 📦Aspire.Azure. Storage.Queues no projeto consumidor de client, ou seja, o projeto do aplicativo que utiliza o AzureclientQueue Storage. A integração do Queue Storage Azureclient regista uma instância QueueServiceClient que pode usar para interagir com Queue Storage Azure.

dotnet add package Aspire.Azure.Storage.Queues

<PackageReference Include="Aspire.Azure.Storage.Queues"
                  Version="*" />

Adicionar armazenamento em fila Azureclient

No arquivo de Program.cs do seu projeto de consumo de client, chame o método de extensão AddAzureQueueClient em qualquer IHostApplicationBuilder para registar um QueueServiceClient para uso por meio do container de injeção de dependências. O método usa um parâmetro de nome de conexão.

builder.AddAzureQueueClient("queue");

Em seguida, você pode recuperar a instância QueueServiceClient usando a injeção de dependência. Por exemplo, para recuperar o client de um serviço:

public class ExampleService(QueueServiceClient client)
{
    // Use client...
}

Configuração

A integração do .NET AspireAzure Queue Storage fornece várias opções para configurar o QueueServiceClient com base nos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração de ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

Em seguida, a cadeia de conexão é recuperada da seção de configuração ConnectionStrings e dois formatos de conexão são suportados:

URI de serviço

A abordagem recomendada é usar um ServiceUri, que funciona com a propriedade AzureStorageQueuesSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o Azure.Identity.DefaultAzureCredential será usado.

{
  "ConnectionStrings": {
    "queue": "https://{account_name}.queue.core.windows.net/"
  }
}

Cadeia de conexão

Como alternativa, um string de conexão de armazenamento Azure pode ser usado.

{
  "ConnectionStrings": {
    "queue": "AccountName=myaccount;AccountKey=myaccountkey"
  }
}

Para obter mais informações, consulte Configurar cadeias de conexão de armazenamento Azure.

Usar provedores de configuração

A integração do .NET AspireAzure Queue Storage suporta Microsoft.Extensions.Configuration. Ele carrega AzureStorageQueuesSettings e QueueClientOptions a partir da configuração usando a chave Aspire:Azure:Storage:Queues. O trecho a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Para o esquema completo de integração Azure Storage QueuesclientJSON, consulte Aspire.Azure.Data.Queues/ConfigurationSchema.json.

Usar delegados em linha

Você também pode passar o delegado Action<AzureStorageQueuesSettings> configureSettings para definir algumas ou todas as opções em linha, como configurar verificações de integridade.

builder.AddAzureQueueClient(
    "queue",
    settings => settings.DisableHealthChecks = true);

Você também pode configurar o QueueClientOptions usando o delegate Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder, que é o segundo parâmetro do método AddAzureQueueClient. Por exemplo, para definir a primeira parte dos cabeçalhos de user-agent para todas as solicitações feitas por este client:

builder.AddAzureQueueClient(
    "queue",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

Client verificações de integridade da integração

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral das integrações.

A integração do .NET AspireAzure Queue Storage:

• Adiciona a verificação de integridade quando AzureStorageQueuesSettings.DisableHealthChecks é false, que tenta se conectar ao Azure Queue Storage.
• Integra-se com o endpoint HTTP /health, que especifica que todas as verificações de integridade registadas devem passar para que o aplicativo seja considerado pronto para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção de Configuração .

Registo

A integração do .NET AspireAzure Queue Storage usa as seguintes categorias de log:

• Azure.Core
• Azure.Identity

Rastreio

A integração do .NET AspireAzure Queue Storage emite as seguintes atividades de rastreamento usando OpenTelemetry:

• Azure.Storage.Queues.QueueClient

Métricas

Atualmente, a integração do .NET AspireAzure Queue Storage não oferece suporte a métricas por padrão devido a limitações com o Azure SDK.

Ver também

• Azure documentos de armazenamento em fila
• .NET .NET Aspire integrações
• .NET Aspire GitHub repo