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

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

Elasticsearch — это распределенная подсистема поиска и аналитики RESTful, масштабируемое хранилище данных и векторная база данных, которая может решать растущее число вариантов использования. Интеграция .NET AspireElasticsearch позволяет подключаться к существующим экземплярам Elasticsearch или создавать новые экземпляры из .NET с помощью docker.io/library/elasticsearch образа контейнера.

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

Модель интеграции Elasticsearch представляет экземпляр Elasticsearch как тип ElasticsearchResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в пакет NuGet 📦Aspire.Хостинг.Elasticsearch в проекте хостинга приложения .

.NET интерфейс командной строки

dotnet add package Aspire.Hosting.Elasticsearch

PackageReference

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

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

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

В хост-проекте вашего приложения вызовите AddElasticsearch на экземпляре builder, чтобы добавить ресурс Elasticsearch.

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch");

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

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

Когда .NET.NET Aspire добавляет образ контейнера в узел приложения, как показано в предыдущем примере с изображением docker.io/library/elasticsearch, он создает новый экземпляр Elasticsearch на локальном компьютере. Ссылка на ресурс Elasticsearch (переменная elasticsearch) добавляется в ExampleProject. Ресурс Elasticsearch включает учетные данные по умолчанию, где username равен "elastic", и случайным образом сгенерированные password с помощью метода CreateDefaultPasswordParameter, если пароль не был указан.

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

Совет

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

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

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

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
                           .WithDataVolume(isReadOnly: false);

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

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

Том данных используется для постоянного хранения данных Elasticsearch за пределами жизненного цикла контейнера. Том данных подключается по пути /usr/share/elasticsearch/data в контейнере Elasticsearch и когда параметр name не указан, имя создается случайным образом. Дополнительная информация о томах данных и причинах их предпочтительности перед привязкамисодержатся в документации Docker: Томы.

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

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

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
                           .WithDataBindMount(
                               source: @"C:\Elasticsearch\Data",
                               isReadOnly: false);

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

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

Важный

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

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

Добавление ресурса Elasticsearch с параметром пароля

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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

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

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

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

интеграция Client

Чтобы приступить к работе с интеграцией .NET AspireElasticsearchclient, установите 📦Aspire. Elastic.Clients.Elasticsearch пакет NuGet в client-потребляющий проект, то есть проект для приложения, использующего Elasticsearchclient. Интеграция Elasticsearchclient регистрирует экземпляр ElasticsearchClient, который можно использовать для взаимодействия с Elasticsearch.

.NET CLI

dotnet add package Aspire.Elastic.Clients.Elasticsearch

PackageReference

<PackageReference Include="Aspire.Elastic.Clients.Elasticsearch"
                  Version="*" />

Добавьте Elasticsearchclient

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

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Совет

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

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

public class ExampleService(ElasticsearchClient client)
{
    // Use client...
}

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

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

builder.AddKeyedElasticsearchClient(name: "products");
builder.AddKeyedElasticsearchClient(name: "orders");

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

public class ExampleService(
    [FromKeyedServices("products")] ElasticsearchClient productsClient,
    [FromKeyedServices("orders")] ElasticsearchClient ordersClient)
{
    // Use clients...
}

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

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

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

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

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

builder.AddElasticsearchClient("elasticsearch");

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

{
  "ConnectionStrings": {
    "elasticsearch": "http://elastic:password@localhost:27011"
  }
}

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

Интеграция .NET AspireElasticsearchClient поддерживает Microsoft.Extensions.Configuration. Он загружает ElasticClientsElasticsearchSettings из конфигурации с помощью ключа Aspire:Elastic:Clients:Elasticsearch. Рассмотрим следующий пример appsettings.json, который настраивает некоторые параметры:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
            "DisableHealthChecks": false,
            "DisableTracing": false,
            "HealthCheckTimeout": "00:00:03",  
            "ApiKey": "<Valid ApiKey>",
            "Endpoint": "http://elastic:password@localhost:27011",
            "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

Полная схема интеграции ElasticsearchclientJSON смотрите в Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

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

Кроме того, можно передать делегат Action<ElasticClientsElasticsearchSettings> configureSettings, чтобы настроить некоторые или все встроенные параметры, например задать ключ API из кода:

builder.AddElasticsearchClient(
    "elasticsearch",
    static settings =>
        settings.Endpoint = new Uri("http://elastic:password@localhost:27011"));

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

При использовании Elastic Cloudможно указать CloudId и ApiKey в разделе Aspire:Elastic:Clients:Elasticsearch при вызове builder.AddElasticsearchClient.

builder.AddElasticsearchClient("elasticsearch");

Рассмотрим следующий пример appsettings.json, который настраивает параметры:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
            "ApiKey": "<Valid ApiKey>",
            "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

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

builder.AddElasticsearchClient(
    "elasticsearch",
    static settings =>
    {
        settings.ApiKey = "<Valid ApiKey>";
        settings.CloudId = "<Valid CloudId>";
    });

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

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

Интеграция .NET AspireElasticsearch использует настроенный client для выполнения PingAsync. Если результатом является HTTP 200 OK, проверка работоспособности считается успешной, в противном случае она неисправная. Аналогичным образом, если возникает исключение, проверка состояния системы считается неработоспособной, и ошибка распространяется через сбой проверки.

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

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

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

Интеграция .NET AspireElasticsearch будет генерировать следующие мероприятия по трассировке с помощью OpenTelemetry:

• Elastic.Transport

См. также

• Elasticsearch .NET
• интеграции .NET.NET Aspire
• .NET Aspire GitHub репозитория