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

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

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

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

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

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

Добавление ресурса сервера NATS с параметрами проверки подлинности

Если вы хотите явно указать имя пользователя и пароль, их можно указать в качестве параметров. Рассмотрим следующий альтернативный пример:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var nats = builder.AddNats(
    name: "nats",
    userName: username,
    password: password);

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


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

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

Добавьте ресурс сервера 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. Дополнительную информацию о томах данных и почему их предпочитают вместо bind mounts можно найти в 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.

dotnet add package Aspire.NATS.Net

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

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

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

builder.AddNatsClient(connectionName: "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

См. также

• NATSБыстрый старт для .Net
• интеграции .NET.NET Aspire
• .NET Aspire GitHub репозиторий