.NET Aspire Redis ^* интеграция ®

Статья
02/05/2025

включает в себя: интеграцию хостинга и 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 для их выражения в виде ресурсов в проекте хоста приложения , добавьте пакет NuGet 📦Aspire.Hosting.Redis.

.NET CLI
PackageReference

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 развертываниях при помощи нашего AI-ассистента Redis Copilot. .NET .NET Aspire добавляет ещё один образ контейнера docker.io/redis/redisinsight на хост приложения, который запускает приложение Commander.

Заметка

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

.NET CLI
PackageReference

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 вне жизненного цикла контейнера. Том данных подключается по пути /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, создавая снимки данных Garnet через заданные интервалы и при достижении порогового значения. Интервал времени interval — это промежуток между экспортами моментальных снимков, а keysChangedThreshold — это количество операций изменения ключей, необходимых для запуска моментального снимка. Дополнительные сведения о постоянстве см. в документации Redis: Постоянство.

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

.NET CLI
PackageReference

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

интеграция Client

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

.NET CLI
PackageReference

dotnet add package Aspire.StackExchange.Redis

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

Добавить клиента Redis

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения 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 внедрение зависимостей.

Добавить клиента с ключом Redis

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

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

Интеграция клиента .NET Aspire Stack Exchange Redis предоставляет несколько вариантов настройки подключения 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": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

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

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

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

builder.AddRedisClient(
    "cache",
    static settings => settings.DisableTracing = true);

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

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

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

OpenTelemetry.Instrumentation.StackExchangeRedis

Метрика

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

См. также

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

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

.NET Aspire Redis ^* интеграция ®

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

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

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

Добавить ресурс Redis с Redis командиром

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

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

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

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

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

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

Добавить ресурс Garnet с функцией сохранения

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

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

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

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

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

интеграция Client

Добавить клиента Redis

Добавить клиента с ключом Redis

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

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

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

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

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

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

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

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

Метрика

См. также

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

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

.NET Aspire Redis * интеграция ®

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

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

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

Добавить ресурс Redis с Redis командиром

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

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

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

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

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

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

Добавить ресурс Garnet с функцией сохранения

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

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

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

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

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

интеграция Client

Добавить клиента Redis

Добавить клиента с ключом Redis

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

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

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

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

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

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

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

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

Метрика

См. также

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

.NET Aspire Redis ^* интеграция ®