Integración de almacenamiento de colas .NET AspireAzure

Artículo
12/15/2024

Incluye:integración de hosting y Client

Azure Queue Storage es un servicio para almacenar un gran número de mensajes a los que se puede acceder desde cualquier lugar del mundo a través de llamadas autenticadas. La integración de .NET AspireAzure Queue Storage le permite conectarse a instancias existentes de Azure Queue Storage o crear nuevas instancias a partir de aplicaciones .NET.

Integración de hospedaje

El modelo de integración de almacenamiento .NET.NET AspireAzure organiza los distintos recursos de almacenamiento en 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 Azure Blob Storage.
AzureQueueStorageResource: representa un recurso de Queue Storage Azure.
AzureTableStorageResource: Representa un recurso de almacenamiento de tablas de Azure.

Para acceder a estos tipos y API para expresarlos, agregue el 📦Aspire.Hosting.Azure.Storage paquete NuGet 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 las 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 almacenamiento 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...

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 eres nuevo en 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 entrega 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 provisiona un contenedor de blobs.

Las siguientes asignaciones de roles se agregan a la cuenta de almacenamiento para conceder acceso a la aplicación. Consulte el roles integrados Azure control de acceso basado en rol (Azure RBAC) para obtener más información:

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.
Contribuyente de datos en tablas de almacenamiento `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Leer, escribir y eliminar entidades y tablas de Azure Storage.
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 solo un punto de partida y puede personalizarse 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 mediante la API de 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 abreviación de IConfiguration.GetSection("ConnectionStrings")[name].

Agregar recurso Azure del emulador de almacenamiento

Para agregar un recurso del emulador de almacenamiento del 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 del contenedor.

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, es duración, etc.

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 acogida
`blob`	10000	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 extremos, encadene las llamadas en el constructor de recursos del contenedor proporcionado por el método RunAsEmulator como se muestra en el siguiente ejemplo:

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`

Configuración del contenedor de Azurite con 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.

Configuración del contenedor de 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 mantener los datos de Azurite más allá 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 tiene el formato .azurite/{resource name}. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a montajes de enlace, consulte Docker documentación: Volúmenes.

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

Para agregar un punto de montaje de enlace de datos al recurso del emulador de Azure Storage, 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, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes con enlace permiten el acceso directo y la modificación de archivos en el sistema host, siendo ideales para el desarrollo y las pruebas en las que se necesitan cambios en tiempo real.

Las vinculaciones de datos dependen del sistema de archivos de la máquina anfitriona para conservar los datos de Azurite a través de los reinicios del contenedor. El montaje del enlace de datos se monta en la ruta de acceso de ../Azurite/Data en el equipo host con respecto al 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 los documentos de Docker: Montajes de enlace.

Conexión a recursos de almacenamiento

Cuando se ejecuta el host de la aplicación .NET.NET Aspire, los recursos de almacenamiento pueden ser accedidos por herramientas externas, como el Explorador de Almacenamiento 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 Explorador.
Seleccione el vínculo Actualizar todo para actualizar la lista de cuentas de almacenamiento.
Expanda el nodo adjunto del emulador &.
Expande 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 recurso de Queue Storage

En el proyecto host de la aplicación, registre la integración de Azure Queue Storage encadenando una llamada a AddQueues en la instancia de IResourceBuilder<IAzureStorageResource> devuelta por AddAzureStorage. En el ejemplo siguiente se muestra cómo agregar un recurso de Queue Storage Azure denominado storage y un recurso de cola denominado queues:

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

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

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

El código anterior:

Agrega un recurso de Azure Storage denominado storage.
Agrega una cola llamada queues al recurso de almacenamiento.
Agrega el recurso storage al ExampleProject y espera a que esté listo antes de iniciar el proyecto.

Comprobaciones de salud de integraciones 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 📦 AspNetCore.HealthChecks.Azure. Storage.Blobs paquete NuGet.

integración de Client

Para empezar a trabajar con la integración de .NET AspireAzure Queue Storage client, instale el paquete NuGet 📦Aspire.Azure.Storage.Queues en el proyecto que consume client, es decir, el proyecto de aplicación que utiliza Azure Queue Storage client. La integración de Azure Queue Storage client registra una instancia de QueueServiceClient que puede usar para interactuar con Azure Queue Storage.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

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

Agregar Azure Queue Storage client

En el archivo Program.cs de tu proyecto que consume client, llama al método de extensión AddAzureQueueClient en cualquier IHostApplicationBuilder para registrar un QueueServiceClient 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.AddAzureQueueClient("queue");

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

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

Configuración

La integración de .NET AspireAzure Queue Storage proporciona varias opciones para configurar el QueueServiceClient 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 AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

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 AzureStorageQueuesSettings.Credential para establecer una conexión. Si no se configura ninguna credencial, se usa el Azure.Identity.DefaultAzureCredential.

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

Cadena de conexión

Como alternativa, puede utilizarse una cadena de conexión de Azure Storage.

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

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

Uso de proveedores de configuración

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

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

Para el esquema completo de integración Azure Storage QueuesclientJSON, consulte Aspire.Azure.Data.Queues/ConfigurationSchema.json.

Uso de delegados en línea

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

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

También puede configurar el QueueClientOptions mediante el delegado Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder, que es el segundo parámetro del método AddAzureQueueClient. Por ejemplo, para establecer la primera parte de las cabeceras del agente de usuario para todas las solicitudes emitidas por este client:

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

comprobaciones de salud de integración de Client

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

La integración de .NET AspireAzure Queue Storage:

Agrega la comprobación de estado cuando AzureStorageQueuesSettings.DisableHealthChecks es false, que intenta conectarse al almacenamiento en cola de Azure.
Se integra con el punto de conexión HTTP de /health, el cual especifica que todas las verificaciones de salud registradas deben completarse para que la aplicación esté lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire Las integraciones configuran automáticamente el registro de eventos, el seguimiento y las 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 características 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 Queue Storage usa las siguientes categorías de registro:

Azure.Core
Azure.Identity

Rastreo

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

Azure.Storage.Queues.QueueClient

Métricas

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

Compartir a través de