integração para armazenamento de filas .NET AspireAzure

Inclui: —&— Client

Azure Armazenamento de Filas é 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 Armazenamento de Filas .NET AspireAzure permite que você se conecte a instâncias existentes do Armazenamento de Filas Azure ou crie novas instâncias a partir de aplicativos .NET.

Integração de hospedagem

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

• AzureStorageResource: representa um recurso de armazenamento Azure.
• AzureStorageEmulatorResource: representa um recurso do emulador de Armazenamento Azure (Azurite).
• AzureBlobStorageResource: representa um recurso de armazenamento de Blobs Azure.
• AzureQueueStorageResource: Representa um recurso de armazenamento de fila Azure.
• AzureTableStorageResource: representa um recurso de armazenamento de tabela Azure.

Para acessar esses tipos e APIs para expressá-los, adicione o📦Aspire . Hospedagem.Azure. Pacote NuGet de armazenamento no projeto AppHost.

dotnet add package Aspire.Hosting.Azure.Storage

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

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicativos.

Adicionar Azure recurso de Armazenamento

Em seu projeto AppHost, chame AddAzureStorage para adicionar e retornar um Azure construtor de recursos de armazenamento.

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 você adiciona um AzureStorageResource ao AppHost, ele expõe outras APIs úteis para adicionar Azure recursos de armazenamento de Blob, Fila e Tabela. Em outras palavras, você deve adicionar um AzureStorageResource antes de adicionar qualquer um dos outros recursos de armazenamento.

Conectar-se a uma conta de Armazenamento Azure existente

Você pode ter uma conta de Armazenamento Azure existente à qual deseja se conectar. Você pode encadear uma chamada para anotar que seu AzureStorageResource é um recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingStorageName = builder.AddParameter("existingStorageName");
var existingStorageResourceGroup = builder.AddParameter("existingStorageResourceGroup");

var storageaccount = builder.AddAzureStorage("storage")
                    .AsExisting(existingStorageName, existingStorageResourceGroup)
                    .AddBlobs("blobs");

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

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

Para obter mais informações sobre como tratar Azure recursos de armazenamento como recursos existentes, consulte Usar recursos existentesAzure.

Adicionar recurso de emulador de armazenamento Azure

Para adicionar um recurso do emulador de armazenamento Azure, faça uma chamada encadeada no IResourceBuilder<AzureStorageResource> para a 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 nesse caso é do Azurite. O emulador de código aberto Azurite fornece um ambiente local gratuito para testar seus aplicativos de Blob, Armazenamento de Filas e Armazenamento de Tabelas, sendo um complemento perfeito para a integração de hospedagem Azure.NET Aspire. O Azurite não está instalado; ao invés disso, é acessível a .NET.NET Aspire como um contêiner. Quando você adiciona um contêiner ao AppHost, conforme mostrado no exemplo anterior com a mcr.microsoft.com/azure-storage/azurite imagem, ele cria e inicia o contêiner quando o AppHost é iniciado. Para obter mais informações, consulte Ciclo de vida do recurso contêiner.

Configurar o contêiner do Azurite

Há várias configurações disponíveis para recursos de contêiner. Por exemplo, você pode configurar as portas do contêiner, as variáveis de ambiente, seu tempo de vida e muito mais.

Configurar portas de contêiner do Azurite

Por padrão, o contêiner Azurite, quando configurado por .NET.NET Aspire, expõe os seguintes endpoints:

A porta em que eles estão escutando é dinâmica por padrão. Quando o contêiner é iniciado, as portas são mapeadas para uma porta aleatória no computador host. Para configurar as portas de ponto de extremidade, encadeia chamadas no construtor de recursos de contêiner 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(27000)
                                .WithQueuePort(27001)
                                .WithTablePort(27002);
                     });

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

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

Configurar contêiner do Azurite com vida útil persistente

Para configurar o contêiner do Azurite com um tempo de vida persistente, chame o método WithLifetime no recurso de contêiner do 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 tempo de vida do recurso contêiner.

Configurar contêiner Azurite com volume de dados

Para adicionar um volume de dados ao recurso do emulador de Armazenamento 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 do Azurite e, quando um parâmetro name não for fornecido, o nome será formatado como .azurite/{resource name}. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos a montagens acopladas, consulte Docker docs: Volumes.

Configurar o contêiner Azurite com vínculo de montagem de dados

Para adicionar uma montagem de vinculação de dados ao recurso de emulador 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 ligação de dados dependem do sistema de arquivos da máquina host para manter os dados do Azurite durante as reinicializações do contêiner. A montagem da associação de dados é montada no ../Azurite/Data caminho no computador host em relação ao diretório AppHost (IDistributedApplicationBuilder.AppHostDirectory) no contêiner do Azurite. Para obter mais informações sobre montagens de vínculo de dados, consulte a documentação em Docker docs: Montagens de vínculo.

Conectar-se aos recursos de armazenamento

Quando o .NET.NET Aspire AppHost é executado, os recursos de armazenamento podem ser acessados por ferramentas externas, como o Azure Gerenciador de Armazenamento. Se o recurso de armazenamento estiver sendo executado localmente usando o Azurite, ele será automaticamente coletado pelo Gerenciador de Armazenamento Azure.

Para se conectar ao recurso de armazenamento do Gerenciador de Armazenamento Azure, siga estas etapas:

1. Execute o .NET.NET Aspire AppHost.

2. Abra o Gerenciador de Armazenamento Azure.

3. Visualize o painel Explorer.

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

5. Expanda o nó Emulador e Anexado.

6. Expanda o nó Contas de Armazenamento.

7. Você deve 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 Gerenciador de Armazenamento Azure. Para obter mais informações sobre como usar o Gerenciador de Armazenamento Azure, consulte Introdução ao Gerenciador de Armazenamento.

Adicionar o recurso de Armazenamento de Fila Azure

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

O código anterior:

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

Bicep gerado por provisionamento

Se você é novo em Bicep, trata-se de uma linguagem especializada 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 você publica seu aplicativo, o Bicep gerado é incluído junto com o arquivo de manifesto. Quando você adiciona um recurso de armazenamento Azure, o seguinte Bicep é gerado:

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

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

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

output name string = storage.name

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: a 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 booliano 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 mínima do TLS com suporte para a conta de armazenamento. O padrão é TLS1_2.
  • networkAcls: os ACLs de rede da conta de armazenamento. O padrão é { defaultAction: 'Allow' }.

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

As atribuições de função a seguir são adicionadas à conta de armazenamento para conceder acesso ao seu aplicativo. Consulte as Azure para obter mais informações:

Além disso, as atribuições de função são criadas para o Azure recurso em um módulo separado:

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

param storage_outputs_name string

param principalType string

param principalId string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' existing = {
  name: storage_outputs_name
}

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
}

O Bicep gerado é um ponto de partida e é influenciado por alterações na infraestrutura de provisionamento em C#. As personalizações feitas diretamente no arquivo Bicep serão substituídas, portanto, faça alterações por meio das APIs de provisionamento do C# para garantir que elas sejam refletidas nos arquivos gerados.

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 a configuração dos 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 à API de 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 etiqueta é adicionada à conta de armazenamento com a chave ExampleKey e o valor Example value.

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

Adicionar recurso de emulador de armazenamento Azure

Para adicionar um recurso do emulador de armazenamento Azure, faça uma chamada encadeada no IResourceBuilder<AzureStorageResource> para a 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 nesse caso é do Azurite. O emulador de código aberto Azurite fornece um ambiente local gratuito para testar seus aplicativos de Blob, Armazenamento de Filas e Armazenamento de Tabelas, sendo um complemento perfeito para a integração de hospedagem Azure.NET Aspire. O Azurite não está instalado; Em vez disso, ele é acessível .NET.NET Aspire como um contêiner. Quando você adiciona um contêiner ao AppHost, conforme mostrado no exemplo anterior com a mcr.microsoft.com/azure-storage/azurite imagem, ele cria e inicia o contêiner quando o AppHost é iniciado. Para obter mais informações, consulte Ciclo de vida do recurso contêiner.

Configurar o contêiner do Azurite

Há várias configurações disponíveis para recursos de contêiner, por exemplo, você pode configurar as portas do contêiner, variáveis de ambiente, tempo de vida e muito mais.

Configurar portas de contêiner do Azurite

Por padrão, o contêiner do Azurite, quando configurado por .NET.NET Aspire, expõe os seguintes pontos de extremidade:

A porta em que eles estão escutando é dinâmica por padrão. Quando o contêiner é iniciado, as portas são mapeadas para uma porta aleatória no computador host. Para configurar as portas de ponto de extremidade, encadeia chamadas no construtor de recursos de contêiner 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(27000)
                                .WithQueuePort(27001)
                                .WithTablePort(27002);
                     });

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

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

Configurar contêiner do Azurite com vida útil persistente

Para configurar o contêiner do Azurite com um tempo de vida persistente, chame o método WithLifetime no recurso de contêiner do 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 tempo de vida do recurso contêiner.

Configurar contêiner Azurite com volume de dados

Para adicionar um volume de dados ao recurso do emulador de Armazenamento 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 do Azurite e, quando um parâmetro name não for fornecido, o nome será formatado como .azurite/{resource name}. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos a montagens acopladas, consulte Docker docs: Volumes.

Configurar o contêiner Azurite com vínculo de montagem de dados

Para adicionar uma montagem de vinculação de dados ao recurso de emulador 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 ligação de dados dependem do sistema de arquivos da máquina host para manter os dados do Azurite durante as reinicializações do contêiner. A montagem da associação de dados é montada no ../Azurite/Data caminho no computador host em relação ao diretório AppHost (IDistributedApplicationBuilder.AppHostDirectory) no contêiner do Azurite. Para obter mais informações sobre montagens de vínculo de dados, consulte a documentação em Docker docs: Montagens de vínculo.

Conectar-se a uma conta de Armazenamento Azure existente

Você pode ter uma conta de Armazenamento Azure existente à qual deseja se conectar. Em vez de representar um novo Azure recurso de Armazenamento, você pode adicionar uma cadeia de conexão ao AppHost. Para adicionar uma conexão a uma conta de Armazenamento Azure existente, 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 conexão é configurada na configuração do AppHost, normalmente em Segredos do Usuário, na ConnectionStrings seção. O AppHost 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 o parâmetro, nesse caso "blobs". A API GetConnectionString é uma forma abreviada de IConfiguration.GetSection("ConnectionStrings")[name].

Conectar-se aos recursos de armazenamento

Quando o .NET.NET Aspire AppHost é executado, os recursos de armazenamento podem ser acessados por ferramentas externas, como o Azure Gerenciador de Armazenamento. Se o recurso de armazenamento estiver sendo executado localmente usando o Azurite, ele será automaticamente coletado pelo Gerenciador de Armazenamento Azure.

Para se conectar ao recurso de armazenamento do Gerenciador de Armazenamento Azure, siga estas etapas:

1. Execute o .NET.NET Aspire AppHost.

2. Abra o Gerenciador de Armazenamento Azure.

3. Visualize o painel Explorer.

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

5. Expanda o nó Emulador e Anexado.

6. Expanda o nó Contas de Armazenamento.

7. Você deve 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 Gerenciador de Armazenamento Azure. Para obter mais informações sobre como usar o Gerenciador de Armazenamento Azure, consulte Introdução ao Gerenciador de Armazenamento.

Verificações de integridade 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 ao ser 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.

integração Client

Para começar a usar a integração do cliente do Armazenamento de Filas do .NET AspireAzure, instale o pacote NuGet 📦AspireAzure..Storage.Queues no projeto que consome o cliente do Armazenamento de Filas, ou seja, o projeto do aplicativo que usa o cliente de Armazenamento de Filas Azure. A integração do cliente da Fila de Armazenamento Azure registra uma instância de QueueServiceClient que você pode usar para interagir com a Fila de Armazenamento Azure.

dotnet add package Aspire.Azure.Storage.Queues

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

Adicionar Azure cliente de Armazenamento de Filas

No arquivo Program.cs do projeto que utiliza o cliente, chame o método de extensão AddAzureQueueClient em qualquer IHostApplicationBuilder para registrar um QueueServiceClient para que possa ser usado por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureQueueClient("queue");

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

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

Configuration

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

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração 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 há suporte para dois formatos de conexão:

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, uma cadeia de conexão de armazenamento Azure pode ser usada.

{
  "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 de Armazenamento de Filas .NET AspireAzure suporta Microsoft.Extensions.Configuration. Ele carrega o AzureStorageQueuesSettings e o QueueClientOptions da configuração usando a chave Aspire:Azure:Storage:Queues. O snippet 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 obter o esquema completo de integração do cliente Azure Storage QueuesJSON, consulte Aspire.Azure.Data.Queues/ConfigurationSchema.json.

Usar configuração nomeada

A .NET AspireAzure integração do Armazenamento de Filas dá suporte à configuração nomeada, o que permite que você configure várias instâncias do mesmo tipo de recurso com configurações diferentes. A configuração nomeada usa o nome da conexão como uma chave na seção de configuração principal.

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "queue1": {
            "DisableHealthChecks": true,
            "ClientOptions": {
              "Diagnostics": {
                "ApplicationId": "myapp1"
              }
            }
          },
          "queue2": {
            "DisableTracing": true,
            "ClientOptions": {
              "Diagnostics": {
                "ApplicationId": "myapp2"
              }
            }
          }
        }
      }
    }
  }
}

Neste exemplo, os nomes de conexão queue1 e queue2 podem ser usados ao chamar AddAzureQueueClient:

builder.AddAzureQueueClient("queue1");
builder.AddAzureQueueClient("queue2");

A configuração nomeada tem precedência sobre a configuração de nível superior. Se ambos forem fornecidos, as configurações da configuração nomeada substituirão as configurações de nível superior.

Usar delegados em linha

Você também pode passar o delegado Action<AzureStorageQueuesSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para configurar verificações de integridade:

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

Você também pode configurar o QueueClientOptions usando o delegado Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder, o segundo parâmetro do método AddAzureQueueClient. Por exemplo, para definir a primeira parte dos cabeçalhos do agente de usuário para todas as solicitações feitas por este cliente:

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

Client verificação de saúde 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 de integrações.

Integração do Armazenamento de Filas .NET AspireAzure:

• Adiciona a verificação de integridade quando AzureStorageQueuesSettings.DisableHealthChecks é false, tentando conectar-se ao Armazenamento de Filas Azure.
• Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem passar para que o aplicativo esteja pronto para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Logging

A Integração de Armazenamento de Filas .NET AspireAzure usa as seguintes categorias de log:

• Azure.Core
• Azure.Identity

Tracing

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

• Azure.Storage.Queues.QueueClient

Metrics

A integração do Armazenamento de Filas .NET AspireAzure atualmente não dá suporte a métricas por padrão devido a limitações com o SDK Azure.

Consulte também

• Azure Documentação de Armazenamento em Filas
• .NET .NET Aspire integrações
• .NET Aspire GitHub repositório