Freigeben über

.NET Aspire Elasticsearch-Integration

  • Artikel

umfasst:Hostingintegration und Client Integration

Elasticsearch ist eine verteilte, RESTful-Such- und Analysemaschine, skalierbare Datenspeicher und Vektordatenbank, die eine wachsende Anzahl von Anwendungsfällen adressieren kann. Mit der .NET AspireElasticsearch-Integration können Sie eine Verbindung mit vorhandenen Elasticsearch-Instanzen herstellen oder neue Instanzen aus .NET mit dem docker.io/library/elasticsearch Container-Imageerstellen.

Hosting-Integration

Die Elasticsearch Hostintegrationsmodelle stellen eine Elasticsearch Instanz als ElasticsearchResource Typ dar. Um auf diesen Typ und die APIs zuzugreifen, die es Ihnen ermöglichen, ihn zu Ihrem 📦Aspire.Hosting-Elasticsearch--NuGet-Paket im -App-Host--Projekt hinzuzufügen.

dotnet add package Aspire.Hosting.Elasticsearch

Weitere Informationen finden Sie unter dotnet add package oder siehe Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

Füge die Elasticsearch-Ressource hinzu

Rufen Sie in Ihrem App-Host-Projekt AddElasticsearch auf der builder-Instanz auf, um eine Elasticsearch-Ressource hinzuzufügen.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem docker.io/library/elasticsearch-Image gezeigt, wird eine neue Elasticsearch Instanz auf dem lokalen Computer erstellt. Der Elasticsearchwird ein Verweis auf Ihre elasticsearch-Ressource (die Variable ExampleProject) hinzugefügt. Die Elasticsearch-Ressource enthält Standardanmeldeinformationen mit einem username von "elastic" und zufällig generierten password mithilfe der CreateDefaultPasswordParameter Methode, wenn kein Kennwort angegeben wurde.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens "elasticsearch". Weitere Informationen finden Sie unter Container-Ressourcenlebenszyklus.

Tipp

Wenn Sie lieber eine Verbindung mit einer vorhandenen Elasticsearch Instanz herstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Fügen Sie die Elasticsearch-Ressource mit Datenvolumen hinzu

Rufen Sie die Elasticsearch-Methode für die WithDataVolume-Ressource auf, um der Elasticsearch-Ressource ein Datenvolume hinzuzufügen:

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...

Das Datenvolume wird verwendet, um die Elasticsearch Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird am /usr/share/elasticsearch/data Pfad im container Elasticsearch bereitgestellt, und wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Daten-Volumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Volumes.

Ressource Elasticsearch mit Datenbind-Einbindung hinzufügen

Rufen Sie die Elasticsearch-Methode auf, um der WithDataBindMount-Ressource eine Datenbindung hinzuzufügen:

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...

Wichtig

Daten Binden von Bereitstellungen mit eingeschränkter Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie für Produktionsumgebungen besser geeignet sind. Bind-Mounts ermöglichen jedoch direkten Zugriff auf und Änderungen an Dateien auf dem Hostsystem und sind ideal für die Entwicklung und den Test, bei dem Echtzeitänderungen erforderlich sind.

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die Elasticsearch Daten über Containerneustarts hinweg beizubehalten. Die Datenbindung wird im Container C:\Elasticsearch\Data auf dem Pfad /Elasticsearch/Data unter Windows (oder Unix auf Elasticsearch) auf dem Hostcomputer eingebunden. Weitere Informationen zu Daten-Bind-Mounts finden Sie in der Docker Dokumentation: Bind Mounts.

Hinzufügen einer Elasticsearch Ressource, mit dem Kennwortparameter

Sie können das vom Container-Image verwendete Passwort explizit angeben, indem Sie diese Zugangsdaten als Parameter bereitstellen. Betrachten Sie das folgende alternative Beispiel:

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...

Weitere Informationen zum Bereitstellen von Parametern finden Sie unter externe Parameter.

Hosten von Integritätsprüfungen für Integration

Die Elasticsearch Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die Elasticsearch Ressource hinzu. Die Gesundheitsprüfung überprüft, ob die Instanz Elasticsearch ausgeführt wird und ob eine Verbindung hergestellt werden kann.

Die Hosting-Integration basiert auf den 📦 AspNetCore.HealthChecks- und denElasticsearch NuGet-Paketen.

Client-Integration

Um mit der .NET AspireElasticsearch Clientintegration zu beginnen, installieren Sie das 📦Aspire. Elastic.Clients.Elasticsearch NuGet-Paket im Client-verwendenden Projekt, das heißt, im Projekt für die Anwendung, die den Elasticsearch Client verwendet. Die Elasticsearch Clientintegration registriert eine ElasticsearchClient Instanz, mit der Sie mit Elasticsearchinteragieren können.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Füge Elasticsearch-Client hinzu

Rufen Sie in der Program.cs-Datei Ihres Client-Projekts die AddElasticsearchClient-Erweiterungsmethode für jedes IHostApplicationBuilder auf, um ein ElasticsearchClient für die Verwendung über den Dependency Injection-Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Tipp

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der Elasticsearch-Ressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Hinzufügen Elasticsearch Ressource.

Anschließend können Sie die ElasticsearchClient Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Gekennzeichneten Elasticsearch-Client hinzufügen

Es kann Situationen geben, in denen Sie mehrere ElasticsearchClient Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Um Elasticsearch-Clients zu registrieren, rufen Sie die AddKeyedElasticsearchClientan:

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

Anschließend können Sie die ElasticsearchClient-Instanzen mithilfe von Dependency Injection abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: schlüsselbasierte Dienste.

Konfiguration

Die .NET AspireElasticsearch Clientintegration bietet mehrere Optionen zum Konfigurieren der Serververbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddElasticsearchClientden Namen der Verbindungszeichenfolge angeben:

builder.AddElasticsearchClient("elasticsearch");

Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings abgerufen:

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

Verwenden von Konfigurationsanbietern

Die .NET AspireElasticsearchClient-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die ElasticClientsElasticsearchSettings mithilfe des Aspire:Elastic:Clients:Elasticsearch Schlüssels aus der Konfiguration. Betrachten Sie das folgende Beispiel appsettings.json, das einige der Optionen konfiguriert:

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

Für das vollständige Schema der Elasticsearch Clientintegration JSON siehe Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Verwendung von Inline-Delegaten

Sie können auch das Action<ElasticClientsElasticsearchSettings> configureSettings-Delegate übergeben, um einige oder alle Optionen inline einzurichten, zum Beispiel um den API-Schlüssel direkt aus dem Code festzulegen.

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

Verwenden Sie einen CloudId und einen ApiKey mit Konfigurationsanbietern

Wenn Sie Elastic Cloudverwenden, können Sie die CloudId und ApiKey im Abschnitt Aspire:Elastic:Clients:Elasticsearch beim Aufrufen von builder.AddElasticsearchClientbereitstellen.

builder.AddElasticsearchClient("elasticsearch");

Betrachten Sie das folgende Beispiel appsettings.json, das die Optionen konfiguriert:

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

Verwenden eines CloudId und eines ApiKey mit Inline-Delegaten

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

Client Gesundheitsprüfungen der Integration

Standardmäßig aktivieren die Integrationen .NET.NET Aspire Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Die .NET AspireElasticsearch-Integration verwendet den konfigurierten Client, um eine PingAsyncauszuführen. Wenn das Ergebnis ein HTTP 200 OK ist, wird die Gesundheitsprüfung als gesund betrachtet, andernfalls ist sie ungesund. Ebenso wird die Gesundheitsprüfung als nicht gesund betrachtet, wenn eine Ausnahme vorliegt, wobei der Fehler durch den Gesundheitsprüfungsfehler weitergegeben wird.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als den Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie in der .NET.NET Aspire Integrationsübersicht. Abhängig vom Unterstützungsdienst unterstützen einige Integrationen möglicherweise nur bestimmte dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefeatures können auch mithilfe der techniken deaktiviert werden, die im Abschnitt Configuration dargestellt werden.

Nachverfolgung

Die .NET AspireElasticsearch Integration gibt die folgenden Ablaufverfolgungsaktivitäten mithilfe von OpenTelemetryaus:

  • Elastic.Transport

Siehe auch