.NET Aspire NATS интеграция

Статья
01/31/2025

Включает:интеграция размещения и Client интеграция

NATS — это высокопроизводительная, безопасная, распределенная система обмена сообщениями. Интеграция .NET AspireNATS позволяет подключаться к существующим экземплярам NATS или создавать новые экземпляры из .NET с помощью docker.io/library/nats образа контейнера.

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

NATS интеграции размещения для .NET Aspire моделирует сервер NATS в качестве типа NatsServerResource. Чтобы получить доступ к этому типу, установите пакет NuGet 📦Aspire.Hosting.Nats в узле приложения проекта , а затем добавьте его с помощью построителя.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Nats

<PackageReference Include="Aspire.Hosting.Nats"
                  Version="*" />

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

Добавить ресурс сервера NATS

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

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");

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

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

Когда .NET.NET Aspire добавляет образ контейнера в узел приложения, как показано в предыдущем примере с изображением docker.io/library/nats, он создает новый экземпляр сервера NATS на локальном компьютере. Ссылка на сервер NATS (переменная nats) добавляется в ExampleProject.

Метод WithReference настраивает подключение в ExampleProject с именем "nats". Для получения дополнительной информации см. Жизненный цикл ресурсов контейнера.

Кончик

Если вы хотите подключиться к существующему серверу NATS, вызовите AddConnectionString вместо этого. Для получения дополнительной информации см. Справочник по существующим ресурсам .

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

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

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithJetStream();

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

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

Функция NATS JetStream предоставляет встроенный механизм сохраняемости с именем JetStream, который позволяет хранить и воспроизводить сообщения позже. При необходимости можно указать параметр srcMountPath, чтобы указать путь к каталогу данных JetStream на хост-компьютере (предоставленный путь подключения сопоставляется с аргументом -sd контейнера).

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

Чтобы добавить том данных в ресурс сервера NATS, вызовите метод WithDataVolume в ресурсе сервера NATS:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataVolume(isReadOnly: false);

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

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

Том данных используется для сохранения данных сервера NATS за пределами жизненного цикла контейнера. Том данных смонтирован по пути /var/lib/nats в контейнере сервера NATS. Имя создается случайным образом, если не указать параметр name. Дополнительные сведения о томах данных и сведения о том, почему они предпочтительнее привязки, см. в Docker документации по томам.

Добавить ресурс сервера NATS с привязкой данных

Чтобы добавить привязку данных к ресурсу сервера NATS, вызовите метод WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataBindMount(
                      source: @"C:\NATS\Data",
                      isReadOnly: false);

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

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

Важный

Подключения привязки данных имеют ограниченные функциональные возможности по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для рабочих сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, идеально подходит для разработки и тестирования, в которых требуются изменения в режиме реального времени.

Монтирование данных с привязкой зависит от файловой системы хост-компьютера для сохранения данных сервера NATS при перезапуске контейнера. Монтаж привязки данных осуществляется в точке C:\NATS\Data на Windows (или /NATS/Data на Unix) на хост-компьютере внутри контейнера сервера NATS. Дополнительные сведения о подключениях привязки данных см. в документации по Docker: привязка подключений.

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

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

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

интеграция Client

Чтобы приступить к работе с интеграцией клиента .NET AspireNATS, установите 📦Aspire.NATS.Net пакет NuGet в проекте, который использует клиент, то есть в проект для приложения, использующего клиент NATS. Интеграция клиента NATS регистрирует экземпляр INatsConnection, который можно использовать для взаимодействия с NATS.

.NET CLI
PackageReference

dotnet add package Aspire.NATS.Net

<PackageReference Include="Aspire.NATS.Net"
                  Version="*" />

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

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

builder.AddNatsClient(connectionName: "nats");

Кончик

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

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

public class ExampleService(INatsConnection connection)
{
    // Use connection...
}

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

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

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

builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");

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

public class ExampleService(
    [FromKeyedServices("chat")] INatsConnection chatConnection,
    [FromKeyedServices("queue")] INatsConnection queueConnection)
{
    // Use connections...
}

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

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

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

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

Укажите имя строки подключения при вызове builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

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

{
  "ConnectionStrings": {
    "nats": "nats://nats:4222"
  }
}

Дополнительные сведения о форматировании этой строки подключения см. в документации ConnectionString.

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

Интеграция .NET AspireNATS поддерживает Microsoft.Extensions.Configuration. Он загружает NatsClientSettings из файла конфигурации с помощью ключа Aspire:Nats:Client. Следующий фрагмент кода является примером файла appsettings.json, который настраивает некоторые параметры:

{
  "Aspire": {
    "Nats": {
      "Client": {
        "ConnectionString": "nats://nats:4222",
        "DisableHealthChecks": true,
        "DisableTracing": true
      }
    }
  }
}

Полная схема интеграции клиента NATSJSON представлена в Aspire.NATS.Net/ConfigurationSchema.json.

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

Передайте делегат Action<NatsClientSettings> configureSettings, чтобы настроить некоторые или все встроенные параметры, например отключить проверки работоспособности из кода:

builder.AddNatsClient(
    "nats",
    static settings => settings.DisableHealthChecks  = true);

NATS в манифесте .NET Aspire

NATS не является частью манифеста развертывания .NET Aspire. Рекомендуется настроить защищенный рабочий NATS сервер за пределами .NET Aspire.

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

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

Интеграция .NET AspireNATS обрабатывает следующее:

Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки работоспособности должны быть пройдены, чтобы приложение считалось готовым принять трафик.

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

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

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

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

NATS

Трассировка

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

NATS.Net

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