Get started with the Elasticsearch integrations

Este conteúdo não está disponível em sua língua ainda.

Elasticsearch is a distributed, RESTful search and analytics engine, scalable data store, and vector database capable of addressing a growing number of use cases. The Aspire Elasticsearch integration provides a way to connect to existing Elasticsearch instances, or create new instances from the docker.io/library/elasticsearch container image.

In this introduction, you’ll see how to install and use the Aspire Elasticsearch integrations in a simple configuration. If you already have this knowledge, see Elasticsearch Hosting integration for full reference details.

Set up hosting integration

To begin, install the Aspire Elasticsearch Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Elasticsearch instances from your Aspire hosting projects:

aspire add elasticsearch

A Aspire CLI é interativa; escolha o resultado adequado quando solicitado:

Select an integration to add:

> elasticsearch (Aspire.Hosting.Elasticsearch)
> Other results listed as selectable options...

#:package Aspire.Hosting.Elasticsearch@*

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

Next, in the AppHost project, create an instance of an Elasticsearch resource, then pass it to the consuming client projects:

Select your programming language to get started

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
                            .WaitFor(elasticsearch)
                            .WithReference(elasticsearch);

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddUvicornApp("api", "./api", "main.app")
                            .WithExternalHttpEndpoints()
                            .WaitFor(elasticsearch)
                            .WithReference(elasticsearch);

var builder = DistributedApplication.CreateBuilder(args);

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

var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js")
                 .WithExternalHttpEndpoints()
                 .WaitFor(elasticsearch)
                 .WithReference(elasticsearch);

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire Elasticsearch client integration:

dotnet add package Aspire.Elastic.Clients.Elasticsearch

#:package Aspire.Elastic.Clients.Elasticsearch@*

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

In the Program.cs file of your client-consuming project, call the AddElasticsearchClient extension method on any IHostApplicationBuilder to register an ElasticsearchClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

To interact with Elasticsearch in your Python consuming projects, you need to include the official Elasticsearch Python client library. You can install this library using pip:

pip install elasticsearch

Ensure that you import the Elasticsearch client in code files that interact with Elasticsearch. You should also import the os module to access environment variables:

from elasticsearch import Elasticsearch
import os

To interact with Elasticsearch in your JavaScript consuming projects, you need to include the official Elasticsearch JavaScript client library. You can install this library using npm:

npm install @elastic/elasticsearch

Ensure that you import the Elasticsearch client in code files that interact with Elasticsearch:

import { Client } from '@elastic/elasticsearch';

Use injected Elasticsearch properties

In the AppHost, when you used the WithReference method to pass an Elasticsearch resource to a consuming client project, Aspire injects a connection string property that you can use in the consuming project. Aspire exposes the connection string as an environment variable named ConnectionStrings__elasticsearch.

Use the GetValue() method to obtain this environment variable in consuming projects:

string endpoint = builder.Configuration.GetValue<string>("ConnectionStrings__elasticsearch");

Use the os.getenv() method to obtain this environment variable in consuming projects:

elasticsearch_endpoint = os.getenv("ConnectionStrings__elasticsearch")

Use the process.env method to obtain this environment variable in consuming projects:

const elasticsearchEndpoint = process.env.ConnectionStrings__elasticsearch;

Use Elasticsearch resources in client code

Now that you’ve added ElasticsearchClient to the builder in the consuming project, you can use the Elasticsearch resource to interact with the search engine. Get the ElasticsearchClient instance using dependency injection. For example, to retrieve your client object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

public class ExampleService(ElasticsearchClient client)
{
    // Use client to interact with Elasticsearch...
}

Having obtained the client, you can work with Elasticsearch as you would in any other C# application.

Use the information you have obtained about the Elasticsearch resource to connect to the search engine. Here is an example of how to connect using the official Python client:

es = Elasticsearch(elasticsearch_endpoint)

Having obtained the client, you can work with Elasticsearch as you would in any other Python application.

Use the information you have obtained about the Elasticsearch resource to connect to the search engine. Here is an example of how to connect using the official JavaScript client:

const client = new Client({
  node: elasticsearchEndpoint
});

Having obtained the client, you can work with Elasticsearch as you would in any other JavaScript application.

Next steps

Now, that you have an Aspire app with Elasticsearch integrations up and running, you can use the following reference documents to learn how to configure and interact with the Elasticsearch resources:

Understand the Elasticsearch hosting integration Discover how to configure persistence, passwords, and more.

Understand the Elasticsearch client integration Discover how to configure keyed clients, client integration health checks, and more.