Udostępnij za pośrednictwem

integracja .NET AspireElasticsearch

  • Artykuł

obejmuje:integrację hostingu oraz Client integrację

Elasticsearch jest rozproszonym silnikiem do wyszukiwania i analizy RESTful, skalowalnym magazynem danych i bazą danych wektorów, która pozwala sprostać rosnącej liczbie scenariuszy użycia. Integracja .NET AspireElasticsearch umożliwia łączenie się z istniejącymi wystąpieniami Elasticsearch lub tworzenie nowych wystąpień z .NET przy użyciu obrazu kontenera docker.io/library/elasticsearch.

Integracja hostingu

Modele integracji hostingu Elasticsearch modelują wystąpienie Elasticsearch jako typ ElasticsearchResource. Aby uzyskać dostęp do tego typu i interfejsów API, które umożliwiają dodanie go do 📦Aspire.Hosting.Elasticsearch pakietu NuGet w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Elasticsearch

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietu w aplikacjach .NET.

Dodawanie zasobu Elasticsearch

W projekcie hosta aplikacji wywołaj AddElasticsearch na instancji builder, aby dodać zasób Elasticsearch.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem docker.io/library/elasticsearch, tworzy nowe wystąpienie Elasticsearch na komputerze lokalnym. Dodawane jest odwołanie do zasobu Elasticsearch (zmiennej elasticsearch) w ExampleProject. Zasób Elasticsearch zawiera poświadczenia domyślne z username"elastic" i losowo wygenerowane password przy użyciu metody CreateDefaultPasswordParameter, gdy nie podano hasła.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie "elasticsearch". Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym wystąpieniem Elasticsearch, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zapoznaj się z Odwołaj się do istniejących zasobów.

Dodawanie zasobu Elasticsearch z woluminem danych

Aby dodać wolumin danych do zasobu Elasticsearch, wywołaj metodę WithDataVolume w zasobie Elasticsearch:

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

Wolumin danych służy do przechowywania Elasticsearch danych poza okresem życia jego kontenera. Wolumin danych jest instalowany w ścieżce /usr/share/elasticsearch/data w kontenerze Elasticsearch, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat woluminów danych oraz szczegóły, dlaczego są one preferowane zamiast montowania bind , zobacz dokumentację Docker: Wolumeny.

Dodaj zasób Elasticsearch z montowaniem powiązania danych

Aby dodać dołączenie powiązania danych do zasobu Elasticsearch, wywołaj metodę 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...

Ważny

Powiązania montowania danych mają ograniczoną funkcjonalność w porównaniu z woluminami , które oferują lepszą wydajność, przenośność i bezpieczeństwo, co sprawia, że są bardziej odpowiednie dla środowisk produkcyjnych. Jednak punkty montowania na sztywno umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do prac deweloperskich i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Montaże powiązań danych polegają na systemie plików maszyny hosta w celu zapewnienia trwałości danych Elasticsearch podczas ponownych uruchomień kontenera. Powiązanie danych jest zamontowane na C:\Elasticsearch\Data na systemie Windows (lub /Elasticsearch/Data na ścieżce Unix) na maszynie hosta w kontenerze Elasticsearch. Aby uzyskać więcej informacji na temat mocowań powiązań danych, zobacz dokumentację: Mocowania powiązane.

Dodawanie zasobu Elasticsearch przy użyciu parametru hasła

Jeśli chcesz jawnie podać hasło używane przez obraz kontenera, możesz podać te poświadczenia jako parametry. Rozważmy następujący przykład alternatywny:

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

Aby uzyskać więcej informacji na temat udostępniania parametrów, zobacz Parametry zewnętrzne.

Hostowanie kontroli kondycji integracji

Integracja hostowania Elasticsearch automatycznie dodaje kontrolę kondycji zasobu Elasticsearch. Sprawdzenie stanu systemu sprawdza, czy wystąpienie Elasticsearch jest uruchomione i czy można nawiązać z nim połączenie.

Integracja hostingu opiera się na 📦 AspNetCore.HealthChecks.Elasticsearch pakietu NuGet.

integracja Client

Aby rozpocząć pracę z integracją .NET AspireElasticsearchclient, zainstaluj 📦Aspire.Elastic.Clients.Elasticsearch pakiet NuGet w projekcie, który korzysta z client. Jest to projekt dla aplikacji korzystającej z Elasticsearchclient. Integracja Elasticsearchclient rejestruje instancję ElasticsearchClient, którą można użyć do współpracy z Elasticsearch.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Dodaj Elasticsearchclient

W pliku Program.cs projektu korzystającego z client, wywołaj metodę rozszerzenia AddElasticsearchClient dla dowolnego IHostApplicationBuilder, aby zarejestrować ElasticsearchClient do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Elasticsearch w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodaj zasób Elasticsearch.

Następnie można pobrać wystąpienie ElasticsearchClient przy użyciu wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Dodaj klucz Elasticsearchclient

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień ElasticsearchClient z różnymi nazwami połączeń. Aby zarejestrować klientów kluczowych Elasticsearch, wywołaj AddKeyedElasticsearchClient:

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

Następnie można pobrać wystąpienia ElasticsearchClient przy użyciu wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług z kluczami, zobacz .NET wstrzykiwanie zależności: usługi z kluczami.

Konfiguracja

Integracja .NET AspireElasticsearchclient oferuje wiele opcji konfigurowania połączenia server na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania builder.AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

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

Korzystanie z dostawców konfiguracji

Integracja .NET AspireElasticsearchClient obsługuje Microsoft.Extensions.Configuration. Ładuje ElasticClientsElasticsearchSettings z konfiguracji przy użyciu klucza Aspire:Elastic:Clients:Elasticsearch. Rozważmy poniższy przykład ustawienia aplikacji.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny schemat integracji ElasticsearchclientJSON, zobacz Aspire.Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<ElasticClientsElasticsearchSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje w linii kodu, na przykład w celu ustawienia klucza API z kodu.

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

Użyj CloudId i ApiKey z dostawcami konfiguracji

W przypadku korzystania z Elastic Cloudmożna podać CloudId i ApiKey w sekcji Aspire:Elastic:Clients:Elasticsearch podczas wywoływania builder.AddElasticsearchClient.

builder.AddElasticsearchClient("elasticsearch");

Rozważmy poniższy przykład ustawienia aplikacji.json, który konfiguruje opcje:

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

Użyj CloudId i ApiKey z delegatami wbudowanymi

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

Client kontrola stanu integracji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireElasticsearch wykorzystuje skonfigurowany client do przeprowadzenia PingAsync. Jeśli wynikiem jest HTTP 200 OK, sprawdzanie kondycji jest uważane za sprawne, w przeciwnym razie jest uznawane za niesprawne. Podobnie, jeśli wystąpi wyjątek, sprawdzanie kondycji jest uznawane za niezdrowe z propagowanym błędem na skutek niepowodzenia.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje do rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Śledzenie

Integracja .NET AspireElasticsearch spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • Elastic.Transport

Zobacz też