integração .NET AspireAzure Blob Storage

Artigo
12/15/2024

Inclui:integração de hospedagem e integraçãoClient

Azure Blob Storage é um serviço para armazenar grandes quantidades de dados não estruturados. A integração .NET AspireAzure Blob Storage permite que você se conecte a instâncias Azure Blob Storage existentes ou crie novas instâncias de aplicativos .NET.

Integração de hospedagem

Os modelos de integração do armazenamento de hospedagem .NET.NET AspireAzure representam os vários recursos de armazenamento listados como os 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 pacote NuGet 📦Aspire.Hosting.Azure.Storage no projeto do host do aplicativo .

.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 or Manage package dependencies in .NET applications.

Adicionar Azure recurso de Armazenamento

Em seu projeto de host de aplicativo, chame AddAzureStorage para adicionar e retornar um construtor de recursos 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 você adiciona um AzureStorageResource ao host do aplicativo, ele expõe outras APIs úteis para adicionar Azure blob, fila e recursos de armazenamento de 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— o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Provisionamento Bicep gerado

Se você é novo em Bicep, é uma linguagem específica do domínio para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente; as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é gerado junto com o arquivo de manifesto. Quando você adiciona um recurso de armazenamento Azure, o seguinte Bicep é gerado:

Toggle 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: 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, ela 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 à sua aplicação. Consulte as funções internas Azure controle de acesso baseado em função (Azure RBAC) para obter mais informações:

Função/ID	Descrição
Colaborador de Dados do Blob de Armazenamento `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Ler, escrever e excluir contêineres e blobs do Armazenamento Azure.
Colaborador de dados da tabela de armazenamento `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Ler, gravar e excluir tabelas e entidades de armazenamento Azure.
Colaborador de dados da fila de armazenamento `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Ler, gravar e excluir filas de armazenamento Azure e mensagens de fila.

O Bicep gerado é um ponto de partida e pode ser personalizado para atender aos seus requisitos específicos.

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 de 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 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 etiqueta é adicionada à conta de armazenamento com uma chave de ExampleKey e um valor de 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.

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 recurso de armazenamento Azure, você pode adicionar uma cadeia de conexão ao host do aplicativo. 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...

Nota

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. Em .NET.NET Aspire nomenclatura, 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 o parâmetro, nesse caso "blobs". A API GetConnectionString é uma abreviação para IConfiguration.GetSection("ConnectionStrings")[name].

Adicionar o recurso de emulador de armazenamento Azure

Para adicionar um recurso do emulador de Armazenamento Azure, encadeia 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 nesse caso é do Azurite. O emulador de software livre do Azurite fornece um ambiente local gratuito para testar seus aplicativos Azure Blob, Armazenamento de Filas e Armazenamento de Tabelas e é um complemento perfeito para o .NET AspireAzure integração de hospedagem. 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 host do aplicativo, conforme 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 contêiner de recursos.

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 vidae muito mais.

Configurar portas de contêiner do Azurite

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

Endpoint	Porta de contêiner	Porta do host
`blob`	10.000	dinâmico
`queue`	10001	dinâmico
`table`	10002	dinâmico

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("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 27002);
                     });

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

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

Nome do ponto de extremidade	Mapeamento de porta (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Configurar o 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 de Contêiner.

Configurar o contêiner do Azurite com o 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 é 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 preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

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

Para adicionar uma montagem de associação de dados ao recurso do emulador de Armazenamento do 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

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

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

Conectar-se aos recursos de armazenamento

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

Nota

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

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

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

No projeto de host do aplicativo, registre a integração Azure Blob Storage encadeando uma chamada para AddBlobs na instância de IResourceBuilder<IAzureStorageResource> retornada por AddAzureStorage. O exemplo a seguir demonstra como adicionar um recurso de Azure Blob Storage chamado storage e um contêiner de blob chamado blobs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

O código anterior:

Adiciona um recurso de Armazenamento Azure chamado storage.
Encadeia uma chamada para RunAsEmulator para configurar o recurso de armazenamento a ser executado localmente usando um emulador. O emulador nesse caso é do Azurite.
Adiciona um contêiner de blob chamado blobs ao recurso de armazenamento.
Adiciona o recurso blobs ao ExampleProject e aguarda que ele esteja pronto antes de iniciar o projeto.

Verificações de integridade das integrações de hospedagem

A integração de hospedagem do Armazenamento Azure 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 .NET AspireAzure Blob Storageclient, instale o pacote NuGet 📦Aspire.Azure.Storage.Blobs no projeto que consome client, ou seja, no projeto do aplicativo que usa o Azure Blob Storageclient. A integração Azure Blob Storageclient registra uma instância de BlobServiceClient que você pode usar para interagir com Azure Blob Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Blobs

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

Adicionar Azure Blob Storageclient

No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddAzureBlobClient em qualquer IHostApplicationBuilder para registrar um BlobServiceClient para uso por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureBlobClient("blobs");

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

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

Configuração

A integração .NET AspireAzure Blob Storage fornece várias opções para configurar o BlobServiceClient 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 AddAzureBlobClient:

builder.AddAzureBlobClient("blobs");

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 AzureStorageBlobsSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o Azure.Identity.DefaultAzureCredential será usado.

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

Cadeia de conexão

Como alternativa, uma cadeia de conexão de armazenamento Azure pode ser usada.

{
  "ConnectionStrings": {
    "blobs": "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 .NET AspireAzure Blob Storage dá suporte a Microsoft.Extensions.Configuration. Ele carrega o AzureStorageBlobsSettings e BlobClientOptions da configuração usando a chave Aspire:Azure:Storage:Blobs. O snippet a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

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

Para obter o esquema Azure Blob Storage de integração clientJSON completo, consulte Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Usar delegados embutidos

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

builder.AddAzureBlobClient(
    "blobs",
    settings => settings.DisableHealthChecks = true);

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

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

Client verificações de integridade de 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.

A integração .NET AspireAzure Blob Storage:

Adiciona a verificação de integridade quando AzureStorageBlobsSettings.DisableHealthChecks é false, que tenta se conectar ao Azure Blob Storage.
Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem passar para que o aplicativo seja considerado pronto para receber 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.

Registro

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

Azure.Core
Azure.Identity

Rastreamento

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

Azure.Storage.Blobs.BlobContainerClient

Métricas

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

Compartilhar via