.NET Aspire Azure Blob Storage integração

Artigo
12/13/2024

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

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 de Azure Blob Storage existentes ou crie novas instâncias a partir de aplicativos .NET.

Integração de hospedagem

A .NET.NET AspireAzure integração de hospedagem do 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 de fila do Azure.
AzureTableStorageResource: Representa um recurso de armazenamento de tabelas Azure.

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

.NET CLI
ReferênciaDePacote

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 aplicação, 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 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.

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 Provisionamento local: Configuração.

Provisionamento gerado Bicep

Se és novo no Bicep, é uma linguagem específica do 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 publicas a tua aplicação, o Bicep gerado é apresentado junto com o arquivo de manifesto. Quando se adiciona um recurso de armazenamento Azure, o seguinte Bicep é gerado:

Alterne Azure Bicep de Armazenamento.

@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 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 armazenamento Blob `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Leia, escreva e apague contentores e blobs do Armazenamento Azure.
Contribuidor de dados da tabela 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 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 ú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 da aplicação, normalmente em "Segredos do Utilizador" , na subseçã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 num 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, está 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 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, o contentor Azurite quando configurado pelo .NET.NET Aspire, expõe os seguintes pontos de extremidade:

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 de extremidade, encadeie chamadas no construtor de recursos do contentor fornecido pelo método RunAsEmulator, conforme mostrado no exemplo seguinte:

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 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 de ligação de dados ao recurso do emulador de Azure Storage, 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 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 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 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.

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 host da aplicação .NET.NET Aspire.
Abra o Azure Storage Explorer.
Veja o painel Explorer.
Selecione o link Atualizar tudo para atualizar a lista de contas de armazenamento.
Expanda o nó Emulador de & anexado.
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 Blob Storage recurso

Em seu projeto de host de aplicativo, registre a integração de 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 configurar o recurso de armazenamento para ser executado localmente usando um emulador. O emulador, neste caso, é 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 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 NuGet pacote.

Client integração

Para começar com a integração .NET AspireAzure Blob Storageclient, instale o pacote NuGet 📦Aspire.Azure.Storage.Blobs no projeto que está a consumir client, ou, em outras palavras, o projeto da aplicação que utiliza o Azure Blob Storageclient. A integração Azure Blob Storageclient registra uma instância BlobServiceClient que você pode usar para interagir com Azure Blob Storage.

.NET CLI
ReferênciaDePacote

dotnet add package Aspire.Azure.Storage.Blobs

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

Adicionar Azure Blob Storageclient

No arquivo de Program.cs do seu projeto de utilização de client, invoque o método de extensão AddAzureBlobClient em qualquer IHostApplicationBuilder para registar um BlobServiceClient para uso através 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 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 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 AddAzureBlobClient:

builder.AddAzureBlobClient("blobs");

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 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 string de ligação Azure Storage pode ser utilizada.

{
  "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 suporta Microsoft.Extensions.Configuration. Ele carrega o AzureStorageBlobsSettings e o BlobClientOptions da configuração usando a chave Aspire:Azure:Storage:Blobs. O trecho 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 a integração completa do esquema Azure Blob StorageclientJSON, 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 realizar verificações de saúde.

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

Você também pode configurar o BlobClientOptions utilizando 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 user-agent para todas as solicitações emitidas por este client:

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

Client verificações de saúde 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 das 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.
Integrou-se com o endpoint HTTP /health, que especifica que todas as verificações de integridade registadas devem ser aprovadas para o aplicativo ser considerado pronto a aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Registo, Rastreio e Métricas, 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 .NET AspireAzure Blob Storage usa as seguintes categorias de log:

Azure.Core
Azure.Identity

Rastreio

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

Azure.Storage.Blobs.BlobContainerClient

Métricas

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

Partilhar via