Aspire Elasticsearch-integratie (Voorvertoning)

Inclusief: —&— 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 AspireElasticsearch-integratie kunt u verbinding maken met bestaande Elasticsearch-instances, of vanuit .NET nieuwe instances maken met de docker.io/library/elasticsearch-containerimage.

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. Gastvrijheid.Elasticsearch NuGet-pakket in het AppHost-project .

dotnet add package Aspire.Hosting.Elasticsearch

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

Zie dotnet-pakket toevoegen of pakketafhankelijkheden beheren in .NET toepassingen voor meer informatie.

Elasticsearch-resource toevoegen

Roep in uw AppHost-project AddElasticsearch het builder exemplaar aan 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 Aspire een containerimage aan de AppHost toevoegt, zoals weergegeven in het vorige voorbeeld met de docker.io/library/elasticsearch containerimage, wordt er een nieuw Elasticsearch exemplaar op uw lokale machine 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 de levenscyclus van containerresources 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. Voor meer informatie over datavolumes en details over waarom ze de voorkeur hebben boven bindingskoppelingen, zie Dockerdocs: Volumes.

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

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 docs: Bind mountsDocker voor meer informatie over gegevens-bindmounts.

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 parameters voor 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 aspNetCore.HealthChecks📦.Elasticsearch NuGet-pakket.

Client integratie

Als u aan de slag wilt met de AspireElasticsearch clientintegratie, installeert u het 📦Aspire.Elastic.Clients.Elasticsearch NuGet-pakket in het project dat gebruikmaakt van de client, oftewel het project voor de toepassing die gebruikmaakt van de Elasticsearch client. De Elasticsearch clientintegratie registreert een ElasticsearchClient-exemplaar waarmee u kunt communiceren Elasticsearch.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

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

Elasticsearch-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte 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");

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

Gecodeerde Elasticsearch-client 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 AddKeyedElasticsearchClient aan:

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

Zie Afhankelijkheidsinjectie: Sleutelservices voor meer informatie over sleutelservices.NET.

Configuratie

De AspireElasticsearch-clientintegratie biedt meerdere opties voor het configureren van de serververbinding 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 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 enkele van de opties worden 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 voor het volledige Elasticsearch schema voor clientintegratie JSONAspire.Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Inline delegates gebruiken

U kunt ook de Action<ElasticClientsElasticsearchSettings> configureSettings delegate doorgeven om enkele of alle opties inline in te stellen, bijvoorbeeld om de API-sleutel in code in te stellen.

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 in Aspire:Elastic:Clients:Elasticsearch de sectie opgeven bij het aanroepen builder.AddElasticsearchClient.

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

Aspire Standaard schakelen integraties statuscontroles in voor alle services. Zie Aspire het overzicht van integraties voor meer informatie.

De AspireElasticsearch-integratie gebruikt 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

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. 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 AspireElasticsearch-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Elastic.Transport

Zie ook

• Elasticsearch .NET
• Aspire Integraties
• Aspire GitHub Repo