.NET Aspire Azure Cache for Redis®^* integración

Incluye: Integración de alojamiento —&— Client integración

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 .NET AspireAzure Cache for Redis permite conectarse a instancias existentes Azure Cache for Redis, crear una nueva instancia o ejecutar como un contenedor localmente desde .NET con la imagen de contenedor 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 estos tipos y API para expresarlos como recursos en su proyecto app host, instale el paquete 📦Aspire.Hosting.Azure.Redis NuGet:

dotnet add package Aspire.Hosting.Azure.Redis

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

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

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 Redis para que se implemente como un Azure Cache for Redis.

Bicep generado por el aprovisionamiento

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir Azure recursos. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar la aplicación, el Bicep generado se muestra 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

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'
  }
}

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

output name string = redis.name

El Bicep anterior es un módulo que aprovisiona un recurso AzureAzure Cache for Redis. Además, las asignaciones de roles se crean para el Azure recurso en un módulo independiente:

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

param redis_outputs_name string

param principalId string

param principalName string

resource redis 'Microsoft.Cache/redis@2024-03-01' existing = {
  name: redis_outputs_name
}

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

Además del AzureAzure Cache for Redis, también aprovisiona una asignación de política de acceso para el acceso de la aplicación a la caché. El Bicep generado es un punto de partida y se ve influido por los cambios en la infraestructura de aprovisionamiento en C#. Las personalizaciones realizadas directamente en el archivo Bicep se sobrescribirán, por lo que los cambios deben realizarse a través de las API de aprovisionamiento de C# para garantizar que se reflejen en los archivos generados.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo permite la personalización del Bicep generado proporcionando una API fluida para configurar los recursos Azure mediante la API 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 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 establece con una familia de BasicOrStandard, un nombre de Standard, y 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

Es posible que tenga un recurso existente AzureAzure Cache for Redis al que quiera conectarse. Puede encadenar una llamada para anotar que su AzureRedisCacheResource es un recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingRedisName = builder.AddParameter("existingRedisName");
var existingRedisResourceGroup = builder.AddParameter("existingRedisResourceGroup");

var cache = builder.AddAzureRedis("azcache")
                   .AsExisting(existingRedisName, existingRedisResourceGroup);

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

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

Para obtener más información sobre cómo tratar los recursos de AzureAzure Cache for Redis como recursos existentes, consulte Uso de recursos de Azure existentes.

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.

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

Por defecto, el recurso AzureAzure Cache for Redis está configurado para utilizar la autenticación 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 con Client

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

dotnet add package Aspire.StackExchange.Redis

<PackageReference Include="Aspire.StackExchange.Redis"
                  Version="*" />

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 inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddRedisClient(connectionName: "cache");

A continuación, puede recuperar la instancia IConnectionMultiplexer utilizando la inyección de dependencia. 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 Microsoft.Azure. Paquete NuGet StackExchangeRedis para habilitar la autenticación:

dotnet add package Microsoft.Azure.StackExchangeRedis

<PackageReference Include="Microsoft.Azure.StackExchangeRedis"
                  Version="*" />

La conexión Redis se puede consumir utilizando la integración de 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 repositorio Microsoft.Azure.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");

Luego puede recuperar las instancias IConnectionMultiplexer usando inyecció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 .NET AspireRedis 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 RedisStack Exchange .

Uso de proveedores de configuración

La integración de .NET Aspire Stack Exchange Redis es compatible con Microsoft.Extensions.Configuration. Carga el StackExchangeRedisSettings de configuración utilizando 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 obtener el esquema completo Redis de integración de clientes JSON, consulte Aspire.StackExchange.Redis/ConfigurationSchema.json.

Utilice delegados en línea

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

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

Client comprobaciones de estado de la integración

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 hosting también permiten puntos finales de comprobación de estado. Para obtener más información, consulte:

• .NET comprobaciones de estado de la aplicación en C#
• Verificaciones de salud en ASP.NET Core

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 endpoint HTTP /health, que especifica que todas las verificaciones de estado registradas deben aprobarse para que la aplicación se considere lista para aceptar el tráfico.

Observabilidad y telemetría

.NET.NET Aspire las 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 y la telemetría de integración, consulte .NET.NET Aspire La introducción a las integraciones. 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 funciones 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

Seguimiento

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 .NET Aspire Stack Exchange Redis actualmente no soporta métricas por defecto debido a limitaciones con la biblioteca StackExchange.Redis.

Consulte también

• AzureAzure Cache for Redis Docs
• Documentación de Stack Exchange Redis
• .NET.NET Aspire Integraciones
• .NET Aspire GitHub repositorio

*: Redis es una marca registrada de Redis Ltd. Todos los derechos son reservados a Redis Ltd. Cualquier uso por parte de Microsoft es solo para fines de referencia y no indica ningún patrocinio, aprobación o afiliación entre Redis y Microsoft. ¿Volver al principio?