Compartir a través de

integración de .NET AspireRedis®*

  • Artículo

Incluye:integración de hospedaje y integraciónClient

Redis es la plataforma de datos más rápida del mundo para almacenar en caché, buscar vectores y bases de datos NoSQL. La integración de .NET AspireRedis permite conectarse a instancias de Redis existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor docker.io/library/redis.

Garnet es un almacén de caché de alto rendimiento de Microsoft Research y cumple con el protocolo de serialización de Redis (RESP). La integración de .NET AspireRedis permite conectarse a instancias de Garnet existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor de ghcr.io/microsoft/garnet.

Valkey es una bifurcación de y cumple con el protocolo de serialización de (RESP). Es un almacén de datos de clave y valor de alto rendimiento que admite una variedad de cargas de trabajo, como el almacenamiento en caché, las colas de mensajes y puede actuar como base de datos principal. La integración de .NET AspireRedis permite conectarse a instancias de Valkey existentes o crear nuevas instancias desde .NET con la imagen de contenedor de docker.io/valkey/valkey.

Integración de hospedaje

La integración de alojamiento de Redis modela un recurso de Redis como un tipo RedisResource. Para acceder a este tipo y las API que le permiten agregarlo a su 📦Aspire.Hosting.Redis paquete NuGet en el proyecto del host de la aplicación de .

dotnet add package Aspire.Hosting.Redis

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

Agregar Redis recurso

En el proyecto host de la aplicación, llame a AddRedis en la instancia de builder para agregar un recurso de Redis:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

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

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

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/Redis/Redis, crea una nueva instancia de Redis en el equipo local. Se agrega una referencia al recurso de Redis (la variable cache) al ExampleProject.

El método WithReference configura una conexión en el ExampleProject denominado "cache". Para obtener más información, consulte ciclo de vida de los recursos de contenedor.

Propina

Si prefiere conectarse a una instancia de Redis existente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.

Añadir recurso Redis con Redis Insights

Para agregar Redis Insights al recurso de Redis, llame al método WithRedisInsight.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisInsight();

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

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

Redis Insights es una interfaz gráfica gratuita para analizar Redis datos en todos los sistemas operativos y despliegues de Redis, con la ayuda de nuestro asistente de inteligencia artificial, Redis Copilot. .NET .NET Aspire agrega otra imagen de contenedor docker.io/redis/redisinsight al host que ejecuta la aplicación comandante.

Nota

Para configurar el puerto de host para el RedisInsightResource encadene una llamada a la API de WithHostPort y proporcione el número de puerto deseado.

Adición de un recurso de Redis con Redis Commander

Para agregar el Commander al recurso , llame al método :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithRedisCommander();

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

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

Redis Commander es una aplicación web Node.js que se usa para ver, editar y administrar una base de datos Redis. .NET .NET Aspire agrega otra imagen de contenedor docker.io/rediscommander/redis-commander al host que ejecuta la aplicación comandante.

Propina

Para configurar el puerto de host para el RedisCommanderResource encadene una llamada a la API de WithHostPort y proporcione el número de puerto deseado.

Adicionar un recurso Redis con volumen de datos

Para agregar un volumen de datos al recurso de Redis, llame al método WithDataVolume en el recurso Redis:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume(isReadOnly: false);

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

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

El volumen de datos se usa para persistir los datos correspondientes a Redis fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta de acceso /data del contenedor de Redis y, cuando no se proporciona un parámetro name, el nombre se genera de forma aleatoria. 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.

Añadir recurso Redis con montaje de unión de datos

Para agregar una vinculación de datos al recurso de Redis, llame al método WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataBindMount(
                       source: @"C:\Redis\Data",
                       isReadOnly: false);

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

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

Importante

Los enlaces de montaje de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes bind permiten el acceso directo y la modificación de archivos en el sistema host, lo cual es ideal para el desarrollo y las pruebas donde se requieren cambios en tiempo real.

Los montajes de enlace de datos se basan en el sistema de archivos de la máquina host para preservar los datos de Redis durante los reinicios del contenedor. El montaje de enlace de datos se monta en el C:\Redis\Data en Windows (o /Redis/Data en Unix) en la ruta de acceso en el equipo host en el contenedor Redis. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: Enlazar montajes.

Agregar recurso Redis con persistencia

Para agregar persistencia al recurso de Redis, llame al método WithPersistence con el volumen de datos o el punto de montaje de datos:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

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

El código anterior agrega persistencia al recurso Redis mediante la toma de instantáneas de los datos de Redis en un intervalo y umbral especificados. El interval es el tiempo entre las exportaciones de instantáneas y el keysChangedThreshold es el número de operaciones de cambio clave necesarias para desencadenar una instantánea. Para obtener más información sobre la persistencia, consulte la documentación de Redis: Persistencia.

La integración de Garnet modela un recurso de Garnet como el tipo GarnetResource. Para acceder a este tipo y las API que le permiten agregarlo al paquete NuGet 📦Aspire.Hosting.Garnet en el proyecto de host de la aplicación .

dotnet add package Aspire.Hosting.Garnet

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

Adición de un recurso de Garnet

En el proyecto host de la aplicación, llame a AddGarnet en la instancia de builder para agregar un recurso de Garnet:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache");

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

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

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de ghcr.io/microsoft/garnet, crea una nueva instancia de Garnet en el equipo local. Se añade una referencia a tu recurso Garnet (la variable cache) al ExampleProject.

El método WithReference configura una conexión en el ExampleProject denominado "cache". Para obtener más información, consulte ciclo de vida de los recursos de contenedor.

Propina

Si prefiere conectarse a una instancia de Garnet existente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.

Adición de un recurso de Garnet con volumen de datos

Para agregar un volumen de datos al recurso garnet, llame al método AddGarnet en el recurso garnet:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume(isReadOnly: false);

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

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

El volumen de datos se usa para conservar los datos de Garnet fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta de acceso /data en el contenedor de Garnet y, cuando no se proporciona un parámetro name, el nombre se genera de forma aleatoria. 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.

Agregar recurso de Garnet con montaje de datos enlazados

Para agregar un montaje de enlace de datos al recurso Garnet, llame al método WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataBindMount(
                       source: @"C:\Garnet\Data",
                       isReadOnly: false);

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

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

Importante

Los montajes de enlace de datos de tienen una funcionalidad limitada en comparación con los volúmenes de, que ofrecen un mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes directos permiten el acceso directo y la modificación de archivos en el sistema host, lo cual es ideal para el desarrollo y las pruebas donde 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 Garnet entre reinicios del contenedor. El punto de montaje del enlace de datos se monta en C:\Garnet\Data en Windows (o /Garnet/Data en Unix) en la ruta de acceso de la máquina host en el contenedor de Garnet. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: montajes de enlace.

Adición de un recurso de Garnet con persistencia

Para agregar persistencia al recurso Garnet, llame al método WithPersistence con el volumen de datos o el punto de montaje de datos asociado.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddGarnet("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

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

El código anterior agrega persistencia al recurso de Redis tomando instantáneas de los datos de garnet en un intervalo y umbral especificados. El interval es el tiempo entre las exportaciones de instantáneas y el keysChangedThreshold es el número de operaciones de cambio clave necesarias para desencadenar una instantánea. Para obtener más información sobre la persistencia, consulte Redis doc.: Persistencia.

La integración de Valkey modela un recurso Valkey como el tipo ValkeyResource. Para acceder a este tipo y API que le permiten agregarlo al paquete NuGet 📦Aspire.Hosting.Valkey en el proyecto host de la aplicación .

dotnet add package Aspire.Hosting.Valkey

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

Adición de un recurso Valkey

En el proyecto host de la aplicación, llame a AddValkey en la instancia de builder para agregar un recurso Valkey:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache");

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

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

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/valkey/valkey, crea una nueva instancia de Valkey en el equipo local. Se agrega una referencia al recurso Valkey (la variable cache) al ExampleProject.

El método WithReference configura una conexión en el ExampleProject denominado "cache". Para obtener más información, consulte ciclo de vida de los recursos de contenedor.

Propina

Si prefiere conectarse a una instancia de Valkey existente, llame a AddConnectionString en su lugar. Para obtener más información, consulte Recursos existentes de referencia.

Adición de un recurso Valkey con volumen de datos

Para agregar un volumen de datos al recurso Valkey, llame al método AddValkey en el recurso Valkey:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume(isReadOnly: false);

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

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

El volumen de datos se usa para conservar los datos de Valkey fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta de acceso /data del contenedor Valkey y, cuando no se proporciona un parámetro name, el nombre se genera de forma aleatoria. 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.

Añadir el recurso Valkey con montaje de datos vinculado

Para agregar un montaje de enlace de datos al recurso Valkey, llame al método WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataBindMount(
                       source: @"C:\Valkey\Data",
                       isReadOnly: false);

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

// 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, haciendo que sean más adecuados para entornos de producción. Sin embargo, los montajes de enlace permiten el acceso directo a los archivos y su modificación en el sistema anfitrión, lo cual es ideal para el desarrollo y pruebas donde se necesitan cambios en tiempo real.

Los montajes de datos vinculados dependen del sistema de archivos de la máquina host para conservar los datos de Valkey durante los reinicios del contenedor. El punto de montaje de datos se encuentra en el C:\Valkey\Data en Windows (o /Valkey/Data en Unix) en la máquina host dentro del contenedor Valkey. Para obtener más información sobre los montajes de datos, consulte los documentos Docker: Montajes de enlace.

Adición de un recurso Valkey con persistencia

Para agregar persistencia al recurso Valkey, llame al método WithPersistence con el volumen de datos o el montaje de enlace de datos:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

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

El código anterior agrega persistencia al recurso de Redis tomando instantáneas de los datos de Valkey en un intervalo y umbral especificados. El interval es el tiempo entre las exportaciones de instantáneas y el keysChangedThreshold es el número de operaciones de cambio clave necesarias para desencadenar una instantánea. Para obtener más información sobre la persistencia, consulte Redis documentos: Persistencia.

Comprobaciones de estado de la integración de hospedaje

La integración de hospedaje Redis agrega automáticamente una comprobación de estado para el tipo de recurso correspondiente. La comprobación de estado comprueba que el server se está ejecutando y que se puede establecer una conexión a ella.

La integración de hospedaje se basa en el 📦 AspNetCore.HealthChecks.Redis paquete NuGet.

integración de Client

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

dotnet add package Aspire.StackExchange.Redis

Agregar Redisclient

En el archivo Program.cs del proyecto que consume client, 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 Redis en el proyecto host de la aplicación. Para obtener más información, consulte Agregar Redis recurso.

Propina

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

Propina

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

A continuación, puede usar la inyección de dependencias para recuperar la instancia de IConnection. 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 Redisclient 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 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 .NET Aspire Stack Exchange Redisclient proporciona varias opciones para configurar la conexión Redis según los requisitos y convenciones de su 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");

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 AddGarnet:

builder.AddGarnet("cache");

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 AddValkey:

builder.AddValkey("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 de Stack Exchange Redis.

Uso de proveedores de configuración

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

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Para obtener el esquema JSON completo de integración de Redisclient, consulte Aspire. StackExchange.Redis/ConfigurationSchema.json.

Use 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 DisableTracing:

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

comprobaciones de estado 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 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 admiten 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 AspireRedis Stack Exchange usa las siguientes categorías de registros:

  • Aspire.StackExchange.Redis

Rastreo

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

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

Azure Redis integración de hospedaje

Para implementar los recursos de Redis en Azure, instale el paquete NuGet 📦Aspire.Hosting.Azure.Redis:

dotnet add package Aspire.Hosting.Azure.Redis

Agregar Azure Cache for Redisserver recurso

Después de instalar el paquete de hospedaje .NET AspireAzureRedis, llame al método de extensión AddAzureRedis en el proyecto de anfitrión de la aplicación.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

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

La llamada anterior a AddAzureRedis configura el recurso de Redisserver para que se despliegue como un Azure Cache for Redis.

Importante

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

Agregar Azure Cache for Redisclient

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

dotnet add package Microsoft.Azure.StackExchangeRedis

La conexión de Redis se puede utilizar mediante la integración de client 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.

Consulte también

*: Redis es una marca registrada de Redis Ltd. Cualquier derecho sobre ella está reservado a Redis Ltd. Cualquier 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