integración de .NET AspireAzure Blob Storage

Artículo
12/13/2024

Incluye:integración de hospedaje y Client

Azure Blob Storage es un servicio para almacenar grandes cantidades de datos no estructurados. La integración de .NET AspireAzure Blob Storage permite conectarse a instancias de Azure Blob Storage existentes o crear nuevas instancias a partir de aplicaciones .NET.

Integración de hospedaje

El modelo de integración de alojamiento de .NET.NET AspireAzure Storage representa los diversos recursos de almacenamiento de los siguientes tipos:

AzureStorageResource: representa un recurso de almacenamiento de Azure.
AzureStorageEmulatorResource: representa un recurso del emulador de Azure Storage (Azurite).
AzureBlobStorageResource: Representa un recurso de almacenamiento Blob de Azure.
AzureQueueStorageResource: Representa un recurso de almacenamiento de colas Azure.
AzureTableStorageResource: representa un recurso de almacenamiento de tabla de Azure.

Para acceder a estos tipos y API para expresarlos, agregue el paquete NuGet 📦Aspire.Hosting.Azure.Storage en el proyecto host de la aplicación .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

Para obtener más información, consulte dotnet add package o Gestionar dependencias de paquetes en aplicaciones .NET.

Agregar recurso de almacenamiento Azure

En el proyecto host de la aplicación, llame a AddAzureStorage para agregar y devolver un generador de recursos de Azure Storage.

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...

Al agregar un AzureStorageResource al host de la aplicación, expone otras API útiles para agregar Azure recursos de Blob, Queue y Table Storage. En otras palabras, debe agregar un AzureStorageResource antes de agregar cualquiera de los demás recursos de almacenamiento.

Importante

Al llamar a AddAzureStorage, llama implícitamente a AddAzureProvisioning, lo que agrega compatibilidad para generar recursos de Azure dinámicamente durante el inicio de la aplicación. La aplicación debe configurar la suscripción y la ubicación adecuadas. Para obtener más información, consulte aprovisionamiento local: Configuración.

Bicep de aprovisionamiento generado

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar tu aplicación, el Bicep generado se produce junto con el archivo de manifiesto. Al agregar un recurso de almacenamiento Azure, se genera el siguiente Bicep:

Alternar Azure Storage 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

Bicep anterior es un módulo que aprovisiona una cuenta de almacenamiento de Azure con los valores predeterminados siguientes:

kind: el tipo de cuenta de almacenamiento. El valor predeterminado es StorageV2.
sku: SKU de la cuenta de almacenamiento. El valor predeterminado es Standard_GRS.
properties: las propiedades de la cuenta de almacenamiento:
- accessTier: nivel de acceso de la cuenta de almacenamiento. El valor predeterminado es Hot.
- allowSharedKeyAccess: valor booleano que indica si la cuenta de almacenamiento permite autorizar las solicitudes con la clave de acceso de la cuenta. El valor predeterminado es false.
- minimumTlsVersion: la versión mínima admitida de TLS para la cuenta de almacenamiento. El valor predeterminado es TLS1_2.
- networkAcls: las ACL de red de la cuenta de almacenamiento. El valor predeterminado es { defaultAction: 'Allow' }.

Además de la cuenta de almacenamiento, también aprovisiona un contenedor de blobs.

Las siguientes asignaciones de roles se agregan a la cuenta de almacenamiento para conceder acceso a la aplicación. Para obtener más información, consulte los roles integrados de control de acceso basado en roles (Azure RBAC) Azure.

Rol o identificador	Descripción
Colaborador de datos de Storage Blob `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Leer, escribir y eliminar Azure contenedores y blobs de Storage.
Colaborador de datos de almacenamiento en tabla `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Leer, escribir y eliminar tablas y entidades de almacenamiento Azure.
Colaborador de datos de cola de almacenamiento `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Leer, escribir y eliminar Azure colas y mensajes de cola de Storage.

El Bicep generado es un punto de partida y se puede personalizar para satisfacer sus requisitos específicos.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo habilita la personalización del Bicep generado, proporcionando una API fluida para configurar los recursos de Azure utilizando la API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el kind, sku, properties, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de almacenamiento de 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");
    });

El código anterior:

Encadena una llamada a la API de ConfigureInfrastructure:
- El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
- Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
- Se recupera el único StorageAccount.
- El StorageAccount.AccessTier se asigna a StorageAccountAccessTier.Cool.
- El StorageAccount.Sku se asigna a un nuevo StorageSku con un Name de PremiumZrs.
- Se agrega una etiqueta a la cuenta de almacenamiento con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso de almacenamiento de Azure. Para obtener más información, consulte Azure.Provisioning.Storage.

Conexión a una cuenta de almacenamiento de Azure existente

Es posible que tenga una cuenta de almacenamiento de Azure existente a la que desea conectarse. En lugar de representar un nuevo recurso de almacenamiento de Azure, puede agregar una cadena de conexión al host de la aplicación. Para agregar una conexión a una cuenta de almacenamiento de Azure existente, llame al 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

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en secretos de usuario, en la sección ConnectionStrings. El host de la aplicación inserta esta cadena de conexión como una variable de entorno en todos los recursos dependientes, por ejemplo:

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

El recurso dependiente puede acceder a la cadena de conexión insertada llamando al método GetConnectionString y pasando el nombre de conexión como parámetro, en este caso "blobs". La API de GetConnectionString es una abreviatura de IConfiguration.GetSection("ConnectionStrings")[name].

Agregar el recurso del emulador de almacenamiento Azure

Para agregar un recurso del emulador de almacenamiento de Azure, encadene una llamada en un IResourceBuilder<AzureStorageResource> a la API de RunAsEmulator.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Al llamar a RunAsEmulator, configura los recursos de almacenamiento para que se ejecuten localmente mediante un emulador. En este caso, el emulador es Azurite. El emulador de código abierto de Azurite proporciona un entorno local gratuito para probar los Azure aplicaciones de Blob, Queue Storage y Table Storage, y es un complemento perfecto para la integración de hospedaje de .NET AspireAzure. Azurite no está instalado, sino que es accesible para .NET.NET Aspire como contenedor. Al agregar un contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de mcr.microsoft.com/azure-storage/azurite, crea e inicia el contenedor cuando se inicia el host de la aplicación. Para obtener más información, consulte ciclo de vida de los recursos de contenedores.

Configuración del contenedor de Azurite

Hay varias configuraciones disponibles para los recursos de contenedor, por ejemplo, puede configurar los puertos del contenedor, las variables de entorno, su duracióny más.

Configuración de puertos de contenedor de Azurite

De forma predeterminada, el contenedor de Azurite cuando se configura mediante .NET.NET Aspire, expone los siguientes puntos de conexión:

Punto final	Puerto de contenedor	Puerto de anfitrión
`blob`	10.000	dinámico
`queue`	10001	dinámico
`table`	10002	dinámico

El puerto en el que están escuchando es dinámico de forma predeterminada. Cuando se inicia el contenedor, los puertos se asignan a un puerto aleatorio en el equipo host. Para configurar los puertos de punto de conexión, encadene las llamadas en el generador de recursos de contenedor proporcionados por el método RunAsEmulator como se muestra en el ejemplo siguiente:

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...

El código anterior configura los puntos de conexión existentes del contenedor de Azurite blob, queuey table para escuchar en los puertos 27000, 27001y 27002, respectivamente. Los puertos del contenedor de Azurite se asignan a los puertos host, como se muestra en la tabla siguiente:

Nombre del punto de conexión	Asignación de puertos (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Configurar el contenedor de Azurite con una duración persistente

Para configurar el contenedor de Azurite con una duración persistente, llame al método WithLifetime en el recurso de contenedor de Azurite y pase 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 obtener más información, consulte vida útil del recurso del contenedor.

Configurar el contenedor Azurite con volumen de datos

Para agregar un volumen de datos al recurso del emulador de Azure Storage, llame al método WithDataVolume en el recurso del emulador de almacenamiento de Azure:

var builder = DistributedApplication.CreateBuilder(args);

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

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

El volumen de datos se utiliza para persistir los datos de Azurite fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta de acceso /data del contenedor de Azurite, y cuando no se proporciona un parámetro name, el nombre se formatea como .azurite/{resource name}. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a enlazar montajes, consulte Docker documentos: Volúmenes.

Configuración del contenedor de Azurite con montaje de enlace de datos

Para agregar una vinculación de datos al recurso del emulador de almacenamiento Azure, llame al 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

Los montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen un mejor rendimiento, portabilidad y seguridad, por lo que son más adecuados para entornos de producción. Sin embargo, las monturas de vinculación permiten el acceso directo y la modificación de archivos en el sistema anfitrión, ideal para el desarrollo y las pruebas cuando se necesitan cambios en tiempo real.

Los montajes de enlace de datos dependen del sistema de archivos del equipo host para conservar los datos de Azurite en los reinicios del contenedor. El enlace de montaje de datos se monta en la ruta de acceso ../Azurite/Data en el equipo host en relación con el directorio host de la aplicación (IDistributedApplicationBuilder.AppHostDirectory) en el contenedor de Azurite. Para obtener más información sobre los montajes de enlace de datos, consulte la documentación de Docker: Montajes de enlace.

Conexión a recursos de almacenamiento

Cuando se ejecuta el host de la aplicación .NET.NET Aspire, las herramientas externas pueden acceder a los recursos de almacenamiento, como el Explorador de Almacenamiento de Azure. Si el recurso de almacenamiento se ejecuta localmente mediante Azurite, el Explorador de Storage Azure lo recogerá automáticamente.

Nota

El Azure Explorador de Storage detecta los recursos de almacenamiento de Azurite, suponiendo que se usen los puertos predeterminados. Si ha configurado el contenedor de Azurite para usar puertos diferentes, deberá configurar el Explorador de Storage de Azure para conectarse a los puertos correctos.

Para conectarse al recurso de almacenamiento desde el Explorador de Almacenamiento Azure, siga estos pasos:

Ejecute el host de la aplicación .NET.NET Aspire.
Abra el Explorador de Azure Storage.
Vea el panel del Explorador .
Seleccione el vínculo Actualizar todo para actualizar la lista de cuentas de almacenamiento.
Expanda el nodo adjunto del emulador & de .
Expanda el nodo Cuentas de Almacenamiento.
Debería ver una cuenta de almacenamiento con el nombre del recurso como prefijo:

Puede explorar la cuenta de almacenamiento y su contenido mediante el Explorador de Storage de Azure. Para obtener más información sobre el uso del Explorador de Azure Storage, consulte Introducción al Explorador de Storage.

Agregar Azure Blob Storage recurso

En el proyecto host de la aplicación, registre la integración de Azure Blob Storage encadenando una llamada a AddBlobs en la instancia de IResourceBuilder<IAzureStorageResource> devuelta por AddAzureStorage. En el ejemplo siguiente se muestra cómo agregar un recurso de Azure Blob Storage denominado storage y un contenedor de blobs denominado 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...

El código anterior:

Agrega un recurso de Azure Storage denominado storage.
Encadena una llamada a RunAsEmulator para configurar el recurso de almacenamiento para que se ejecute localmente mediante un emulador. En este caso, el emulador es Azurite.
Agrega un contenedor de blobs denominado blobs al recurso de almacenamiento.
Agrega el recurso blobs al ExampleProject y espera a que esté listo antes de iniciar el proyecto.

Comprobaciones de estado de la integración de hospedaje

La integración de hospedaje de Azure Storage agrega automáticamente una comprobación de estado para el recurso de almacenamiento. Solo se agrega cuando se ejecuta como emulador y comprueba que el contenedor de Azurite se está ejecutando y que se puede establecer una conexión a él. La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.Azure.Storage.Blobs.

integración de Client

Para empezar a trabajar con la integración de .NET AspireAzure Blob Storageclient, instale el paquete NuGet 📦Aspire.Azure.Storage.Blobs en el proyecto de consumo de client, específicamente, en el proyecto de la aplicación que usa Azure Blob Storageclient. La integración de Azure Blob Storageclient registra una instancia de BlobServiceClient que puede usar para interactuar con Azure Blob Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Blobs

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

Agregar Azure Blob Storageclient

En el archivo Program.cs de su proyecto que consume client, utilice el método de extensión AddAzureBlobClient en cualquier IHostApplicationBuilder para registrar un BlobServiceClient para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddAzureBlobClient("blobs");

A continuación, puede recuperar la instancia de BlobServiceClient mediante la inyección de dependencias. Por ejemplo, para recuperar el client de un servicio:

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

Configuración

La integración de .NET AspireAzure Blob Storage proporciona varias opciones para configurar el BlobServiceClient en función de los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar a AddAzureBlobClient:

builder.AddAzureBlobClient("blobs");

A continuación, la cadena de conexión se recupera de la sección de configuración de ConnectionStrings y se admiten dos formatos de conexión:

URI del servicio

El enfoque recomendado es usar un ServiceUri, que funciona con la propiedad AzureStorageBlobsSettings.Credential para establecer una conexión. Si no se configura ninguna credencial, se usa el Azure.Identity.DefaultAzureCredential.

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

Cadena de conexión

Como alternativa, se puede usar una cadena de conexión de almacenamiento Azure.

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

Para obtener más información, consulte Configurar las cadenas de conexión de Azure Storage.

Uso de proveedores de configuración

La integración de .NET AspireAzure Blob Storage admite Microsoft.Extensions.Configuration. Carga el AzureStorageBlobsSettings y el BlobClientOptions desde la configuración mediante la clave Aspire:Azure:Storage:Blobs. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

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

Para obtener el esquema de integración completo Azure Blob StorageclientJSON, consulte Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Uso de delegados en línea

También puede pasar el delegado de Action<AzureStorageBlobsSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para verificar el estado de salud.

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

También puede configurar el BlobClientOptions mediante el delegado Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder, el segundo parámetro del método AddAzureBlobClient. Por ejemplo, para establecer la primera parte de los encabezados de user-agent para todas las solicitudes emitidas por este client:

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

comprobaciones de estado de la integración de Client

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan las verificaciones de salud de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración de .NET AspireAzure Blob Storage:

Agrega la comprobación de estado cuando AzureStorageBlobsSettings.DisableHealthChecks es false, que intenta conectarse al Azure Blob Storage.
Se integra con el punto de conexión HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben pasar para que la aplicación se considere lista para aceptar el tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las funcionalidades de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

La integración de .NET AspireAzure Blob Storage usa las siguientes categorías de registro:

Azure.Core
Azure.Identity

Seguimiento

La integración de .NET AspireAzure Blob Storage emite las siguientes actividades de seguimiento mediante OpenTelemetry:

Azure.Storage.Blobs.BlobContainerClient

Métricas

La integración de .NET AspireAzure Blob Storage actualmente no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure.

Compartir a través de