intégration de .NET AspireElasticsearch

inclut :intégration d’hébergement et intégration Client

Elasticsearch est un moteur distribué de recherche et d’analytique RESTful, un magasin de données scalable et une base de données vectorielle capable de traiter un nombre croissant de cas d’usage. L’intégration .NET AspireElasticsearch vous permet de vous connecter à des instances de Elasticsearch existantes ou de créer de nouvelles instances à partir de .NET avec l’image conteneur docker.io/library/elasticsearch.

Intégration de l’hébergement

Le Elasticsearch hébergeant des modèles d’intégration d’une instance de Elasticsearch comme type de ElasticsearchResource. Pour accéder à ce type et aux API qui vous permettent de l’ajouter à votre package NuGet 📦Aspire.HostingElasticsearch dans le projet hôte de l’application .

.NET CLI

dotnet add package Aspire.Hosting.Elasticsearch

RéférenceDePaquet

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

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de paquet dans les applications .NET.

Ajouter Elasticsearch ressource

Dans votre projet hôte d’application, appelez AddElasticsearch sur l’instance de builder pour ajouter une ressource Elasticsearch :

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image docker.io/library/elasticsearch, il crée une instance de Elasticsearch sur votre ordinateur local. Une référence à votre ressource Elasticsearch (la variable elasticsearch) est ajoutée au ExampleProject. La ressource Elasticsearch inclut des informations d’identification par défaut avec une username de "elastic" et des password générées de manière aléatoire à l’aide de la méthode CreateDefaultPasswordParameter lorsqu’un mot de passe n’a pas été fourni.

La méthode WithReference configure une connexion dans le ExampleProject nommé "elasticsearch". Pour plus d’informations, consultez le cycle de vie des ressources de conteneur .

Pourboire

Si vous préférez vous connecter à une instance de Elasticsearch existante, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter une ressource Elasticsearch avec un volume de données

Pour ajouter un volume de données à la ressource Elasticsearch, appelez la méthode WithDataVolume sur la ressource 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...

Le volume de données est utilisé pour conserver les données Elasticsearch en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /usr/share/elasticsearch/data dans le conteneur Elasticsearch et lorsqu’un paramètre name n’est pas fourni, le nom est généré aléatoirement. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison , consultez Docker documentation : Volumes.

Ajouter Elasticsearch ressource avec montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource Elasticsearch, appelez la méthode 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...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , qui offrent de meilleures performances, une meilleure portabilité et une sécurité accrue, les rendant ainsi plus adaptés aux environnements de production. Toutefois, les montages de liaison autorisent un accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et le test quand des modifications en temps réel sont nécessaires.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données Elasticsearch entre les redémarrages de conteneur. Le point de montage des données est monté à l'emplacement C:\Elasticsearch\Data sur Windows (ou à /Elasticsearch/Data sur Unix) sur l’ordinateur hôte dans le conteneur Elasticsearch. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Ajouter Elasticsearch ressource avec un paramètre de mot de passe

Lorsque vous souhaitez fournir explicitement le mot de passe utilisé par l’image conteneur, vous pouvez fournir ces informations d’identification en tant que paramètres. Prenons l’exemple de remplacement suivant :

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

Pour plus d’informations sur la fourniture de paramètres, consultez paramètres externes.

Vérifications de l'intégrité de l'intégration d'hébergement

L’intégration d’hébergement Elasticsearch ajoute automatiquement un contrôle d’intégrité pour la ressource Elasticsearch. La vérification d’intégrité confirme que l’instance de Elasticsearch est en cours d’exécution et qu’une connexion peut être établie à elle.

L’intégration de l’hébergement s’appuie sur 📦 AspNetCore.HealthChecks.Elasticsearch paquet NuGet.

intégration de Client

Pour commencer à utiliser l’intégration du client .NET AspireElasticsearch, installez le 📦Aspire. Elastic.Clients.Elasticsearch package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client Elasticsearch. L’intégration du client Elasticsearch inscrit une instance ElasticsearchClient que vous pouvez utiliser pour interagir avec Elasticsearch.

.NET CLI

dotnet add package Aspire.Elastic.Clients.Elasticsearch

RéférenceDePaquet

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

Ajouter Elasticsearch client

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddElasticsearchClient sur n’importe quelle IHostApplicationBuilder pour inscrire un ElasticsearchClient à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource Elasticsearch dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter Elasticsearch ressource.

Vous pouvez ensuite récupérer l’instance ElasticsearchClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Ajouter un client à clé Elasticsearch

Il peut arriver que vous souhaitiez inscrire plusieurs instances de ElasticsearchClient avec différents noms de connexion. Pour inscrire des clients avec la clé Elasticsearch, appelez le AddKeyedElasticsearchClient:

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

Vous pouvez ensuite récupérer les instances ElasticsearchClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Pour plus d’informations sur les services à clé, consultez l'injection de dépendances : services à clé .NET.

Configuration

L’intégration du client .NET AspireElasticsearch fournit plusieurs options pour configurer la connexion serveur en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de builder.AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

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

Utiliser des fournisseurs de configuration

L’intégration .NET AspireElasticsearchClient prend en charge Microsoft.Extensions.Configuration. Il charge le ElasticClientsElasticsearchSettings à partir de la configuration à l’aide de la clé Aspire:Elastic:Clients:Elasticsearch. Prenons l’exemple suivant appsettings.json qui configure certaines des options suivantes :

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

Pour le schéma complet de l’intégration du client Elasticsearch, JSON, consultez Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Utiliser des délégués inline

Vous pouvez également transmettre le délégué Action<ElasticClientsElasticsearchSettings> configureSettings pour configurer en ligne certaines ou toutes les options, par exemple pour définir la clé API directement à partir du code :

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

Utiliser un CloudId et un ApiKey avec des fournisseurs de configuration

Lorsque vous utilisez Elastic Cloud, vous pouvez fournir les CloudId et les ApiKey dans la section Aspire:Elastic:Clients:Elasticsearch lorsque vous appelez builder.AddElasticsearchClient.

builder.AddElasticsearchClient("elasticsearch");

Prenons l’exemple suivant appsettings.json qui configure les options :

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

Utiliser un CloudId et un ApiKey avec des délégués en ligne

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

Client vérifications d’intégrité de l’intégration

Par défaut, les .NET.NET Aspire intégrations permettent les contrôles de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

L'intégration .NET AspireElasticsearch utilise le client configuré pour effectuer une PingAsync. Si le résultat est HTTP 200 OK, le contrôle d’intégrité est considéré comme sain, sinon il n’est pas sain. De même, s’il y a une exception, la vérification de l'état de santé est considérée comme défectueuse, avec l’erreur se propageant par l’échec de cette vérification.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement la journalisation, le suivi et les métriques, parfois appelés les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Traçage

L’intégration .NET AspireElasticsearch émet les activités de suivi suivantes à l’aide de OpenTelemetry:

• Elastic.Transport

Voir aussi

• Elasticsearch .NET
• intégrations .NET.NET Aspire
• .NET Aspire GitHub dépôt