Integración de Tablas de Datos .NET AspireAzure

Incluye:integración de hospedaje y integraciónClient

Azure Table Storage es un servicio para almacenar datos NoSQL estructurados. La integración de tablas de datos de .NET AspireAzure permite conectarse a instancias de Azure Table Storage existentes o crear nuevas instancias a partir de aplicaciones .NET.

Integración de hospedaje

El .NET.NET AspireAzure Storage modela la integración de hospedaje de los diversos recursos de almacenamiento como 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 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 de host de la aplicación .

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 Administrar dependencias de paquetes en aplicaciones .NET.

Agregar recurso de almacenamiento Azure

En el proyecto host de la aplicación, llame a AddAzureStorage para añadir y devolver un generador de recursos Storage 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 almacenamiento de blobs, colas y tablas. En otras palabras, debe agregar un AzureStorageResource antes de agregar cualquiera de los demás recursos de almacenamiento.

Bicep de aprovisionamiento generado

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir los 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 genera como salida junto con el archivo de manifiesto. Al agregar un recurso de Azure Storage, se genera el siguiente 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. Consulte el roles integrados Azure control de acceso basado en rol (Azure RBAC) para obtener más información:

El Bicep generado es un punto de partida y se puede adaptar 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 al proporcionar una API fluida para configurar los recursos de Azure con 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...

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 manera abreviada de referirse a IConfiguration.GetSection("ConnectionStrings")[name].

Añadir 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 lifetime, 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:

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:

Configurar el contenedor de Azurite con tiempo de vida 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 ciclo de vida del recurso de contenedor.

Configurar 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 conservar los datos de Azurite fuera del ciclo de vida del 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 enlazar montajes, consulte Docker documentos: Volúmenes.

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

Para agregar un montaje de vinculación 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...

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 montaje de enlace de datos se monta en la ruta ../Azurite/Data del equipo anfitrión, relativo al directorio anfitrión de la aplicación (IDistributedApplicationBuilder.AppHostDirectory) en el contenedor de Azurite. Para obtener más información sobre los montajes vinculantes de datos, consulte la documentación sobre montajes con enlace Docker.

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 Azure. Si el recurso de almacenamiento se ejecuta localmente mediante Azurite, el Explorador de Storage Azure lo recogerá automáticamente.

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

1. Ejecute el host de la aplicación .NET.NET Aspire.

2. Abra el Explorador de Azure Storage.

3. Vea el panel del Explorador .

4. Seleccione el vínculo Actualizar todo para actualizar la lista de cuentas de almacenamiento.

5. Expanda el nodo emulador asociado de &.

6. Expanda el nodo "Cuentas de Almacenamiento" de "" "".

7. 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 Table Storage recurso

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

El código anterior:

• Agrega un recurso de Azure Storage denominado storage.
• Agrega un recurso de almacenamiento de tablas denominado tables al recurso de almacenamiento.
• Agrega el recurso storage al ExampleProject y espera a que esté listo antes de iniciar el proyecto.

Hospedaje de comprobaciones de estado de integración

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 Tablas de Datos .NET AspireAzureclient, instale el paquete NuGet de 📦Aspire.Azure.Data.Tables en el proyecto que consume client, es decir, el proyecto de la aplicación que usa las Tablas de Datos Azureclient. La integración Azure Data Tables client registra una instancia de TableServiceClient que puedes usar para interactuar con Azure Table Storage.

dotnet add package Aspire.Azure.Data.Tables

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

Agregar Azure Table Storageclient

En el archivo Program.cs del proyecto que consume client, llame al método de extensión AddAzureTableClient en cualquier IHostApplicationBuilder para registrar un TableServiceClient para usar a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddAzureTableClient("tables");

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

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

Configuración

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

Uso de proveedores de configuración

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

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

Para el esquema completo de integración de tablas de datos AzureclientJSON, consulte Aspire.Azure. Data.Tables/ConfigurationSchema.json.

Utilizar delegados en línea

También puede pasar el delegado de Action<AzureDataTablesSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para configurar el ServiceUri:

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

También puede configurar el TableClientOptions mediante el delegado Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder, el segundo parámetro del método AddAzureTableClient. Por ejemplo, para establecer el identificador de TableServiceClient para identificar el client:

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

comprobaciones de estado de 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.

Integración de tablas de datos .NET AspireAzure

• Agrega la comprobación de estado cuando AzureDataTablesSettings.DisableHealthChecks es false, que intenta conectarse al Azure Table 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 pueda considerarse lista para recibir 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 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 tablas de datos de .NET AspireAzure usa las siguientes categorías de registro:

• Azure.Core
• Azure.Identity

Seguimiento

La integración de las tablas de datos .NET AspireAzure emite las siguientes actividades de rastreo mediante OpenTelemetry:

• Azure.Data.Tables.TableServiceClient

Métricas

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

Consulte también

• Azure Table Storage documentos
• .NET .NET Aspire integraciones
• .NET Aspire GitHub repo