.NET Aspire Elasticsearch 통합

포함:호스팅 통합 및 Client 통합

Elasticsearch 증가하는 사용 사례를 해결할 수 있는 분산형 RESTful 검색 및 분석 엔진, 확장 가능한 데이터 저장소 및 벡터 데이터베이스입니다. .NET Aspire Elasticsearch 통합을 사용하면 기존 Elasticsearch 인스턴스에 연결하거나 docker.io/library/elasticsearch 컨테이너 이미지사용하여 .NET 새 인스턴스를 만들 수 있습니다.

호스팅 통합

Elasticsearch 호스팅 통합은 Elasticsearch 인스턴스를 ElasticsearchResource 형식으로 모델화합니다. 이 형식과 API에 액세스하여 📦Aspire에 추가하려면, 앱 호스트 프로젝트에서Elasticsearch NuGet 패키지를 사용하십시오.

dotnet add package Aspire.Hosting.Elasticsearch

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

자세한 내용은 dotnet add package 또는 manage package dependencies in .NET applications.

Elasticsearch 리소스 추가

앱 호스트 프로젝트에서 builder 인스턴스에서 AddElasticsearch 호출하여 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 인스턴스가 만들어집니다. ExampleProject에 Elasticsearch 리소스(elasticsearch 변수)에 대한 참조가 추가됩니다. Elasticsearch 리소스에는 "elastic"username 있는 기본 자격 증명과 암호가 제공되지 않은 경우 CreateDefaultPasswordParameter 메서드를 사용하여 임의로 생성된 password 포함됩니다.

WithReference 메서드는 "elasticsearch"라는 이름의 ExampleProject에 연결을 구성합니다. 자세한 내용은 컨테이너 리소스 수명 주기참조하세요.

데이터 볼륨과 함께 Elasticsearch 리소스를 추가

Elasticsearch 리소스에 데이터 볼륨을 추가하려면 Elasticsearch 리소스에서 WithDataVolume 메서드를 호출합니다.

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 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 Elasticsearch 컨테이너의 /usr/share/elasticsearch/data 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및바인드 마운트보다 선호하는 이유에 대한 자세한 내용은 문서: 볼륨를 참조하세요.

데이터 바인드 마운트를 사용하여 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 데이터를 지속합니다. 데이터 바인드 마운트는 Elasticsearch 컨테이너의 호스트 컴퓨터에서 Windows에서는 C:\Elasticsearch\Data 경로에, Unix에서는 /Elasticsearch/Data 경로에 마운트됩니다. 데이터 바인드 마운트에 대한 자세한 정보는 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 Aspire Elasticsearch client 통합을 시작하려면, 📦AspireElastic.Clients.Elasticsearch NuGet 패키지를 설치합니다. client-consuming 프로젝트, 즉 Elasticsearchclient을 사용하는 애플리케이션의 프로젝트에서. Elasticsearch client 통합은 Elasticsearch와 상호 작용하기 위해 사용할 수 있는 ElasticsearchClient 인스턴스를 등록합니다.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

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

Elasticsearch client 추가

client을 사용하는 프로젝트의 Program.cs 파일에서 종속성 주입 컨테이너를 통해 사용할 ElasticsearchClient를 등록하기 위해 모든 IHostApplicationBuilder에서 AddElasticsearchClient 확장 메서드를 호출합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddElasticsearchClient(connectionName: "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 Aspire Elasticsearch client 통합은 프로젝트의 요구 사항 및 규칙에 따라 server 연결을 구성하는 여러 옵션을 제공합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 builder.AddElasticsearchClient호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddElasticsearchClient("elasticsearch");

그런 다음 ConnectionStrings 구성 섹션에서 연결 문자열을 검색합니다.

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

구성 공급자 사용

.NET Aspire Elasticsearch Client 통합은 Microsoft.Extensions.Configuration지원합니다. Aspire:Elastic:Clients:Elasticsearch 키를 사용하여 구성에서 ElasticClientsElasticsearchSettings 로드합니다. 다음 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>"
        }
      }
    }
  }
}

전체 Elasticsearchclient 통합 JSON 스키마는 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사용하는 경우 builder.AddElasticsearchClient호출할 때 Aspire:Elastic:Clients:Elasticsearch 섹션에서 CloudId 및 ApiKey 제공할 수 있습니다.

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 Aspire Elasticsearch 통합은 구성된 client를 사용하여 PingAsync을 수행합니다. 결과가 HTTP 200 OK이면 상태 검사가 정상으로 간주되고 그렇지 않으면 비정상입니다. 마찬가지로 예외가 있는 경우 상태 검사는 상태 검사 실패를 통해 전파되는 오류와 함께 비정상으로 간주됩니다.

관찰 가능성 및 원격 분석

통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성핵심 요소라고도 . 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

추적

.NET Aspire Elasticsearch 통합 기능은 OpenTelemetry를 사용하여 다음 추적 활동을 발생시킬 것입니다.

• Elastic.Transport

같이 보기

• Elasticsearch .NET
• .NET .NET Aspire 통합
• .NET Aspire GitHub 리포지토리