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


.NET Aspire Redis * интеграция распределенного кэширования ®

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

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

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

Узнайте, как использовать интеграцию .NET AspireRedis распределенного кэширования. Библиотека Aspire.StackExchange.Redis.DistributedCaching используется для регистрации поставщика IDistributedCache, который поддерживается сервером Valkey с образом 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, которые позволяют добавить его в пакет NuGet 📦Aspire.Hosting.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, чтобы добавить его в пакет NuGet 📦Aspire.Hosting.Valkey в проекте узла приложения.

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

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

интеграция Client

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

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

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

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

builder.AddRedisDistributedCache(connectionName: "cache");

Совет

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

Совет

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

Совет

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

Затем можно получить объект IDistributedCache благодаря внедрению зависимостей. Например, чтобы получить кэш из службы, выполните следующие действия.

public class ExampleService(IDistributedCache cache)
{
    // Use cache...
}

Дополнительные сведения о внедрении зависимостей см. в разделе .NET внедрение зависимостей.

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

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров 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": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

Для полной схемы интеграции клиента с распределенным кэшированием см. в Redis.

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

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

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

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

builder.AddRedisDistributedCache(
    "cache",
     null,
     static options => options.ConnectTimeout = 3_000);

Client контроль состояния интеграции

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

Интеграция с распределенным кэшированием .NET AspireRedis обрабатывает следующее:

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

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

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

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

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

  • Aspire.StackExchange.Redis
  • Microsoft.Extensions.Caching.StackExchangeRedis

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

Интеграция распределенного кэширования .NET AspireRedis инициирует следующие трассировочные действия с помощью OpenTelemetry.

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Метрика

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

См. также

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