.NET Aspire Azure Integração com tabelas de dados

Artigo
12/14/2024

Inclui: Integração de Hostinge integração Client

Azure Table Storage é um serviço para armazenar dados NoSQL estruturados. A integração .NET AspireAzure Tabelas de Dados permite que você se conecte a instâncias de Azure Table Storage existentes ou crie novas instâncias a partir de aplicativos .NET.

Integração de hospedagem

A integração de hospedagem de armazenamento dos modelos .NET.NET AspireAzure modela os vários recursos de armazenamento dos 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 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. Armazenamento pacote NuGet no aplicativo host projeto.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

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

Adicionar Azure recurso de armazenamento

No seu projeto de host de aplicativo, 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...

Ao adicionares um AzureStorageResource ao host da aplicação, ele disponibiliza outras APIs úteis para adicionar Azure recursos de armazenamento de Blob, Queue e Tabela. Em outras palavras, você deve adicionar um AzureStorageResource antes de adicionar qualquer um dos outros recursos de armazenamento.

Importante

Quando você chama AddAzureStorage, ele chama implicitamente AddAzureProvisioning—que adiciona suporte para gerar recursos de Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Configuração de provisionamento local:.

Provisionamento gerado Bicep

Se és novo em Bicep, é uma linguagem específica de um domínio para definir Azure recursos. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, as APIs de provisionamento geram Bicep para você. Quando se publica o seu aplicativo, o Bicep gerado é disponibilizado junto com o ficheiro de manifesto. Quando um recurso de Azure Storage é adicionado, o seguinte Bicep é gerado:

Alterne Azure armazenamento 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 provisiona também um contentor de blobs.

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:

Função / ID	Descrição
Contribuidor de dados de Blob de armazenamento `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Leia, escreva e elimine contentores e blobs de Armazenamento Azure.
Contribuidor de dados de tabelas de armazenamento `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Leia, escreva e elimine tabelas e entidades de armazenamento Azure.
Contribuidor de dados da fila de armazenamento `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Leia, escreva e elimine filas de armazenamento Azure e mensagens de fila.

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 personalizar o Bicep gerado ao fornecer uma API fluente para configurar os recursos Azure, utilizando 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 ú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...

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Na nomenclatura .NET.NET Aspire, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário , 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 do emulador de armazenamento Azure

Para adicionar um recurso de emulador de Azure Storage, encadeie uma chamada num 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, 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 contêiner. 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 contêiner, por exemplo, você pode configurar as portas do contêiner, variáveis de ambiente, é tempo de vidae muito mais.

Configurar portas de contêiner do Azurite

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

Ponto final	Porto de contentores	Porta do host
`blob`	10.000	dinâmico
`queue`	10001	dinâmico
`table`	10002	dinâmico

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 ponto final, encadear 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:

Nome do ponto final	Cartografia de portos (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

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 Tempo 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 detrimento de montagens de ligação , consulte os documentos (docs) Docker: Volumes.

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

Para adicionar uma montagem de ponto de ligação de dados ao recurso de armazenamento do emulador 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...

Importante

As montagens de ligação de dados têm funcionalidade limitada comparado com volumes, que oferecem melhor desempenho, portabilidade e segurança, o que os torna mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

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 dados é efetuada no caminho ../Azurite/Data da máquina host, em relação ao diretório 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.

Observação

O Azure Storage Explorer descobre recursos de armazenamento do Azurite supondo que as portas padrão sejam usadas. Se você configurou o contêiner Azurite para usar portas diferentes, precisará configurar o Azure Storage Explorer para se conectar às portas corretas.

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

Execute o .NET.NET Aspire host do aplicativo.
Abra o Azure Storage Explorer.
Veja o painel Explorer.
Selecione o link Atualizar tudo para atualizar a lista de contas de armazenamento.
Expanda o Emulador Anexado & nó.
Expanda o nó Contas de Armazenamento.
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 Table Storage recurso

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

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(tables)
       .WaitFor(tables);

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

O código anterior:

Adiciona um recurso de armazenamento Azure chamado storage.
Adiciona um recurso de armazenamento de tabela chamado tables ao recurso de armazenamento.
Adiciona o recurso storage ao ExampleProject e aguarda que ele esteja pronto antes de iniciar o projeto.

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 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 a integração das .NET AspireAzure Tabelas de Dados client, instale o pacote NuGet 📦Aspire.Azure.Data.Tables no projeto que consome client, ou seja, o projeto para a aplicação que utiliza as Azure Tabelas de Dados client. A integração das Tabelas de Dados Azureclient regista uma instância TableServiceClient que pode usar para interagir com Azure Table Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Data.Tables

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />

Adicionar Azure Table Storageclient

No arquivo Program.cs do seu projeto de utilização de client, chame o método de extensão AddAzureTableClient em qualquer IHostApplicationBuilder para registar um TableServiceClient para ser utilizado através do contentor de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureTableClient("tables");

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

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

Configuração

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

Usar provedores de configuração

A integração .NET AspireAzure Table Storage suporta Microsoft.Extensions.Configuration. Ele carrega o AzureDataTablesSettings e o TableClientOptions a partir da configuração, usando a chave Aspire:Azure:Data:Tables. O trecho a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "Azure": {
      "Data": {
        "Tables": {
          "ServiceUri": "YOUR_URI",
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "EnableTenantDiscovery": true
          }
        }
      }
    }
  }
}

Para obter a Azure completa Tabelas de Dados client integração JSON esquema, consulte Aspire.Azure. Data.Tables/ConfigurationSchema.json.

Usar delegados incorporados

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

builder.AddAzureTableClient(
    "tables",
    settings => settings.DisableHealthChecks = true);

Você também pode configurar o TableClientOptions usando o delegado Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder, o segundo parâmetro do método AddAzureTableClient. Por exemplo, para definir o ID de TableServiceClient para identificar o client:

builder.AddAzureTableClient(
    "tables",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.EnableTenantDiscovery = true));

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

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 das Tabelas de Dados .NET AspireAzure:

Adiciona a verificação de integridade quando AzureDataTablesSettings.DisableHealthChecks é false, que tenta conectar-se ao Azure Table Storage.
Integra-se com o ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registadas devem passar para que a aplicação seja considerada pronta 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 seção de configuração .

Registo

A integração de tabelas de dados .NET AspireAzure usa as seguintes categorias de log:

Azure.Core
Azure.Identity

Rastreio

A integração .NET AspireAzure Data Tables emite as seguintes atividades de rastreamento usando OpenTelemetry:

Azure.Data.Tables.TableServiceClient

Métricas

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

Partilhar via