.NET Aspire Elasticsearch integration
omfattar:
Som värd för integrering och Client integration
Elasticsearch är en distribuerad, RESTful-sök- och analysmotor, skalbart datalager och en vektordatabas som kan hantera ett växande antal användningsfall. Med integreringen .NET AspireElasticsearch kan du ansluta till befintliga Elasticsearch-instanser eller skapa nya instanser från .NET med docker.io/library/elasticsearch containeravbildningen.
Hostningsintegration
Elasticsearch's hostingintegrering modellerar en Elasticsearch-instans som en ElasticsearchResource-typ. För att komma åt den här typen av och API:er som gör att du kan lägga till den i ditt 📦Aspire.Hosting.Elasticsearch NuGet-paket till appvärd-projektet.
dotnet add package Aspire.Hosting.Elasticsearch
För mer information, se dotnet add package eller Hantera paketberoenden i .NET applikationer.
Lägga till Elasticsearch resurs
I ditt appvärdprojekt anropar du AddElasticsearch till builder-instansen för att lägga till resursen Elasticsearch:
var builder = DistributedApplication.CreateBuilder(args);
var elasticsearch = builder.AddElasticsearch("elasticsearch");
builder.AddProject<Projects.ExampleProject>()
.WithReference(elasticsearch);
// After adding all resources, run the app...
När .NET.NET Aspire lägger till en containeravbildning i appvärden, som du ser i föregående exempel med docker.io/library/elasticsearch avbildningen, skapar den en ny Elasticsearch instans på den lokala datorn. En referens till din Elasticsearch resurs (variabeln elasticsearch) läggs till i ExampleProject. Resursen Elasticsearch innehåller standardautentiseringsuppgifter med username"elastic" och slumpmässigt genererade password med hjälp av CreateDefaultPasswordParameter-metoden när ett lösenord inte angavs.
Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "elasticsearch". Mer information finns i Livscykel för containerresurser.
Tips
Om du hellre vill ansluta till en befintlig Elasticsearch instans anropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.
Lägga till Elasticsearch resurs med datavolym
Om du vill lägga till en datavolym i resursen Elasticsearch anropar du metoden WithDataVolume på den Elasticsearch resursen:
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...
Datavolymen används för att bevara Elasticsearch data utanför containerns livscykel. Datavolymen monteras på sökvägen /usr/share/elasticsearch/data i containern Elasticsearch och när en name parameter inte specificeras genereras namnet slumpmässigt. För mer information om datavolymer och varför de föredras framför bindningsmonter, se Docker-dokumentationen: Volymer.
Lägg till Elasticsearch resurs med databindningsmontering
Om du vill lägga till en databindningsmontering till den Elasticsearch resursen anropar du metoden 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...
Viktig
Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.
Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara Elasticsearch data mellan omstarter av containrar. Databindningsmonteringen monteras på sökvägen C:\Elasticsearch\Data i Windows (eller /Elasticsearch/Data på Unix) på värddatorn i Elasticsearch-containern. För mer information om databindningspunkter finns i Docker dokument: Bindningspunkter.
Lägga till Elasticsearch resurs med lösenordsparameter
När du uttryckligen vill ange lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:
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...
Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.
Hälsoövervakning av integrationsvärdar
Elasticsearch värdintegrering lägger automatiskt till en hälsokontroll för den Elasticsearch resursen. Hälsokontrollen verifierar att Elasticsearch-instansen körs och att en anslutning kan upprättas till den.
Värdintegreringen förlitar sig på 📦 AspNetCore.HealthChecks.Elasticsearch NuGet-paketet.
Client integration
Kom igång med .NET AspireElasticsearch-klientintegrering genom att installera 📦Aspire. Elastic.Clients.Elasticsearch NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder Elasticsearch-klienten. Elasticsearch-klientintegrering registrerar en ElasticsearchClient instans som du kan använda för att interagera med Elasticsearch.
dotnet add package Aspire.Elastic.Clients.Elasticsearch
Lägg till Elasticsearch klient
I Program.cs-filen för ditt klientprojekt anropar du AddElasticsearchClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en ElasticsearchClient för användning via beroendeinjiceringscontainern. Metoden tar en parameter för anslutningsnamn.
builder.AddElasticsearchClient(connectionName: "elasticsearch");
Tips
Parametern connectionName måste matcha namnet som används när du lägger till resursen Elasticsearch i appvärdsprojektet. Mer information finns i Lägg till Elasticsearch resurs.
Du kan sedan hämta ElasticsearchClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:
public class ExampleService(ElasticsearchClient client)
{
// Use client...
}
Lägg till klient med nyckel Elasticsearch
Det kan finnas situationer där du vill registrera flera ElasticsearchClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Elasticsearch klienter anropar du AddKeyedElasticsearchClient:
builder.AddKeyedElasticsearchClient(name: "products");
builder.AddKeyedElasticsearchClient(name: "orders");
Sedan kan du hämta ElasticsearchClient instanser med hjälp av dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:
public class ExampleService(
[FromKeyedServices("products")] ElasticsearchClient productsClient,
[FromKeyedServices("orders")] ElasticsearchClient ordersClient)
{
// Use clients...
}
För mer information om nyckelade tjänster, se .NET beroendeinjektion: Nyckelade tjänster.
Konfiguration
Den .NET AspireElasticsearch klientintegrering innehåller flera alternativ för att konfigurera serveranslutningen baserat på kraven och konventionerna i ditt projekt.
Använda en anslutningssträng
När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddElasticsearchClient:
builder.AddElasticsearchClient("elasticsearch");
Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:
{
"ConnectionStrings": {
"elasticsearch": "http://elastic:password@localhost:27011"
}
}
Använda konfigurationsprovidrar
.NET Aspire
Elasticsearch
Client-integreringen stöder Microsoft.Extensions.Configuration. Den läser in ElasticClientsElasticsearchSettings från konfigurationen med hjälp av Aspire:Elastic:Clients:Elasticsearch-nyckeln. Överväg följande exempel appsettings.json som konfigurerar några av alternativen:
{
"Aspire": {
"Elastic": {
"Clients": {
"Elasticsearch": {
"DisableHealthChecks": false,
"DisableTracing": false,
"HealthCheckTimeout": "00:00:03",
"ApiKey": "<Valid ApiKey>",
"Endpoint": "http://elastic:password@localhost:27011",
"CloudId": "<Valid CloudId>"
}
}
}
}
}
Det fullständiga Elasticsearch klientintegreringsschemat JSON finns i Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.
Använd inline-delegater
Du kan också använda Action<ElasticClientsElasticsearchSettings> configureSettings delegering för att konfigurera vissa eller alla alternativ direkt i koden, till exempel för att ange API-nyckeln från koden:
builder.AddElasticsearchClient(
"elasticsearch",
static settings =>
settings.Endpoint = new Uri("http://elastic:password@localhost:27011"));
Använd en CloudId och en ApiKey med konfigurationsleverantörer
När du använder Elastic Cloudkan du ange CloudId och ApiKey i avsnittet Aspire:Elastic:Clients:Elasticsearch när du anropar builder.AddElasticsearchClient.
builder.AddElasticsearchClient("elasticsearch");
Överväg följande exempel appsettings.json som konfigurerar alternativen:
{
"Aspire": {
"Elastic": {
"Clients": {
"Elasticsearch": {
"ApiKey": "<Valid ApiKey>",
"CloudId": "<Valid CloudId>"
}
}
}
}
}
Använd en CloudId och en ApiKey med inline-delegater
builder.AddElasticsearchClient(
"elasticsearch",
static settings =>
{
settings.ApiKey = "<Valid ApiKey>";
settings.CloudId = "<Valid CloudId>";
});
Client hälsokontroller för integrering
Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.
.NET Aspire
Elasticsearch-integreringen använder den konfigurerade klienten för att utföra PingAsync. Om resultatet är en HTTP 200 OK anses hälsokontrollen vara felfri, annars är den inte felfri. På samma sätt, om det finns ett undantag, anses hälsokontrollen vara ohälsosam och felet sprids genom hälsokontrollens misslyckande.
Observerbarhet och telemetri
.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.
Spårning
.NET Aspire Elasticsearch-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:
Elastic.Transport
Se även
.NET Aspire