.NET Aspire Redis * интеграция распределенного кэширования ®
Включает:
интеграция хостинга и Client интеграция
Узнайте, как использовать интеграцию .NET AspireRedis распределенного кэширования. Библиотека Aspire.StackExchange.Redis.DistributedCaching используется для регистрации поставщика IDistributedCache, поддерживаемого Redisserver с помощью образа контейнера docker.io/library/redis.
Узнайте, как использовать интеграцию .NET AspireRedis распределенного кэширования. Библиотека Aspire.StackExchange.Redis.DistributedCaching используется для регистрации поставщика IDistributedCache, на основе Garnetserver с образом контейнера ghcr.io/microsoft/garnet.
Узнайте, как использовать интеграцию .NET AspireRedis распределенного кэширования. Библиотека Aspire.StackExchange.Redis.DistributedCaching используется для регистрации поставщика IDistributedCache, поддерживаемого Valkeyserver, с образом контейнера docker.io/valkey/valkey.
Интеграция хостинга
Интеграция Redis моделирует ресурс Redis как тип RedisResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в пакет NuGet 📦Aspire.Hosting.Redis вашего проекта хоста приложения .
dotnet add package Aspire.Hosting.Redis
Для получения дополнительных сведений см. 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
Чтобы добавить 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 моделирует ресурс Garnet как тип GarnetResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в 📦Aspire. Пакет NuGet host.Garnet в проекте приложения.
dotnet add package Aspire.Hosting.Garnet
Дополнительные сведения см. в статье 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.
Метод 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 в контейнере Garnet, и если параметр 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 путем создания моментальных снимков данных Гарнета с заданным интервалом и пороговым значением. Время между экспортами моментальных снимков обозначается как interval, а keysChangedThreshold — это количество операций изменения ключей, необходимых для запуска моментального снимка. Дополнительные сведения об устойчивости см. в Redis документации: Устойчивость.
Интеграция хостинга Valkey моделирует ресурс Valkey как тип ValkeyResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в
dotnet add package Aspire.Hosting.Valkey
Дополнительные сведения см. в 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.
Метод 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 автоматически добавляет проверку работоспособности для соответствующего типа ресурса. Проверка работоспособности проверяет, запущен ли server, а также можно ли установить подключение к нему.
Интеграция размещения зависит от пакета NuGet 📦 AspNetCore.HealthChecks.Redis.
интеграция Client
Чтобы начать работу с интеграцией .NET AspireRedis распределенного кэширования, установите 📦Aspire.StackExchange.Redis.РаспределенногоКэширования пакет NuGet в проект, использующий client, то есть в проект для приложения, использующего Redis распределенное кэширование client.
dotnet add package Aspire.StackExchange.Redis.DistributedCaching
Добавьте Redisclient
В файле Program.cs проекта client-consuming вызовите расширение AddRedisDistributedCache, чтобы зарегистрировать требуемые службы для распределенного кэширования и добавить IDistributedCache для использования через контейнер внедрения зависимостей.
builder.AddRedisDistributedCache(connectionName: "cache");
Совет
Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Redis в проект узла приложения. Дополнительные сведения см. в разделе «Добавление Redis ресурса».
Подсказка
Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Garnet в проект узла приложения. Дополнительные сведения см. в разделе Добавление ресурса Garnet.
Совет / Чаевые
Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Valkey в проект узла приложения. Дополнительные сведения см. в разделе Добавление ресурса Valkey.
Затем можно получить объект IDistributedCache благодаря внедрению зависимостей. Например, чтобы получить кэш из службы, выполните следующие действия.
public class ExampleService(IDistributedCache cache)
{
// Use cache...
}
Дополнительные сведения о внедрении зависимостей см. в .NET.
Добавьте ключ Redisclient
Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров IDistributedCache с различными именами подключений. Чтобы зарегистрировать ключевых клиентов Redis, вызовите метод AddKeyedRedisDistributedCache.
builder.AddKeyedRedisDistributedCache(name: "chat");
builder.AddKeyedRedisDistributedCache(name: "product");
Затем можно извлечь экземпляры IDistributedCache с помощью внедрения зависимостей. Например, чтобы получить подключение из примера службы:
public class ExampleService(
[FromKeyedServices("chat")] IDistributedCache chatCache,
[FromKeyedServices("product")] IDistributedCache productCache)
{
// Use caches...
}
Дополнительные сведения о ключевых службах см. в разделе .NET внедрение зависимостей: ключевые службы.
Конфигурация
Интеграция распределенного кэширования .NET AspireRedis предоставляет несколько вариантов настройки подключения Redis на основе требований и соглашений проекта.
Используйте строку подключения
При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове builder.AddRedisDistributedCache:
builder.AddRedisDistributedCache("cache");
Затем строка подключения будет извлечена из раздела конфигурации ConnectionStrings:
{
"ConnectionStrings": {
"cache": "localhost:6379"
}
}
Для получения дополнительной информации о том, как форматировать эту строку подключения, см. документацию по конфигурации Stack Exchange Redis.
Использование поставщиков конфигураций
Интеграция .NET Aspire Stack Exchange Redis поддерживает Microsoft.Extensions.Configuration. Он загружает StackExchangeRedisSettings из конфигурации, используя ключ Aspire:StackExchange:Redis. Пример appsettings.json, который настраивает некоторые параметры:
{
"Aspire": {
"StackExchange": {
"Redis": {
"ConnectionString": "localhost:6379",
"DisableHealthChecks": true,
"DisableTracing": false
}
}
}
}
Полная схема интеграции RedisclientJSON см. в AspireStackExchange.Redis/ConfigurationSchema.json.
Использование встроенных делегатов
Можно также передать делегат Action<StackExchangeRedisSettings> для настройки некоторых или всех встроенных параметров, например для настройки DisableTracing:
builder.AddRedisDistributedCache(
"cache",
settings => settings.DisableTracing = true);
Вы также можете настроить ConfigurationOptions с помощью параметра делегата Action<ConfigurationOptions> configureOptions метода AddRedisDistributedCache. Например, чтобы задать время ожидания подключения:
builder.AddRedisDistributedCache(
"cache",
static settings => settings.ConnectTimeout = 3_000);
Проверки состояния здоровья
По умолчанию .NET.NET Aspire интеграции включают проверки работоспособности для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.
Интеграция с распределенным кэшированием .NET AspireRedis обрабатывает следующее:
- Добавляет проверку работоспособности
StackExchange.Redis, пытается открыть подключение и выбрасывает исключение при сбое. - Интегрируется с HTTP-конечной точкой
/health, которая определяет, что все проверки работоспособности, зарегистрированные, должны быть пройдены, чтобы приложение считалось готовым принять трафик.
Наблюдаемость и телеметрия
.NET
.NET Aspire интеграции автоматически настраивают конфигурации журналирования, трассировки и метрик, которые иногда называют столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации
Лесозаготовка
Интеграция распределенного кэширования .NET AspireRedis использует следующие категории журналов:
Aspire.StackExchange.RedisMicrosoft.Extensions.Caching.StackExchangeRedis
Отслеживание
Интеграция распределенного кэширования .NET AspireRedis будет генерировать следующие действия трассировки, используя OpenTelemetry:
OpenTelemetry.Instrumentation.StackExchangeRedis
Метрика
В настоящее время интеграция распределенного кэширования .NET AspireRedis не поддерживает метрики по умолчанию из-за ограничений библиотеки StackExchange.Redis.
хостинг интеграция AzureRedis
Чтобы развернуть ресурсы Redis в Azure, установите 📦Aspire. Хостинг.Azure. пакет NuGetRedis:
dotnet add package Aspire.Hosting.Azure.Redis
Добавьте ресурс Azure Cache for Redisserver
После установки пакета размещения .NET AspireAzureRedis вызовите метод расширения AddAzureRedis в проекте хоста приложения.
var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddAzureRedis("azcache")
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(cache);
Предыдущий вызов AddAzureRedis настраивает ресурс Redisserver для развертывания как Azure Cache for Redis.
Важный
По умолчанию AddAzureRedis настраивает аутентификацию Microsoft Entra ID. Для этого требуются изменения в приложениях, которые должны подключаться к этим ресурсам, например, интеграции client.
Добавить распределенные Azure Cache for Redisclient
По умолчанию при вызове AddAzureRedis в интеграции размещения Redis она настраивает 📦 Майкрософт.Azure. StackExchangeRedis пакет NuGet для включения проверки подлинности:
dotnet add package Microsoft.Azure.StackExchangeRedis
Подключение Redis можно использовать с помощью интеграции client и 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.AddRedisDistributedCache("cache", configureOptions: options =>
{
options.Defaults = configurationOptions.Defaults;
});
Дополнительные сведения см. в Майкрософт.Azure. Репозиторий StackExchangeRedis.
См. также
*: Redis является зарегистрированным товарным знаком Redis Ltd. Любые права, указанные в них, зарезервированы для Redis Ltd. Любое использование корпорации Майкрософт предназначено только для ссылок и не указывает на спонсорство, подтверждение или принадлежность между Redis и Корпорацией Майкрософт. Вернуться к верхней?
.NET Aspire