Condividi tramite

integrazione di .NET AspireElasticsearch

  • Articolo

Include:integrazione dell'hosting e Client integrazione

Elasticsearch è un motore di ricerca e analisi RESTful distribuito, un archivio dati scalabile e un database vettoriale in grado di affrontare un numero crescente di casi d'uso. L'integrazione .NET AspireElasticsearch consente di connettersi alle istanze di Elasticsearch esistenti o di creare nuove istanze da .NET con l'immagine del contenitore docker.io/library/elasticsearch.

Integrazione dell'hosting

L'integrazione di hosting Elasticsearch modella un'istanza Elasticsearch come tipo ElasticsearchResource. Per accedere a questo tipo e alle API che consentono di aggiungerlo al pacchetto NuGet 📦Aspire.Hosting.Elasticsearch nel progetto host dell'app.

dotnet add package Aspire.Hosting.Elasticsearch

Per ulteriori informazioni, consultare dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere risorsa Elasticsearch

Nel progetto host dell'app, chiama AddElasticsearch sull'istanza di builder per aggiungere una risorsa Elasticsearch.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/library/elasticsearch, crea una nuova istanza Elasticsearch nel computer locale. Viene aggiunto un riferimento alla risorsa Elasticsearch (variabile elasticsearch) al ExampleProject. La risorsa Elasticsearch include le credenziali predefinite con un username di "elastic" e un password generato casualmente usando il metodo CreateDefaultPasswordParameter nel caso in cui non sia stata fornita una password.

Il metodo WithReference configura una connessione nel ExampleProject denominato "elasticsearch". Per altre informazioni, vedere ciclo di vita delle risorse contenitore.

Mancia

Se preferisci connetterti a un'istanza di Elasticsearch esistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere la risorsa Elasticsearch con un volume di dati

Per aggiungere un volume di dati alla risorsa Elasticsearch, chiamare il metodo WithDataVolume nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati Elasticsearch all'esterno del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /usr/share/elasticsearch/data nel contenitore Elasticsearch e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Aggiungere la risorsa Elasticsearch con il bind mount dei dati

Per aggiungere un montaggio dell'associazione dati alla risorsa Elasticsearch, chiamare il metodo 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...

Importante

I di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretta dei file nel sistema host, ed è ideale per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati Elasticsearch tra i riavvii del contenitore. Il punto di montaggio dei dati è montato sul percorso C:\Elasticsearch\Data su Windows (o sul percorso /Elasticsearch/Data in Unix) sulla macchina host nel container Elasticsearch. Per ulteriori informazioni sui bind mount dei dati, vedere nei documenti Docker: Bind mounts.

Aggiungi la risorsa Elasticsearch con il parametro password

Quando si vuole specificare in modo esplicito la password usata dall'immagine del contenitore, è possibile specificare queste credenziali come parametri. Si consideri l'esempio alternativo seguente:

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

Per altre informazioni sulla fornitura di parametri, vedere Parametri esterni.

Hosting dei controlli di integrità dell'integrazione

L'integrazione dell'hosting Elasticsearch aggiunge automaticamente una verifica dello stato di salute per la risorsa Elasticsearch. Il controllo integrità verifica che l'istanza di Elasticsearch sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.Elasticsearch.

integrazione Client

Per iniziare con l'integrazione client .NET AspireElasticsearch, installare il pacchetto NuGet 📦Aspire.Elastic.Clients.Elasticsearch nel progetto che consuma il client, cioè il progetto per l'applicazione che utilizza il client Elasticsearch. L'integrazione client Elasticsearch registra un'istanza di ElasticsearchClient che è possibile usare per interagire con Elasticsearch.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Aggiungere Elasticsearch client

Nel file Program.cs del progetto che utilizza il client chiamare il metodo di estensione AddElasticsearchClient in qualsiasi IHostApplicationBuilder per registrare un ElasticsearchClient da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Mancia

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Elasticsearch nel progetto host dell'app. Per altre informazioni, vedere Aggiungere Elasticsearch risorsa.

È quindi possibile recuperare l'istanza di ElasticsearchClient usando l'iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Aggiungere il client Elasticsearch con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di ElasticsearchClient con nomi di connessione diversi. Per registrare i clienti con chiave di tipo Elasticsearch, chiamare il AddKeyedElasticsearchClient:

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

È quindi possibile recuperare le istanze di ElasticsearchClient usando l'iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per altre informazioni sui servizi con chiave, vedere .NET inserimento delle dipendenze: Servizi con chiave.

Configurazione

L'integrazione client .NET AspireElasticsearch offre più opzioni per configurare la connessione server in base ai requisiti e alle convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama builder.AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

La stringa di connessione verrà quindi recuperata dalla sezione di configurazione ConnectionStrings:

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

Utilizzare i provider di configurazione

L'integrazione .NET AspireElasticsearchClient supporta Microsoft.Extensions.Configuration. Carica il ElasticClientsElasticsearchSettings dalla configurazione usando la chiave Aspire:Elastic:Clients:Elasticsearch. Si consideri l'esempio seguente appsettings.json che configura alcune delle opzioni:

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

Per lo schema di integrazione client completo ElasticsearchJSON, vedere Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Usare delegati inline

È inoltre possibile passare il delegato Action<ElasticClientsElasticsearchSettings> configureSettings per configurare alcune o tutte le opzioni inline, ad esempio per impostare la chiave API direttamente nel codice:

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

Usare un CloudId e un ApiKey con i provider di configurazione

Quando si usa Elastic Cloud, è possibile specificare il CloudId e il ApiKey nella sezione Aspire:Elastic:Clients:Elasticsearch quando si chiama builder.AddElasticsearchClient.

builder.AddElasticsearchClient("elasticsearch");

Si consideri l'esempio seguente appsettings.json che configura le opzioni:

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

Usare un CloudId e un ApiKey con delegati inline

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

Client controlli di integrità dell'integrazione

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano verifiche dello stato di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

L'integrazione .NET AspireElasticsearch usa il client configurato per eseguire un PingAsync. Se il risultato è HTTP 200 OK, il controllo dello stato di salute è considerato funzionante; in caso contrario, non è funzionante. Analogamente, se si verifica un'eccezione, il controllo integrità viene considerato non salutare e l'errore si propaga attraverso il fallimento del controllo integrità.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Tracciamento

L'integrazione .NET AspireElasticsearch genererà le attività di traccia seguenti usando OpenTelemetry:

  • Elastic.Transport

Vedere anche