.NET Aspire Redis * интеграция ®
Включает:интеграцию размещения и Client интеграцию
Redis — это самая быстрая платформа данных в мире для кэширования, векторного поиска и баз данных NoSQL. Интеграция .NET AspireRedis позволяет подключаться к существующим экземплярам Redis или создавать новые экземпляры из .NET с помощью docker.io/library/redis
образа контейнера.
Гарнет — это высокопроизводительное хранилище кэша из Microsoft Research и соответствует протоколу сериализации Redis (RESP). Интеграция .NET AspireRedis позволяет подключаться к существующим экземплярам Garnet или создавать новые экземпляры из .NET с помощью образа контейнера ghcr.io/microsoft/garnet
.
Valkey является Redis форком и соответствует протоколу сериализации Redis (RESP). Это высокопроизводительное хранилище типа ключ/значение, которое поддерживает различные типы нагрузки, такие как кэширование и очереди сообщений, и может использоваться в качестве основной базы данных. Интеграция .NET AspireRedis позволяет подключаться к существующим экземплярам Valkey или создавать новые экземпляры из .NET с помощью образа контейнера docker.io/valkey/valkey
.
Интеграция хостинга
Redis интеграции моделирует ресурс Redis в качестве типа RedisResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в
dotnet add package Aspire.Hosting.Redis
Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях .NET.
Добавьте ресурс Redis
На экземпляре builder
вашего проекта узла приложения вызовите AddRedis, чтобы добавить ресурс 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
Чтобы добавить
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 развертываниях при помощи нашего AI-ассистента 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, которые позволяют добавить его в пакет NuGet 📦Aspire.Hosting.Garnet в проект app host приложения.
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
в контейнере Гарнета и когда параметр 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, которые позволяют добавить его в 📦Aspire. Host.Valkey пакет NuGet в проекте узла приложения.
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 и можно ли к нему подключиться.
Интеграция размещения зависит от 📦 AspNetCore.HealthChecks.Redis пакет NuGet.
интеграция Client
Чтобы приступить к работе с интеграцией Stack Exchange Redisclient.NET Aspire, установите пакет NuGet 📦AspireStackExchangeRedis в проект, который использует client, то есть в проект приложения, использующего Redisclient. Интеграция Redisclient регистрирует экземпляр IConnectionMultiplexer, который можно использовать для взаимодействия с Redis.
dotnet add package Aspire.StackExchange.Redis
Добавьте Redisclient
В файле Program.cs вашего проекта на базе clientвызовите метод расширения AddRedisClient для любого IHostApplicationBuilder, чтобы зарегистрировать IConnectionMultiplexer
для использования через контейнер внедрения зависимостей. Метод принимает параметр имени подключения.
builder.AddRedisClient(connectionName: "cache");
Совет
Параметр connectionName
должен соответствовать имени, используемому при добавлении ресурса Redis в проект узла приложения. Дополнительные сведения см. в разделе Добавление Redis ресурса.
Совет
Параметр connectionName
должен соответствовать имени, используемому при добавлении ресурса Garnet в проект узла приложения. Дополнительную информацию см. в разделе Добавление ресурса Garnet.
Совет
Параметр connectionName
должен соответствовать имени, используемому при добавлении ресурса Valkey в проект узла приложения. Дополнительные сведения см. в разделе Добавление ресурса Valkey.
Затем можно получить экземпляр IConnection
с помощью внедрения зависимостей. Например, чтобы получить подключение из примера службы:
public class ExampleService(IConnectionMultiplexer connectionMux)
{
// Use connection multiplexer...
}
Дополнительные сведения о внедрении зависимостей см. в .NET внедрение зависимостей.
Добавьте ключ Redisclient
Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров IConnectionMultiplexer
с различными именами подключений. Чтобы зарегистрировать клиентов с ключами Redis, вызовите метод AddKeyedRedisClient.
builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");
Затем вы можете получить экземпляры IConnectionMultiplexer
с помощью инъекции зависимостей. Например, чтобы получить подключение из примера службы:
public class ExampleService(
[FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
[FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
// Use connections...
}
Дополнительные сведения о службах с ключами см. в разделе .NET внедрение зависимостей: службы с ключами.
Конфигурация
Интеграция Redisclient Stack Exchange .NET Aspire предоставляет несколько вариантов настройки подключения Redis на основе требований и соглашений проекта.
Используйте строку подключения
При использовании строки подключения из раздела конфигурации ConnectionStrings
можно указать имя строки подключения при вызове AddRedis:
builder.AddRedis("cache");
При использовании строки подключения из раздела конфигурации ConnectionStrings
можно указать имя строки подключения при вызове AddGarnet:
builder.AddGarnet("cache");
При использовании строки подключения из раздела конфигурации ConnectionStrings
можно указать имя строки подключения при вызове AddValkey:
builder.AddValkey("cache");
Затем строка подключения будет получена из раздела конфигурации ConnectionStrings
:
{
"ConnectionStrings": {
"cache": "localhost:6379"
}
}
Дополнительные сведения о том, как форматировать эту строку подключения, см. в документации Redis по конфигурации Stack 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
}
}
}
}
Для полной схемы интеграции RedisclientJSON смотрите Aspire. StackExchange.Redis/ConfigurationSchema.json.
Использование встроенных делегатов
Можно также передать делегат Action<StackExchangeRedisSettings>
для настройки некоторых или всех встроенных параметров, например для настройки DisableTracing
:
builder.AddRedisClient(
"cache",
static settings => settings.DisableTracing = true);
Client проверки работоспособности интеграции
По умолчанию .NET.NET Aspire интеграции позволяют проверки работоспособности для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.
Интеграция .NET Aspire Stack Exchange Redis обрабатывает следующее:
- Добавляет проверку работоспособности, когда StackExchangeRedisSettings.DisableHealthChecks является
false
, которая пытается подключиться к экземпляру контейнера. - Интегрируется с HTTP точкой доступа
/health
, которая указывает, что все зарегистрированные проверки работоспособности должны быть пройдены, чтобы программу считали готовой к приему трафика.
Наблюдаемость и телеметрия
.NET
.NET Aspire интеграции автоматически настраивают конфигурации для ведения журналов, трассировки и метрик, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации
Лесозаготовка
Интеграция Redis Stack Exchange .NET Aspire использует следующие категории журналов:
Aspire.StackExchange.Redis
Отслеживание
Интеграция .NET Aspire Stack Exchange Redis будет генерировать следующие действия трассировки с использованием OpenTelemetry:
OpenTelemetry.Instrumentation.StackExchangeRedis
Метрика
В настоящее время интеграция Redis Stack Exchange .NET Aspire не поддерживает метрики по умолчанию из-за ограничений библиотеки StackExchange.Redis
.
интеграция хостинга AzureRedis
Чтобы развернуть ресурсы Redis в Azure, установите пакет NuGet 📦Aspire.Hosting.Azure.Redis:
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.AddRedisClient("cache", configureOptions: options =>
{
options.Defaults = configurationOptions.Defaults;
});
Дополнительные сведения см. в репозитории StackExchangeRedis на Microsoft.Azure.
См. также
*: Redis является зарегистрированным товарным знаком Redis Ltd. Любые права, указанные в них, зарезервированы для Redis Ltd. Любое использование корпорации Майкрософт предназначено только для ссылок и не указывает на спонсорство, подтверждение или принадлежность между Redis и Корпорацией Майкрософт. Вернуться к верхней?
.NET Aspire