Ағылшын тілінде оқу

Бөлісу құралы:

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

  • Мақала
Выберите ресурс размещения, поддерживающий протокол 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, которые позволяют добавить его в . Хостинг. пакет NuGet в проекте узла приложения .

Интерфейс командной строки.NET 
dotnet add package Aspire.Hosting.Redis

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях .NET.

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

На экземпляре AddRedis вашего проекта узла приложения вызовите builder, чтобы добавить ресурс Redis.

C# 
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

Чтобы добавить Insights в ресурс , вызовите метод :

C# 
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:

C# 
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:

C# 
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:

C# 
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 с подключением тома данных или привязки данных:

C# 
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 приложения.

Интерфейс командной строки.NET 
dotnet add package Aspire.Hosting.Garnet

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях .NET.

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

В проекте узла приложения вызовите метод AddGarnet для экземпляра builder, чтобы добавить ресурс Garnet.

C# 
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:

C# 
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:

C# 
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, используя либо том данных, либо привязку данных.

C# 
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 в проекте узла приложения.

Интерфейс командной строки.NET 
dotnet add package Aspire.Hosting.Valkey

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях .NET.

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

В проекте узла приложения вызовите AddValkey для экземпляра builder, чтобы добавить ресурс Valkey.

C# 
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:

C# 
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:

C# 
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 с подключением тома данных или привязки данных:

C# 
var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddValkey("cache")
                   .WithDataVolume()
                   .WithPersistence(
                       interval: TimeSpan.FromMinutes(5),
                       keysChangedThreshold: 100);

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

// After adding all resources, run the app...

Код, приведенный выше, обеспечивает сохранение ресурса Redis путем создания снимков данных Valkey с заданным интервалом и пороговым значением. Время interval — это интервал между экспортами моментальных снимков, а keysChangedThreshold — это количество операций изменения ключей, необходимых для запуска моментального снимка. Дополнительные сведения о постоянстве см. в документации Redis: Постоянство.

Проверка работоспособности интеграции

Интеграция размещения Redis автоматически добавляет проверку состояния для соответствующего типа ресурса. Проверка работоспособности проверяет, запущен ли сервер и что подключение можно установить к нему.

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

интеграция Client

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

Интерфейс командной строки.NET 
dotnet add package Aspire.StackExchange.Redis

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

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения AddRedisClient для любого IHostApplicationBuilder, чтобы зарегистрировать IConnectionMultiplexer для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

C# 
builder.AddRedisClient(connectionName: "cache");

Шайпұл

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

Шайпұл

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

Шайпұл

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

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

C# 
public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

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

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

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров IConnectionMultiplexer с различными именами подключений. Чтобы зарегистрировать клиентов с ключами Redis, вызовите метод AddKeyedRedisClient.

C# 
builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");

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

C# 
public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

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

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

Интеграция клиента .NET Aspire Stack Exchange Redis предоставляет несколько вариантов настройки подключения Redis на основе требований и соглашений проекта.

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

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове AddRedis:

C# 
builder.AddRedis("cache");

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове AddGarnet:

C# 
builder.AddGarnet("cache");

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове AddValkey:

C# 
builder.AddValkey("cache");

Затем строка подключения будет получена из раздела конфигурации ConnectionStrings:

JSON 
{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

Дополнительные сведения о том, как форматировать эту строку подключения, см. в документации Redis по конфигурации Stack Exchange.

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

Интеграция .NET Aspire Stack Exchange Redis поддерживает Microsoft.Extensions.Configuration. Он загружает StackExchangeRedisSettings из конфигурации с помощью ключа Aspire:StackExchange:Redis. Пример appsettings.json, который настраивает некоторые параметры:

JSON 
{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

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

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

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

C# 
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 обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

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

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

  • Aspire.StackExchange.Redis

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

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

  • OpenTelemetry.Instrumentation.StackExchangeRedis

Метрика

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

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

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

Интерфейс командной строки.NET 
dotnet add package Aspire.Hosting.Azure.Redis

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

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

C# 
var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

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

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

Маңызды

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

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

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

Интерфейс командной строки.NET 
dotnet add package Microsoft.Azure.StackExchangeRedis

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

C# 
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 и Корпорацией Майкрософт. Вернуться к верхней?