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

Включает:интеграция размещения и Client интеграция

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

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

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

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

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

.NET CLI

dotnet add package Aspire.Hosting.Redis

СсылкаНаПакет

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

Дополнительные сведения см. в статье dotnet add package or Manage package dependencies in .NET applications.

Добавление ресурса 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

Чтобы добавить 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 or Manage package dependencies in .NET applications.

Добавление ресурса 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.

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

Совет

Если вы хотите подключиться к существующему экземпляру 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 вне жизненного цикла контейнера. Том данных подключается по пути /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...

Важный

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

Привязка данных опирается на файловую систему хост-компьютера для сохранения данных 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.Host.Valkey в проекте размещения приложения .

.NET CLI

dotnet add package Aspire.Hosting.Valkey

СсылкаНаПакет

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

Дополнительные сведения см. в статье dotnet add package or Manage package dependencies in .NET applications.

Добавление ресурса 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.

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

Совет

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

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

интеграция Client

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

.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": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Полная схема интеграции клиента RedisJSON см. в Aspire. StackExchange.Redis/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);

Проверки состояния здоровья

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

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

• Добавляет проверку работоспособности StackExchange.Redis, пытается открыть подключение и выбрасывает исключение при сбое.
• Интегрируется с конечной точкой 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.

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

Чтобы развернуть ресурсы Redis в Azure, установите 📦Aspire. Хостинг.Azure. пакет NuGetRedis:

.NET CLI

dotnet add package Aspire.Hosting.Azure.Redis

СсылкаНаПакет

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

Добавьте ресурс сервера AzureAzure Cache for Redis

После того как вы установите пакет размещения .NET AspireAzureRedis, вызовите метод расширения AddAzureRedis в вашем проекте узла приложения.

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

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

Предыдущий вызов AddAzureRedis настраивает ресурс сервера Redis для его развертывания в качестве Azure Cache for Redis.

Важный

По умолчанию AddAzureRedis настраивает аутентификацию Microsoft Entra ID. Это требует изменений в приложениях, которые должны подключаться к этим ресурсам, например интеграции клиентов.

Добавление выходного клиента AzureAzure Cache for Redis

По умолчанию при вызове AddAzureRedis в интеграции размещения Redis она настраивает 📦 Майкрософт.Azure. StackExchangeRedis пакет NuGet для включения проверки подлинности:

.NET CLI

dotnet add package Microsoft.Azure.StackExchangeRedis

СсылкаНаПакет

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

Подключение Redis можно использовать с помощью интеграции клиента и Microsoft.Azure.StackExchangeRedis. Рассмотрим следующий код конфигурации:

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.AddRedisOutputCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

Дополнительные сведения см. в Майкрософт.Azure. Репозиторий StackExchangeRedis.

См. также

• Stack Exchange Redis документация
• интеграции .NET.NET Aspire
• .NET Aspire GitHub repo

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