Compartir a través de

Integración de almacenamiento en caché de salida®

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

Aprenda cómo utilizar la integración de caché de salida .NET AspireRedis. La Aspire.StackExchange.Redis.OutputCaching integración de cliente se utiliza para registrar un proveedor de ASP.NET Core caché de salida respaldado por un Redis servidor con la docker.io/library/redis imagen de contenedor.

Aprenda cómo utilizar la integración de caché de salida .NET AspireRedis. La Aspire.StackExchange.Redis.OutputCaching integración de cliente se usa para registrar un ASP.NET Core proveedor de caché de salida respaldado por un servidor Garnet con la imagen de ghcr.io/microsoft/garnet contenedor.

Aprenda cómo utilizar la integración de caché de salida .NET AspireRedis. La Aspire.StackExchange.Redis.OutputCaching integración de cliente se utiliza para registrar un proveedor de ASP.NET Core almacenamiento en caché de salida, respaldado por un servidor Valkey, con la imagen del docker.io/valkey/valkey contenedor.

Integración de hospedaje

La integración de hospedaje Redis modela un recurso Redis como el tipo RedisResource. Para acceder a este tipo y a las APIs para expresarlos como recursos en el proyecto host de la aplicación, agregue el paquete NuGet 📦Aspire.Hosting.Redis

dotnet add package Aspire.Hosting.Redis

Para obtener más información, consulte dotnet add package (Agregar paquete ) o Manage package dependencies in applications (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 más información, consulte Ciclo de vida de los recursos del contenedor.

Propina

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

Incorporación de un recurso de Redis con Redis Insights

Para agregar Redis perspectivas al Redis recurso, llame al WithRedisInsight método:

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 en todas las implementaciones, 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 de la app que ejecuta la app de 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.

Añade el recurso Redis con Redis Commander

Para agregar el Redis Comandante al Redis recurso, llame al WithRedisCommander 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 de la app que ejecuta la app de 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.

Agregar el 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 utiliza para conservar los datos de Redis fuera del ciclo de vida del contenedor. El volumen de datos se monta en la ruta /data del contenedor Redis y, si no se especifica un parámetro name, el nombre se genera aleatoriamente. Para más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren sobre los montajes de enlace, consulte Docker la documentación: Volúmenes.

Adición del recurso Redis con montaje con enlace de datos

Para agregar una vinculación de datos al recurso 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 montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, por lo que son más apropiados para entornos de producción. Sin embargo, los montajes bind permiten el acceso directo y la modificación de archivos en el sistema host, siendo ideal para el desarrollo y pruebas donde se necesiten cambios en tiempo real.

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

Añadir recurso Redis con persistencia

Para añadir persistencia al recurso Redis, llame al método WithPersistence con un volumen de datos o un montaje de enlace 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 Redis docs: Persistencia.

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

dotnet add package Aspire.Hosting.Garnet

Para obtener más información, consulte dotnet add package (Agregar paquete ) o Manage package dependencies in applications (Administrar dependencias de paquetes en .NET aplicaciones).

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 agrega una referencia al recurso Garnet (la variable cache) al ExampleProject.

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

Propina

Si prefiere conectarse a una instancia de Garnet existente, llame a AddConnectionString en su lugar. Para obtener más información, consulte 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 el camino /data en el contenedor de Garnet y, cuando no se proporciona un parámetro name, el nombre se genera aleatoriamente. Para más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren sobre los montajes de enlace, consulte Docker la documentación: Volúmenes.

Adición de un recurso de Garnet con montaje de enlace de datos

Para agregar un montaje de vinculación 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 tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, por lo que son más apropiados para entornos de producción. Sin embargo, los montajes bind permiten el acceso directo y la modificación de archivos en el sistema host, siendo ideal para el desarrollo y pruebas donde se necesiten 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 montaje de enlace de datos se monta en la ruta de acceso C:\Garnet\Data en Windows (o /Garnet/Data en Unix) en la máquina host dentro del contenedor 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 utilizando el volumen de datos o el punto de montaje del enlace de datos.

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 docs: Persistencia.

La integración de hosting de Valkey modela un recurso Valkey como el tipo ValkeyResource. Para acceder a este tipo y a las API que le permiten agregarlo al paquete NuGet .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 (Agregar paquete ) o Manage package dependencies in applications (Administrar dependencias de paquetes en .NET aplicaciones).

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 más información, consulte Ciclo de vida de los recursos del contenedor.

Propina

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

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 más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren sobre los montajes de enlace, consulte Docker la documentación: Volúmenes.

Adición del recurso Valkey con enlace de montaje de datos

Para agregar un montaje de vinculación de datos al recurso Valkey, utilice el 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 mejor rendimiento, portabilidad y seguridad, por lo que son más apropiados para entornos de producción. Sin embargo, los montajes bind permiten el acceso directo y la modificación de archivos en el sistema host, siendo ideal para el desarrollo y pruebas donde se necesiten cambios en tiempo real.

Los montajes de unión de datos dependen del sistema de archivos de la máquina host para conservar los datos de Valkey durante los reinicios del contenedor. El montaje de datos vinculado se monta en la ruta C:\Valkey\Data en Windows (o /Valkey/Data en Unix) en el equipo host dentro del contenedor Valkey. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: 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 docs: Persistencia.

Comprobaciones de salud de la integración del hosting

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

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

integración con Client

Para empezar a trabajar con la integración del cliente de caché de salida de .NET Aspire Stack ExchangeRedis, instale el paquete NuGet 📦Aspire.StackExchange.Redis.OutputCaching en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que utiliza el cliente de caché de salida. La Redis integración del cliente de almacenamiento en caché de salida registra los servicios necesarios para habilitar CacheOutput las llamadas de método y el uso del atributo [OutputCache] para confiar en Redis como su mecanismo de almacenamiento en caché.

dotnet add package Aspire.StackExchange.Redis.OutputCaching

Agregar almacenamiento en caché de salida

En el archivo Program.cs del proyecto que consume servicios de cliente, llame al método de extensión denominado AddRedisOutputCache sobre cualquier objeto IHostApplicationBuilder para registrar los servicios necesarios para el almacenamiento en caché de salida.

builder.AddRedisOutputCache(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 Adición de un 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 Incorporación de un recurso Valkey.

Agregue el middleware a la canalización de procesamiento de solicitudes llamando a UseOutputCache(IApplicationBuilder):

var app = builder.Build();

app.UseOutputCache();

Para las aplicaciones de API mínimas, configure un punto de conexión para realizar el almacenamiento en caché mediante una llamada a CacheOutputo mediante la aplicación de OutputCacheAttribute, como se muestra en los ejemplos siguientes:

app.MapGet("/cached", () => "Hello world!")
   .CacheOutput();

app.MapGet(
    "/attribute",
    [OutputCache] () => "Hello world!");

En el caso de las aplicaciones con controladores, aplique el atributo [OutputCache] al método de acción. En el caso de las aplicaciones de Razor Pages, aplique el atributo a la clase de página de Razor.

Configuración

La integración del almacenamiento en caché de salida de .NET Aspire Stack Exchange Redis 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 AddRedisOutputCache:

builder.AddRedisOutputCache(connectionName: "cache");

A continuación, la cadena de conexión se obtendrá desde la sección de configuración de 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 ExchangeRedis.

Uso de proveedores de configuración

La integración del almacenamiento en caché de salida de .NET Aspire Stack Exchange Redis admite Microsoft.Extensions.Configuration. Carga el StackExchangeRedisSettings desde la 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 consultar el esquema completo de la integración del cliente de almacenamiento en caché de salida, vea Redis.

Utiliza delegados en línea

También puede pasar el delegado de Action<StackExchangeRedisSettings> configurationSettings para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar las comprobaciones de estado desde el código:

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.DisableHealthChecks  = true);

También puede configurar ConfigurationOptions mediante el Action<ConfigurationOptions> configureOptions parámetro delegado del AddRedisOutputCache método . Por ejemplo, para establecer el tiempo de espera de conexión:

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.ConnectTimeout = 3_000);

Client comprobaciones de salud de integración

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

La integración del almacenamiento en caché de salida 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 recibir 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 del almacenamiento en caché de salida de .NET Aspire Stack Exchange Redis usa las siguientes categorías de registro:

  • Aspire.StackExchange.Redis
  • Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

Seguimiento

La integración de caché de salida .NET Aspire de Redis Stack Exchange generará las siguientes actividades de rastreo mediante OpenTelemetry:

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Métricas

La integración del almacenamiento en caché de salida de .NET Aspire Stack Exchange Redis actualmente no admite métricas de forma predeterminada debido a limitaciones con la biblioteca de StackExchange.Redis.

Consulte también

*: Redis es una marca registrada de Redis Ltd. Todos los derechos pertenecen 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 a la parte superior?