integrace .NET AspireElasticsearch

zahrnuje:hosting integrace a Client integrace

Elasticsearch je distribuovaný vyhledávací a analytický modul RESTful, škálovatelné úložiště dat a vektorová databáze schopné řešit rostoucí počet případů použití. Integrace umožňuje připojit se k existujícím instancím nebo vytvářet nové instance z pomocíimage kontejneru .

Integrace hostování

Integrace Elasticsearch hostování modeluje instanci Elasticsearch jako typ ElasticsearchResource. Chcete-li získat přístup k tomuto typu a rozhraním API, které vám umožní je přidat do 📦Aspire.Hosting.Elasticsearch balíčku NuGet v projektu hostitele aplikace.

.NET rozhraní příkazového řádku

dotnet add package Aspire.Hosting.Elasticsearch

PackageReference

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

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidání prostředku Elasticsearch

V projektu hostitele aplikace zavolejte na instanci builder příkaz AddElasticsearch a přidejte prostředek Elasticsearch.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí docker.io/library/elasticsearch, vytvoří na místním počítači novou instanci Elasticsearch. Do ExampleProjectse přidá odkaz na váš prostředek Elasticsearch (proměnná elasticsearch). Prostředek Elasticsearch obsahuje výchozí přihlašovací údaje s username"elastic" a náhodně vygenerovanými password pomocí metody CreateDefaultPasswordParameter, pokud heslo nebylo zadané.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "elasticsearch". Další informace viz životní cyklus kontejnerového prostředku.

Rada

Pokud byste se raději připojili k existující instanci Elasticsearch, volejte místo toho AddConnectionString. Další informace viz Odkazy na existující zdroje.

Přidat Elasticsearch zdroj s datovým objemem

Pokud chcete do prostředku Elasticsearch přidat datový svazek, zavolejte metodu WithDataVolume prostředku 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...

Objem dat se používá k zachování Elasticsearch dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /usr/share/elasticsearch/data v kontejneru Elasticsearch a když není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč jsou preferovány před bind mounty, najdete v dokumentaci Docker: Svazky.

Přidání prostředku Elasticsearch s připojením vazby dat

Chcete-li přidat datový bind mount k prostředku Elasticsearch, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Vazby mount však umožňují přímý přístup a úpravy souborů v hostitelském systému, což je ideální pro vývoj a testování, kde jsou potřeba změny v reálném čase.

Připojení vazby dat využívají systém souborů hostitelského počítače k zachování Elasticsearch dat napříč restartováními kontejneru. Připojení vazby dat je namontováno na cestu C:\Elasticsearch\Data ve Windows (nebo /Elasticsearch/Data na Unix) na hostitelském počítači v kontejneru Elasticsearch. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidejte prostředek Elasticsearch s parametrem pro heslo

Pokud chcete explicitně zadat heslo používané imagí kontejneru, můžete tyto přihlašovací údaje zadat jako parametry. Podívejte se na následující alternativní příklad:

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

Další informace o poskytování parametrů naleznete v tématu Externí parametry.

Hostování kontrol stavu integrace

Integrace hostování Elasticsearch automaticky přidá kontrolu stavu prostředku Elasticsearch. Kontrola stavu ověřuje, že je spuštěná instance Elasticsearch a že se k ní dá navázat připojení.

Integrace hostování spoléhá na 📦 AspNetCore.HealthChecks.Elasticsearch balíček NuGet.

integrace Client

Pokud chcete začít s integrací .NET AspireElasticsearchclient, nainstalujte 📦Aspire. Elastic.Clients.Elasticsearch NuGet balíček v rámci projektu client, tj. projektu pro aplikaci, která používá Elasticsearchclient. Integrace Elasticsearchclient zaregistruje instanci ElasticsearchClient, kterou můžete použít k interakci s Elasticsearch.

.NET rozhraní příkazového řádku

dotnet add package Aspire.Elastic.Clients.Elasticsearch

PackageReference

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

Přidejte Elasticsearchclient

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddElasticsearchClient na libovolném IHostApplicationBuilder a zaregistrujte ElasticsearchClient pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Elasticsearch do hostitelského projektu aplikace. Další informace najdete v Přidání Elasticsearch prostředku.

Potom můžete načíst instanci ElasticsearchClient pomocí vkládání závislostí. Například pro načtení připojení z ukázkové služby:

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

Přidání Elasticsearchclient s klíči

Mohou nastat situace, kdy chcete registrovat více instancí ElasticsearchClient s různými jmény připojení. Pokud chcete zaregistrovat klíčované klienty Elasticsearch, zavolejte AddKeyedElasticsearchClient:

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

Potom můžete načíst tyto instance ElasticsearchClient pomocí injektování závislostí. Například pro načtení spojení z ukázkové služby:

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

Další informace o klíčových službách najdete v části .NET vkládání závislostí: Klíčové služby.

Konfigurace

Integrace .NET AspireElasticsearchclient poskytuje několik možností konfigurace připojení server na základě požadavků a konvencí projektu.

Použití připojovacího řetězce

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddElasticsearchClientzadat název připojovacího řetězce:

builder.AddElasticsearchClient("elasticsearch");

Pak bude připojovací řetězec načten z konfigurační sekce ConnectionStrings:

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

Použití zprostředkovatelů konfigurace

Integrace .NET AspireElasticsearchClient podporuje Microsoft.Extensions.Configuration. Načte ElasticClientsElasticsearchSettings z konfigurace pomocí klíče Aspire:Elastic:Clients:Elasticsearch. Podívejte se na následující příklad nastavení aplikace.json, která konfiguruje některé z možností:

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

Kompletní schéma integrace ElasticsearchclientJSON najdete v tématu Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<ElasticClientsElasticsearchSettings> configureSettings a nastavit některé nebo všechny možnosti přímo, například nastavit API klíč z kódu:

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

Použijte CloudId a ApiKey s poskytovateli konfigurace

Při použití elastického cloudumůžete při volání builder.AddElasticsearchClientzadat CloudId a ApiKey v Aspire:Elastic:Clients:Elasticsearch sekci.

builder.AddElasticsearchClient("elasticsearch");

Zvažte následující příklad nastavení aplikace.json, který konfiguruje možnosti:

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

Použijte CloudId a ApiKey s vloženými delegáty

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

Client kontroly stavu integrace

Ve výchozím nastavení umožňují integrace .NET.NET Aspire provádění zdravotních kontrol pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

Integrace .NET AspireElasticsearch používá client, které bylo nakonfigurované, k provedení PingAsync. Pokud je výsledkem HTTP 200 OK, je kontrola stavu považována za v pořádku, jinak není v pořádku. Podobně platí, že pokud dojde k výjimce, je kontrola stavu považována za nezdravou a chyba se šíří přes selhání kontroly stavu.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví tyto konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Trasování

Integrace .NET AspireElasticsearch pomocí OpenTelemetryvygeneruje následující aktivity trasování:

• Elastic.Transport

Viz také

• Elasticsearch .NET
• integrace .NET.NET Aspire
• .NET Aspire GitHub řrepo