Интеграция кэширования выходных данных .NET AspireRedis^* ®

Статья
03/08/2025

включает: интеграция хостинга и интеграция Client

Узнайте, как использовать интеграцию кэширования выходных данных .NET AspireRedis. Интеграция клиента Aspire.StackExchange.Redis.OutputCaching используется для регистрации поставщика выходного кэширования ASP.NET Core, поддерживаемого сервером Redis с образом контейнера docker.io/library/redis.

Узнайте, как использовать интеграцию кэширования выходных данных .NET AspireRedis. Интеграция клиента используется для регистрации поставщика кеширования вывода , поддерживаемого сервером Garnet с образом контейнера .

Узнайте, как использовать интеграцию кэширования выходных данных .NET AspireRedis. Интеграция клиента Aspire.StackExchange.Redis.OutputCaching используется для регистрации поставщика кэширования ASP.NET Core выходных данных, поддерживаемого сервером Valkey , с образом контейнера docker.io/valkey/valkey.

Интеграция хостинга

Интеграция Redis моделирует ресурс Redis, используя тип RedisResource. Чтобы получить доступ к этому типу и API для их выражения в виде ресурсов в проекте хоста приложения , добавьте пакет NuGet 📦Aspire.Hosting.Redis.

.NET CLI
СсылкаНаПакет

dotnet add package Aspire.Hosting.Redis

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

Дополнительные сведения см. в статьях dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавить ресурс Redis

В проекте хоста приложения, вызовите AddRedis на экземпляре builder, чтобы добавить ресурс Redis.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Когда .NET.NET Aspire добавляет образ контейнера в узел приложения, как показано в предыдущем примере с изображением docker.io/Redis/Redis, он создает новый экземпляр Redis на локальном компьютере. Ссылка на ресурс Redis (переменная cache) добавляется в ExampleProject.

Метод WithReference настраивает подключение в ExampleProject с именем "cache". Дополнительные сведения см. в жизненном цикле ресурса контейнера.

Совет

Если вы хотите подключиться к существующему экземпляру Redis, вызовите AddConnectionString вместо этого. Дополнительные сведения см. в статье Справочник по существующим ресурсам.

Добавление ресурса Redis с помощью Redis Insights

Чтобы добавить Redis Insights в ресурс Redis, вызовите метод 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 — это бесплатный интерфейс с графическим пользовательским интерфейсом для анализа данных Redis на всех операционных системах и развертываниях Redis с помощью помощника на базе искусственного интеллекта Redis Copilot. .NET .NET Aspire добавляет еще один образ контейнера docker.io/redis/redisinsight к хосту приложения, который запускает командирское приложение.

Заметка

Чтобы настроить порт узла для цепочки RedisInsightResource, выполните вызов к API WithHostPort и укажите нужный номер порта.

Добавить ресурс Redis с помощью Redis Commander

Чтобы добавить Redis Commander в ресурс Redis, вызовите метод WithRedisCommander:

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 — это веб-приложение Node.js, используемое для просмотра, редактирования и управления базой данных Redis. .NET .NET Aspire добавляет еще один образ контейнера docker.io/rediscommander/redis-commander в хост приложения, который выполняет приложение-командир.

Совет

Чтобы настроить порт узла для цепочки RedisCommanderResource, выполните вызов к API WithHostPort и укажите нужный номер порта.

Добавьте ресурс Redis с объемом данных

Чтобы добавить том данных в ресурс Redis, вызовите метод WithDataVolume в ресурсе 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...

Объём данных используется для сохранения Redis данных вне жизненного цикла контейнера. Том данных подключается по пути /data в контейнере Redis и когда параметр name не указан, имя создается случайным образом. Дополнительные сведения о томах данных и сведения о том, почему они предпочтительнее привязки, см. в Docker документации по томам.

Добавление ресурса Redis с подключением привязки данных

Чтобы добавить крепление привязки данных к ресурсу Redis, вызовите метод 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...

Важный

Крепления привязки данных ограничены по функциональности по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для производственных сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, что идеально подходит для разработки и тестирования, где требуются изменения в режиме реального времени.

Монтирование привязки данных зависит от файловой системы хост-компьютера для обеспечения сохранности данных Redis при перезапусках контейнера. Монтирование привязки данных осуществляется по пути C:\Redis\Data на Windows (или /Redis/Data на Unix) на хост-компьютере в контейнере Redis. Дополнительные сведения о монтировании привязок данных см. в документации: Docker монтирование привязок.

Добавление ресурса Redis с сохраняемостью

Чтобы добавить сохраняемость к ресурсу Redis, вызовите метод WithPersistence с подключением тома данных или привязки данных:

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...

Приведенный выше код добавляет сохраняемость к ресурсу Redis путем создания моментальных снимков данных Redis с заданным интервалом и пороговым значением. interval — это время между экспортами моментальных снимков, keysChangedThreshold — количество операций изменения ключей, необходимых для запуска моментального снимка. Дополнительные сведения о персистентности см. в документации Redis: Персистентность.

Интеграция с Гарнетом моделирует ресурс Garnet в качестве типа GarnetResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в пакет NuGet Hosting.Garnet 📦Aspire в проекте хоста приложения .

.NET CLI
СсылкаНаПакет

dotnet add package Aspire.Hosting.Garnet

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

Для получения дополнительной информации см. dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавление ресурса Garnet

В проекте хоста приложения вызовите AddGarnet на экземпляре builder, чтобы добавить ресурс Garnet.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Когда .NET.NET Aspire добавляет образ контейнера в хост приложения, как показано в предыдущем примере с изображением ghcr.io/microsoft/garnet, он создает новый экземпляр Garnet на локальном компьютере. Ссылка на ресурс Garnet (переменная cache) добавляется в ExampleProject.

Совет

Если вы хотите подключиться к существующему экземпляру Garnet, вызовите AddConnectionString вместо этого. Дополнительные сведения см. в статье Справочник по существующим ресурсам.

Добавить ресурс Garnet с объемом данных

Чтобы добавить том данных в ресурс Garnet, вызовите метод AddGarnet в ресурсе 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...

Том данных используется для сохранения данных Garnet вне жизненного цикла контейнера. Том данных монтируется в контейнер Garnet по пути /data, и если параметр name не указан, имя генерируется случайным образом. Дополнительные сведения о томах данных и о причинах, по которым они предпочтительнее привязок, можно ознакомиться в Docker документации по томам.

Добавление ресурса Garnet с подключением привязки данных

Чтобы добавить точку привязки данных к ресурсу Garnet, вызовите метод 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...

Важный

Подключения привязки данных имеют ограниченные функциональные возможности по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для рабочих сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, что идеально подходит для разработки и тестирования, где требуются изменения в режиме реального времени.

Привязки данных (data bind mounts) опираются на файловую систему хост-компьютера для сохранения данных Garnet при перезапусках контейнера. Точка монтирования привязки данных находится по пути C:\Garnet\Data на Windows (или /Garnet/Data на Unix) на хост-компьютере в контейнере Garnet. Дополнительные сведения о монтировании привязок данных см. в Docker документации: Монтирование привязок.

Добавить ресурс Garnet с сохранением данных

Чтобы добавить сохраняемость к ресурсу Garnet, вызовите метод WithPersistence с подключением тома данных или привязки данных:

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...

Код, представленный выше, добавляет персистентность ресурсу Redis путем создания моментальных снимков данных Garnet с заданным интервалом и пороговым значением. interval — это время между экспортами моментальных снимков, keysChangedThreshold — количество операций изменения ключей, необходимых для запуска моментального снимка. Дополнительные сведения о персистентности см. в документации Redis: Персистентность.

Интеграция хостинга Valkey представляет ресурс Valkey в виде типа ValkeyResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в пакет NuGet 📦Aspire.Hosting.Valkey в проекте хоста приложения .

.NET CLI
СсылкаНаПакет

dotnet add package Aspire.Hosting.Valkey

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

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях.NET.

Добавление ресурса Valkey

В проекте размещения приложения вызовите AddValkey на экземпляре builder, чтобы добавить ресурс Valkey.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Когда .NET.NET Aspire добавляет образ контейнера в хост приложения, как показано в предыдущем примере с образом docker.io/valkey/valkey, он создает новый экземпляр Valkey на локальном компьютере. Ссылка на ресурс Valkey (переменная cache) добавляется в ExampleProject.

Совет

Если вы хотите подключиться к существующему экземпляру Valkey, вызовите AddConnectionString вместо этого. Дополнительные сведения см. в статье Справочник по существующим ресурсам.

Добавьте ресурс Valkey с объемом данных

Чтобы добавить том данных в ресурс Valkey, вызовите метод AddValkey в ресурсе 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...

Том данных используется для сохранения данных Valkey за пределами жизненного цикла контейнера. Том данных подключается по пути /data в контейнере Valkey, а если параметр name не указан, имя создается случайным образом. Дополнительные сведения о томах данных и сведения о том, почему они предпочтительнее привязки, см. в Docker документации по томам.

Добавление ресурса Valkey с подключением привязки данных

Чтобы добавить подключение привязки данных к ресурсу Valkey, вызовите метод 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...

Важный

Монтажи привязки данных имеют ограниченную функциональность по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для производственных сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, что идеально подходит для разработки и тестирования, где требуются изменения в режиме реального времени.

Монтажи для привязки данных зависят от файловой системы хост-компьютера, чтобы сохранить данные Valkey между перезапусками контейнера. Точка привязки данных монтируется на C:\Valkey\Data в Windows (или на /Valkey/Data в Unix) по пути на компьютере-хосте в контейнере Valkey. Дополнительные сведения о подключении привязок данных см. в документации по Docker: подключение привязок.

Добавьте ресурс Valkey с сохранением данных

Чтобы добавить устойчивость ресурсу Valkey, вызовите метод WithPersistence, указав либо том данных, либо привязку данных.

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...

Приведенный выше код добавляет постоянство к ресурсу Redis посредством создания снимков данных Valkey с определённым интервалом и порогом. interval — это интервал времени между экспортами моментальных снимков, а keysChangedThreshold — количество операций изменения ключей, необходимых для запуска моментального снимка. Дополнительные сведения о персистентности см. в документации Redis: Персистентность.

Проверка работоспособности интеграции в рамках хостинга

Интеграция хостинга Redis автоматически добавляет проверку состояния для соответствующего типа ресурса. Проверка работоспособности проверяет, запущен ли сервер и что подключение можно установить к нему.

Интеграция размещения зависит от пакета NuGet AspNetCore.HealthChecks.

интеграция Client

Чтобы приступить к работе с интеграцией клиента .NET Aspire Stack Exchange Redis для кэширования выходных данных, установите пакет NuGet 📦Aspire.StackExchange.Redis.OutputCaching в проект клиента, то есть в проекте приложения, которое использует клиент кэширования выходных данных. Клиентская интеграция кеширования Redis регистрирует службы, необходимые для активации вызовов методов CacheOutput и использования атрибута [OutputCache], полагаясь на Redis в качестве механизма кеширования.

.NET CLI
СсылкаНаПакет

dotnet add package Aspire.StackExchange.Redis.OutputCaching

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

Добавление кэширования выходных данных

В файле Program.cs проекта, используюющего клиент, вызовите метод расширения AddRedisOutputCache в любом IHostApplicationBuilder, чтобы зарегистрировать необходимые службы для кэширования выходных данных.

builder.AddRedisOutputCache(connectionName: "cache");

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Redis в проект узла приложения. Дополнительные сведения см. в разделе Добавление Redis ресурса.

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Garnet в проект узла приложения. Дополнительные сведения см. в разделе Добавление ресурса Garnet.

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Valkey в проект узла приложения. Дополнительную информацию см. в разделе Добавление ресурса Valkey.

Добавьте ПО промежуточного слоя в конвейер обработки запросов, вызвав UseOutputCache(IApplicationBuilder):

var app = builder.Build();

app.UseOutputCache();

Для минимальных приложений APIнастройте конечную точку для кэширования путем вызова CacheOutputили применения OutputCacheAttribute, как показано в следующих примерах:

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

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

Для приложений с контроллерами примените атрибут [OutputCache] к методу действия. Для приложений Razor Pages примените атрибут к классу страницы Razor.

Конфигурация

Интеграция кэширования выходных данных .NET Aspire Stack Exchange Redis предоставляет несколько вариантов настройки подключения Redis на основе требований и соглашений проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове AddRedisOutputCache:

builder.AddRedisOutputCache(connectionName: "cache");

Затем строка подключения будет получена из раздела конфигурации ConnectionStrings:

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

Дополнительные сведения о том, как отформатировать эту строку подключения, см. в документации по конфигурации RedisStack Exchange.

Использование поставщиков конфигураций

Интеграция .NET Aspire Stack Exchange Redis для кэширования вывода поддерживает Microsoft.Extensions.Configuration. Он загружает StackExchangeRedisSettings из конфигурации с помощью ключа Aspire:StackExchange:Redis. Пример appsettings.json, который настраивает некоторые параметры:

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

Полную схему интеграции клиентского кэширования см. в Aspire.StackExchange.Redis.OutputCaching/ConfigurationSchema.json.

Использование встроенных делегатов

Можно также передать делегат Action<StackExchangeRedisSettings> configurationSettings для настройки некоторых или всех встроенных параметров, например для отключения проверок работоспособности из кода:

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

Вы также можете настроить ConfigurationOptions с помощью параметра делегата Action<ConfigurationOptions> configureOptions метода AddRedisOutputCache. Например, чтобы задать время ожидания подключения:

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

Client проверка состояния интеграции

По умолчанию .NET.NET Aspireинтеграции клиента имеют включенные проверки работоспособности для всех служб. Аналогичным образом, многие .NET.NET Aspireхостинговые интеграции также включают конечные точки проверки работоспособности. Дополнительные сведения см. в следующем разделе:

.NET проверки работоспособности приложения на C#
Проверка здоровья в ASP.NET Core

Интеграция .NET Aspire Stack Exchange Redis с кэшированием выходных данных обрабатывает следующее:

Добавляет проверку работоспособности, когда StackExchangeRedisSettings.DisableHealthChecks является false, которая пытается подключиться к экземпляру контейнера.
Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки работоспособности должны быть успешными, чтобы приложение считалось готовым принять трафик.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации журналирования, трассировки и метрик, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция кэширования выходных данных .NET Aspire Stack Exchange Redis использует следующие категории журналов:

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

Отслеживание

.NET Aspire Интеграция кэширования выводных данных Stack Exchange Redis будет выдавать следующие действия трассировки с помощью OpenTelemetry:

OpenTelemetry.Instrumentation.StackExchangeRedis

Метрика

Интеграция кэширования выходных данных .NET Aspire Stack Exchange Redis в настоящее время не поддерживает метрики по умолчанию из-за ограничений библиотеки StackExchange.Redis.

См. также

*: Redis является зарегистрированным товарным знаком Redis Ltd. Любые права, указанные в них, зарезервированы для Redis Ltd. Любое использование корпорации Майкрософт предназначено только для ссылок и не указывает на спонсорство, подтверждение или принадлежность между Redis и Корпорацией Майкрософт. Вернуться к верхней?

Поделиться через

Интеграция кэширования выходных данных .NET AspireRedis^* ®

Интеграция хостинга

Добавить ресурс Redis

Добавление ресурса Redis с помощью Redis Insights

Добавить ресурс Redis с помощью Redis Commander

Добавьте ресурс Redis с объемом данных

Добавление ресурса Redis с подключением привязки данных

Добавление ресурса Redis с сохраняемостью

Добавление ресурса Garnet

Добавить ресурс Garnet с объемом данных

Добавление ресурса Garnet с подключением привязки данных

Добавить ресурс Garnet с сохранением данных

Добавление ресурса Valkey

Добавьте ресурс Valkey с объемом данных

Добавление ресурса Valkey с подключением привязки данных

Добавьте ресурс Valkey с сохранением данных

Проверка работоспособности интеграции в рамках хостинга

интеграция Client

Добавление кэширования выходных данных

Конфигурация

Используйте строку подключения

Использование поставщиков конфигураций

Использование встроенных делегатов

Client проверка состояния интеграции

Наблюдаемость и телеметрия

Лесозаготовка

Отслеживание

Метрика

См. также

Дополнительные ресурсы

Поделиться через

Интеграция кэширования выходных данных .NET AspireRedis* ®

Интеграция хостинга

Добавить ресурс Redis

Добавление ресурса Redis с помощью Redis Insights

Добавить ресурс Redis с помощью Redis Commander

Добавьте ресурс Redis с объемом данных

Добавление ресурса Redis с подключением привязки данных

Добавление ресурса Redis с сохраняемостью

Добавление ресурса Garnet

Добавить ресурс Garnet с объемом данных

Добавление ресурса Garnet с подключением привязки данных

Добавить ресурс Garnet с сохранением данных

Добавление ресурса Valkey

Добавьте ресурс Valkey с объемом данных

Добавление ресурса Valkey с подключением привязки данных

Добавьте ресурс Valkey с сохранением данных

Проверка работоспособности интеграции в рамках хостинга

интеграция Client

Добавление кэширования выходных данных

Конфигурация

Используйте строку подключения

Использование поставщиков конфигураций

Использование встроенных делегатов

Client проверка состояния интеграции

Наблюдаемость и телеметрия

Лесозаготовка

Отслеживание

Метрика

См. также

Дополнительные ресурсы

Интеграция кэширования выходных данных .NET AspireRedis^* ®