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 ExampleProjectwird ein Verweis auf Ihre Elasticsearch-Ressource (die Variable elasticsearch) 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 WithDataVolume-Methode für die Elasticsearch-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 WithDataBindMount-Methode auf, um der Elasticsearch-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 Elasticsearch auf dem Pfad C:\Elasticsearch\Data unter Windows (oder /Elasticsearch/Data auf Unix) 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 AspireElasticsearchclient-Integration zu beginnen, installieren Sie das 📦Aspire.Elastic.Clients.Elasticsearch NuGet-Paket im Projekt, das clientverwendet, d. h. im Projekt für die Anwendung, die die Elasticsearchclientverwendet. Die Elasticsearchclient-Integration registriert eine ElasticsearchClient Instanz, die Sie für die Interaktion mit Elasticsearchverwenden können.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Hinzufügen von Elasticsearchclient

Rufen Sie in der Program.cs-Datei Ihres client-verbrauchenden Projekts die AddElasticsearchClient-Erweiterungsmethode für jedes IHostApplicationBuilder auf, um eine ElasticsearchClient für die Verwendung über den Abhängigkeitsinjektionscontainer 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...
}

Hinzufügen von codiertem Elasticsearchclient

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 AspireElasticsearchclient-Integration bietet mehrere Optionen zum Konfigurieren der server Verbindung 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 Appsettingsjson, 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>"
        }
      }
    }
  }
}

Das vollständige Elasticsearchclient Integration JSON Schema finden Sie unter 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");

Sehen Sie sich das folgende Beispiel Appsettings an.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 die konfigurierte 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