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

Статья
12/13/2024

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

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

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

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

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Nats

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

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

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

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

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, он создает новый экземпляр NATSserver на локальном компьютере. Ссылка на NATSserver (переменная nats) добавляется в ExampleProject.

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

Кончик

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

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

Чтобы добавить NATS JetStream в ресурс NATSserver, вызовите метод 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 контейнера).

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

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

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

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

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

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

Важный

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

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

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

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

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

интеграция Client

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

.NET CLI
PackageReference

dotnet add package Aspire.NATS.Net

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

Добавьте NATSclient

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

builder.AddNatsClient(connectionName: "nats");

Кончик

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

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

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

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

Добавить ключ NATSclient

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

См. полную схему интеграции NATSclientJSON в Aspire.NATS.Net/ConfigurationSchema.json.

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

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

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

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

NATS не является частью манифеста развертывания .NET Aspire. Рекомендуется настроить безопасное производственное NATSserver за пределами .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

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