integratie van .NET AspireElasticsearch

omvat:hostingintegratie en Client integratie

Elasticsearch is een gedistribueerde, RESTful zoek- en analyse-engine, een schaalbaar gegevensarchief en een vectordatabase die in staat is om een toenemend aantal gebruiksvoorbeelden aan te pakken. Met de .NET AspireElasticsearch-integratie kun je verbinding maken met bestaande Elasticsearch-exemplaren of nieuwe exemplaren creëren vanuit .NET met de docker.io/library/elasticsearch containerafbeelding.

Hostingintegratie

Het Elasticsearch hostintegratiemodel modelleert een Elasticsearch instantie als het ElasticsearchResource type. Voor toegang tot dit type en API's waarmee u het kunt toevoegen aan uw 📦Aspire.Hosting.Elasticsearch NuGet-pakket in het app-hostproject.

.NET CLI

dotnet add package Aspire.Hosting.Elasticsearch

PackageReference

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Elasticsearch-resource toevoegen

Roep in uw app-hostproject AddElasticsearch aan op het builder exemplaar om een Elasticsearch-resource toe te voegen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de docker.io/library/elasticsearch-installatiekopie, wordt er een nieuw Elasticsearch exemplaar op uw lokale computer gemaakt. Er wordt een verwijzing naar uw Elasticsearch resource (de variabele elasticsearch) toegevoegd aan de ExampleProject. De Elasticsearch-resource bevat standaardreferenties met een username van "elastic" en willekeurig gegenereerde password met behulp van de CreateDefaultPasswordParameter methode wanneer er geen wachtwoord is opgegeven.

De methode WithReference configureert een verbinding in de ExampleProject met de naam "elasticsearch". Zie levenscyclus van containerresourcesvoor meer informatie.

Tip

Als u liever verbinding wilt maken met een bestaand Elasticsearch exemplaar, roept u in plaats daarvan AddConnectionString aan. Zie Bestaande resourcesraadplegen voor meer informatie.

Elasticsearch resource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de Elasticsearch-resource, roept u de methode WithDataVolume aan voor de Elasticsearch resource:

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

Het gegevensvolume wordt gebruikt om de Elasticsearch gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /usr/share/elasticsearch/data pad in de Elasticsearch container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Zie Docker docs: Volumesvoor meer informatie over gegevensvolumes en details over waarom ze de voorkeur hebben boven bindingskoppelingen.

Elasticsearch resource toevoegen met koppeling voor gegevensbinding

Als u een koppeling voor gegevensbinding wilt toevoegen aan de Elasticsearch-resource, roept u de WithDataBindMount methode aan:

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

Belangrijk

Gegevens koppelen beperkte functionaliteit hebben in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind-mounts bieden echter directe toegang tot en wijzigingen van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar real-time wijzigingen nodig zijn.

Gegevensbind-koppelpunten zijn afhankelijk van het bestandssysteem van de hostmachine om de Elasticsearch gegevens te behouden bij het opnieuw opstarten van de container. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\Elasticsearch\Data in Windows (of /Elasticsearch/Data op Unix) op de hostcomputer in de Elasticsearch container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Resource toevoegen Elasticsearch met wachtwoordparameter

Wanneer u expliciet het wachtwoord wilt opgeven dat wordt gebruikt door de containerafbeelding, kunt u deze referenties opgeven als parameters. Bekijk het volgende alternatieve voorbeeld:

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

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

Gezondheidscontroles voor hostingintegratie

De Elasticsearch hostingintegratie voegt automatisch een statuscontrole toe voor de Elasticsearch resource. De statuscontrole controleert of het Elasticsearch-exemplaar draait en of er een correcte verbinding tot stand kan worden gebracht.

De hostingintegratie is afhankelijk van de 📦 AspNetCore.HealthChecks.Elasticsearch NuGet-pakket.

integratie van Client

Om aan de slag te gaan met de .NET AspireElasticsearchclient-integratie, installeer het 📦Aspire.Elastic.Clients.Elasticsearch NuGet-pakket in het project dat de clientgebruikt, dat wil zeggen, het project voor de toepassing die gebruikmaakt van de Elasticsearchclient. De Elasticsearchclient-integratie registreert een ElasticsearchClient exemplaar dat u kunt gebruiken om met Elasticsearchte communiceren.

.NET CLI

dotnet add package Aspire.Elastic.Clients.Elasticsearch

PackageReference

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

Elasticsearch client toevoegen

Roep in het Program.cs bestand van uw clientverbruikende project de AddElasticsearchClient-extensiemethode aan op elke IHostApplicationBuilder om een ElasticsearchClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Elasticsearch resource in het app-hostproject. Zie voor meer informatie Voeg Elasticsearch resourcetoe.

Vervolgens kunt u het ElasticsearchClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Sleutel-Elasticsearchclient toevoegen

Er kunnen situaties zijn waarin u meerdere ElasticsearchClient exemplaren met verschillende verbindingsnamen wilt registreren. Als u keyed Elasticsearch clients wilt registreren, roept u de AddKeyedElasticsearchClientaan:

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

Vervolgens kunt u de ElasticsearchClient exemplaren ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over gesleutelde services, zie .NET afhankelijkheidsinjectie: Keyed Services.

Configuratie

De .NET AspireElasticsearchclient-integratie biedt meerdere opties voor het configureren van de server-verbinding op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van builder.AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie:

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

Configuratieproviders gebruiken

De .NET AspireElasticsearchClient-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de ElasticClientsElasticsearchSettings vanuit de configuratie met behulp van de Aspire:Elastic:Clients:Elasticsearch-sleutel. Bekijk het volgende voorbeeld appsettings.json waarmee een aantal van de opties wordt geconfigureerd:

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

Zie Aspirevoor de volledige integratie van ElasticsearchclientJSON schema. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Inline delegates gebruiken

U kunt de Action<ElasticClientsElasticsearchSettings> configureSettings gedelegeerde ook doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om de API-sleutel in te stellen vanuit code:

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

Een CloudId en een ApiKey gebruiken met configuratieproviders

Wanneer u Elastic Cloud-gebruikt, kunt u de CloudId en ApiKey opgeven in Aspire:Elastic:Clients:Elasticsearch sectie wanneer u builder.AddElasticsearchClientaanroept.

builder.AddElasticsearchClient("elasticsearch");

Bekijk het volgende voorbeeld appsettings.json waarmee de opties worden geconfigureerd:

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

Een CloudId en een ApiKey gebruiken met inline gedelegeerden

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

Gezondheidscontroles voor Client-integratie

Standaard zijn .NET.NET Aspire integraties zo ingesteld dat ze statuscontroles voor alle diensten uitvoeren. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De .NET AspireElasticsearch-integratie maakt gebruik van de geconfigureerde client om een PingAsyncuit te voeren. Als het resultaat een HTTP 200 OK is, wordt de statuscontrole als in orde beschouwd, anders is deze niet in orde. Als er een uitzondering is, wordt de statuscontrole beschouwd als ongezond, met de fout die zich verspreidt door het mislukken van de statuscontrole.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties automatisch configuraties voor loggen, tracering en metrieken instellen, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Opsporing

De .NET AspireElasticsearch-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Elastic.Transport

Zie ook

• Elasticsearch .NET
• .NET .NET Aspire integraties
• .NET Aspire GitHub repository