Compartir a través de

integración de .NET AspireAzure Cache for Redis®*

  • Artículo

incluye: integración de hospedaje de e integración de Client

Azure Cache for Redis proporciona un almacén de datos en memoria basado en el software Redis. Redis mejora el rendimiento y la escalabilidad de una aplicación que usa los almacenes de datos de back-end en gran medida. Puede procesar grandes volúmenes de solicitudes de aplicación manteniendo los datos a los que se accede con frecuencia en la memoria del servidor, que se pueden escribir y leer rápidamente. Redis aporta una solución crítica de almacenamiento de datos de baja latencia y alto rendimiento a las aplicaciones modernas.

Azure Cache for Redis ofrece tanto el Redis código abierto (OSS Redis) como un producto comercial de Redis Inc. (Redis Enterprise) como servicio administrado. Proporciona instancias de servidor de Redis seguras y dedicadas y compatibilidad completa con la API de Redis. Microsoft opera el servicio, hospedado en Azurey utilizable por cualquier aplicación dentro o fuera de Azure.

La integración de .NET AspireAzure Cache for Redis permite conectarse a instancias de Azure Cache for Redis existentes o crear nuevas instancias, o ejecutarse como un contenedor localmente desde .NET con la imagen de contenedor de docker.io/library/redis.

Integración de hospedaje

La integración del alojamiento .NET AspireAzure Cache for Redis modela un recurso de AzureRedis como el tipo AzureRedisCacheResource. Para acceder a este tipo y APIs para expresarlos como recursos en el proyecto host de la aplicación , agregue el paquete NuGet 📦Aspire.Hosting.Azure.Redis.

dotnet add package Aspire.Hosting.Azure.Redis

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

Agregar AzureAzure Cache for Redis recurso

En el proyecto host de la aplicación, llame a AddAzureRedis en la instancia de builder para agregar un recurso de AzureAzure Cache for Redis, como se muestra en el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache");

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

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

La llamada anterior a AddAzureRedis configura el recurso de servidor de Redis para implementarse como un Azure Cache for Redis.

Importante

De forma predeterminada, AddAzureRedis configura la autenticación de ID de Microsoft Entra . Esto requiere cambios en las aplicaciones que necesitan conectarse a estos recursos, por ejemplo, integraciones de cliente.

Propina

Al llamar a AddAzureRedis, 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 AzureAzure Cache for Redis, se genera el siguiente Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalName string

resource redis 'Microsoft.Cache/redis@2024-03-01' = {
  name: take('redis-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    sku: {
      name: 'Basic'
      family: 'C'
      capacity: 1
    }
    enableNonSslPort: false
    disableAccessKeyAuthentication: true
    minimumTlsVersion: '1.2'
    redisConfiguration: {
      'aad-enabled': 'true'
    }
  }
  tags: {
    'aspire-resource-name': 'redis'
  }
}

resource redis_contributor 'Microsoft.Cache/redis/accessPolicyAssignments@2024-03-01' = {
  name: take('rediscontributor${uniqueString(resourceGroup().id)}', 24)
  properties: {
    accessPolicyName: 'Data Contributor'
    objectId: principalId
    objectIdAlias: principalName
  }
  parent: redis
}

output connectionString string = '${redis.properties.hostName},ssl=true'

Bicep anterior es un módulo que aprovisiona un AzureAzure Cache for Redis con los valores predeterminados siguientes:

  • location: ubicación del recurso de AzureAzure Cache for Redis. El valor predeterminado es la ubicación del grupo de recursos.
  • principalId: el ID de entidad principal del recurso de AzureAzure Cache for Redis.
  • principalName: el nombre principal del recurso de AzureAzure Cache for Redis.
  • sku: SKU del recurso de AzureAzure Cache for Redis. El valor predeterminado es Basic con una capacidad de 1.
  • enableNonSslPort: El puerto no SSL del recurso AzureAzure Cache for Redis. El valor predeterminado es false.
  • disableAccessKeyAuthentication: la autenticación de la clave de acceso del recurso AzureAzure Cache for Redis. El valor predeterminado es true.
  • minimumTlsVersion: la versión mínima de TLS del recurso de AzureAzure Cache for Redis. El valor predeterminado es 1.2.
  • redisConfiguration: La configuración Redis del recurso Azure Cache for Redis. El valor predeterminado es aad-enabled y se establece en true.
  • tags: las etiquetas del recurso de AzureAzure Cache for Redis. El valor predeterminado es aspire-resource-name establecido en el nombre del recurso de Aspire, en este caso redis.
  • redis_contributor: colaborador del recurso de AzureAzure Cache for Redis, con un nombre de directiva de acceso de Data Contributor.
  • connectionString: la cadena de conexión del recurso de AzureAzure Cache for Redis.

Además de la AzureAzure Cache for Redis, también proporciona una asignación de directiva que permite el acceso de la aplicación a la memoria caché. 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 permite personalizar el Bicep generado proporcionando una API fluida para configurar los recursos de Azure usando la API de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el kind, consistencyPolicy, locations, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de AzureAzure Cache for Redis:

builder.AddAzureRedis("redis")
    .WithAccessKeyAuthentication()
    .ConfigureInfrastructure(infra =>
    {
        var redis = infra.GetProvisionableResources()
                         .OfType<RedisResource>()
                         .Single();

        redis.Sku = new()
        {
            Family = RedisSkuFamily.BasicOrStandard,
            Name = RedisSkuName.Standard,
            Capacity = 1,                    
        };
        redis.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 RedisResource.
    • El Sku se configura con una familia de BasicOrStandard, un nombre de Standardy una capacidad de 1.
    • Se agrega una etiqueta al recurso de Redis con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso AzureAzure Cache for Redis. Para obtener más información, consulte Azure.Provisioning.Redis. Para obtener más información, vea Azure. Personalización del aprovisionamiento.

Conexión a un AzureAzure Cache for Redis existente

Puede que ya tenga un AzureAzure Cache for Redis al que desea conectarse. En lugar de representar un nuevo recurso de AzureAzure Cache for Redis, puede agregar una cadena de conexión al host de la aplicación. Para agregar una conexión a un AzureAzure Cache for Redisexistente, llame al método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddConnectionString("azure-redis");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cache);

// 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": {
        "azure-redis": "<your-redis-name>.redis.cache.windows.net:6380,ssl=true,abortConnect=False"
    }
}

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 "azure-redis". La API GetConnectionString es una forma abreviada de IConfiguration.GetSection("ConnectionStrings")[name].

Ejecutar el recurso AzureAzure Cache for Redis como contenedor

La integración de hospedaje de Azure Cache for Redis admite la ejecución del servidor Redis como contenedor local. Esto es beneficioso para situaciones en las que desea ejecutar el servidor de Redis localmente con fines de desarrollo y pruebas, evitando la necesidad de aprovisionar un recurso de Azure o conectarse a un servidor de Azure Cache for Redis existente.

Para usar la imagen de contenedor de docker.io/library/redis y ejecutar la instancia de AzureAzure Cache for Redis como contenedor localmente, encadene una llamada a RunAsContainer, como se muestra en el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")
                   .RunAsContainer();

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

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

El código anterior configura el recurso Redis para que se ejecute localmente en un contenedor.

Consejo (if "Tip" refers to advice).

El método RunAsContainer es útil para el desarrollo y las pruebas locales. La API expone un delegado opcional que le permite personalizar la configuración subyacente de RedisResource, como agregar Redis Insights, Redis Commander, un volumen de datos o un montaje de enlace de datos. Para obtener más información, consulte la .NET AspireRedis integración de alojamiento.

Configuración del recurso de AzureAzure Cache for Redis para usar la autenticación de clave de acceso

De forma predeterminada, el recurso de AzureAzure Cache for Redis está configurado para usar autenticación de Microsoft Entra ID. Si desea usar la autenticación de contraseña (no recomendada), puede configurar el servidor para que use la autenticación de contraseña llamando al método WithAccessKeyAuthentication:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")
                   .WithAccessKeyAuthentication();

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

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

El código anterior configura el recurso AzureAzure Cache for Redis para usar la autenticación de clave de acceso. Esto modifica el Bicep generado para usar la autenticación con clave de acceso en lugar de la autenticación con Microsoft Entra ID. En otras palabras, la cadena de conexión contendrá una contraseña y se agregará a un secreto de Azure Key Vault.

integración de Client

Para empezar a trabajar con la integración de cliente de .NET Aspire Stack Exchange Redis, instale el 📦Aspire.StackExchange.Redis paquete de NuGet en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente de Redis. La integración del cliente Redis registra una instancia de IConnectionMultiplexer que puede utilizar para interactuar con Redis.

dotnet add package Aspire.StackExchange.Redis

Agregar cliente Redis

En el archivo Program.cs del proyecto que consume el cliente, llame al método de extensión AddRedisClient en cualquier IHostApplicationBuilder para registrar un IConnectionMultiplexer para su uso a través del contenedor de inserción de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddRedisClient(connectionName: "cache");

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso AzureAzure Cache for Redis en el proyecto host de la aplicación. Para obtener más información, consulte Agregar AzurerecursoAzure Cache for Redis.

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

public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.

Agregar AzureAzure Cache for Redis cliente autenticado

De forma predeterminada, al llamar a AddAzureRedis en la integración de hospedaje de Redis, se configura Microsoft Entra ID. Instale el 📦 Microsoft.Azure. StackExchangeRedis paquete NuGet para habilitar la autenticación:

dotnet add package Microsoft.Azure.StackExchangeRedis

La conexión Redis se puede consumir utilizando la integración del cliente y Microsoft.Azure.StackExchangeRedis. Tenga en cuenta el código de configuración siguiente:

var azureOptionsProvider = new AzureOptionsProvider();

var configurationOptions = ConfigurationOptions.Parse(
    builder.Configuration.GetConnectionString("cache") ?? 
    throw new InvalidOperationException("Could not find a 'cache' connection string."));

if (configurationOptions.EndPoints.Any(azureOptionsProvider.IsMatch))
{
    await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(
        new DefaultAzureCredential());
}

builder.AddRedisClient("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

Para obtener más información, consulte el Microsoft.Azure. Repositorio de StackExchangeRedis.

Adición de un cliente de Redis con clave

Puede haber situaciones en las que quiera registrar varias instancias de IConnectionMultiplexer con nombres de conexión diferentes. Para registrar clientes de Redis con clave, llame al método AddKeyedRedisClient:

builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");

A continuación, puede recuperar las instancias de IConnectionMultiplexer mediante la inserción de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

Para obtener más información sobre los servicios con claves, consulte .NET inserción de dependencias: Servicios con claves.

Configuración

La integración de cliente de Redis.NET Aspire Stack Exchange proporciona varias opciones para configurar la conexión Redis 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 AddRedis:

builder.AddRedis("cache");

A continuación, la cadena de conexión se recuperará de la sección de configuración ConnectionStrings:

{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

Para obtener más información sobre cómo dar formato a esta cadena de conexión, consulte los documentos de configuración deStack Exchange Redis.

Uso de proveedores de configuración

La integración de .NET Aspire Stack Exchange Redis es compatible con Microsoft.Extensions.Configuration. Carga el StackExchangeRedisSettings desde la configuración mediante la clave Aspire:StackExchange:Redis. Ejemplo appsettings.json que configura algunas de las opciones:

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Para el esquema completo de integración de cliente RedisJSON, consulte Aspire.StackExchange.Redis/ConfigurationSchema.json.

Usar delegados en línea

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

builder.AddRedisClient(
    "cache",
    static settings => settings.DisableTracing = true);

comprobaciones de estado de integración de Client

De forma predeterminada, las integraciones de cliente .NET.NET Aspire están habilitadas para las comprobaciones de estado de todos los servicios. Del mismo modo, muchas .NET.NET Aspireintegraciones de hospedaje también habilitan los puntos de comprobación de estado. Para obtener más información, consulte:

La integración de .NET Aspire Stack Exchange Redis controla lo siguiente:

  • Agrega la comprobación de estado cuando StackExchangeRedisSettings.DisableHealthChecks es false, que intenta conectarse a la instancia del contenedor.
  • 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 características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección de configuración ,.

Registro

La integración de .NET Aspire Stack Exchange Redis usa las siguientes categorías de registro:

  • Aspire.StackExchange.Redis

Rastreo

La integración de .NET Aspire Stack Exchange Redis emitirá las siguientes actividades de seguimiento usando OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

La integración Redis de .NET Aspire Stack actualmente no admite métricas por defecto debido a limitaciones con la biblioteca de StackExchange.Redis.

Consulte también

*: Redis es una marca registrada de Redis Ltd. Cualquier derecho de la misma está reservado a Redis Ltd. El uso por parte de Microsoft es solo para fines referenciales y no indica ningún patrocinio, aprobación o afiliación entre Redis y Microsoft. ¿Volver al principio?