.NET Aspire Elasticsearch tümleştirmesi (Önizleme)

Içerir: Barındırma tümleştirmesi ve Client tümleştirmesi

Elasticsearch, artan sayıda kullanım örneğini ele alabilen dağıtılmış, RESTful arama ve analiz altyapısı, ölçeklenebilir veri deposu ve vektör veritabanıdır. .NET Aspire Elasticsearch tümleştirmesi, mevcut Elasticsearch örneklerine bağlanmanıza veya .NETdocker.io/library/elasticsearch kapsayıcı görüntüsüile yeni örnekler oluşturmanıza olanak tanır.

Barındırma entegrasyonu

Elasticsearch barındırma entegrasyonu, bir ElasticsearchResource örneğini Elasticsearch türü olarak modeller. Bu tür ve API'lere erişmek için 📦Aspire.Hosting.Elasticsearch NuGet paketini app host projesine ekleyin.

dotnet add package Aspire.Hosting.Elasticsearch

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

Daha fazla bilgi için bkz. dotnet add package veya .NET uygulamalarında paket bağımlılıklarını yönetme.

Elasticsearch kaynağı ekleme

Uygulama ana bilgisayar projenizde, bir AddElasticsearch kaynağı eklemek için builder'ı Elasticsearch örneğinde çağırın.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

.NET .NET Aspire, önceki örnekte docker.io/library/elasticsearch görüntüsüyle gösterildiği gibi uygulama konağına bir kapsayıcı görüntüsü eklediğinde, yerel makinenizde yeni bir Elasticsearch örneği oluşturur. ExampleProject'ye Elasticsearch kaynağınıza (elasticsearch değişkeni) bir başvuru eklenir. Elasticsearch kaynağı, username değeri "elastic" olan varsayılan kimlik bilgilerini ve parola sağlanmadığında password yöntemi kullanılarak rastgele oluşturulmuş CreateDefaultPasswordParameter içerir.

WithReference yöntemi, ExampleProject'deki "elasticsearch"adlı bir bağlantıyı yapılandırıyor. Daha fazla bilgi için bkz. Kapsayıcı kaynak yaşam döngüsü.

Veri hacmine sahip Elasticsearch kaynağı ekle

Elasticsearch kaynağına veri birimi eklemek için WithDataVolume kaynağında Elasticsearch yöntemini çağırın:

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

Veri hacmi, Elasticsearch verilerini kapsayıcısının yaşam döngüsü dışında kalıcı hale getirmek için kullanılır. Veri birimi, /usr/share/elasticsearch/data kapsayıcısının Elasticsearch yoluna bağlanır ve name parametresi sağlanmazsa ad rastgele oluşturulur. Veri hacimleri hakkında daha fazla bilgi edinmek vebağlamalara neden tercih edildikleri konusunda ayrıntılar için bkz: belgeler: Hacimler.

Veri bağlama ile Elasticsearch kaynağı ekleme

Elasticsearch kaynağına veri bağlaması eklemek için WithDataBindMount yöntemini çağırın:

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

Veri bind mount'lar, kapsayıcılar yeniden başlatıldığında Elasticsearch verilerini kalıcı hale getirmek için konak makinenin dosya sistemine dayanır. Veri bağlama noktası, Elasticsearch konteynerinde, konak makinedeki Windows'ta C:\Elasticsearch\Data (veya Unix üzerindeki /Elasticsearch/Data yolunda) konumuna monte edilir. Veri bağlama noktaları hakkında daha fazla bilgi için Docker belgelerine bakın: Bağlama noktaları.

Parola parametresiyle Elasticsearch kaynağı ekleme

Kapsayıcı görüntüsü tarafından kullanılan parolayı açıkça sağlamak istediğinizde, bu kimlik bilgilerini parametre olarak sağlayabilirsiniz. Aşağıdaki alternatif örneği göz önünde bulundurun:

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

Dış parametrelerin sağlanması hakkında daha fazla bilgi için bkz. External parameters.

Barındırma entegrasyonu için sağlık kontrolleri

Elasticsearch barındırma tümleştirmesi, Elasticsearch kaynağı için otomatik olarak bir sistem durumu denetimi ekler. Sistem durumu denetimi, Elasticsearch örneğinin çalıştığını ve buna bağlantı kurulabileceğini doğrular.

Barındırma tümleştirmesi, AspNetCore.HealthChecks 📦 ve NuGet paketiElasticsearch'ye dayanır.

Client tümleştirme

.NET Aspire Elasticsearch istemci tümleştirmesine başlamak için, istemciyi kullanan uygulamanın projesinde, yani istemci kullanan projede NuGet paketini Elastic.Clients.Elasticsearch yükleyin. Elasticsearch istemci tümleştirmesi, ile etkileşimde bulunurken kullanabileceğiniz bir Elasticsearch örneği kaydeder.

dotnet add package Aspire.Elastic.Clients.Elasticsearch

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

Elasticsearch istemcisi ekle

İstemci kullanan projenizin Program.cs dosyasında, herhangi bir AddElasticsearchClient üzerinde IHostApplicationBuilder uzantı metodunu çağırarak, bağımlılık enjeksiyonu kapsayıcısı aracılığıyla kullanılmak üzere bir ElasticsearchClient kaydedin. yöntemi bir bağlantı adı parametresi alır.

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Daha sonra bağımlılık ekleme kullanarak ElasticsearchClient örneğini alabilirsiniz. Örneğin, bağlantıyı örnek bir hizmetten almak için:

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

Anahtarlı Elasticsearch istemcisi ekleme

Farklı bağlantı adlarına sahip birden çok ElasticsearchClient örneğini kaydetmek istediğiniz durumlar olabilir. Anahtarlı Elasticsearch istemcilerini kaydetmek için AddKeyedElasticsearchClient'i aramanız gerekmektedir.

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

Daha sonra bağımlılık ekleme kullanarak ElasticsearchClient örneklerini alabilirsiniz. Örneğin, bağlantıyı örnek bir hizmetten almak için:

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

Anahtarlı hizmetler hakkında daha fazla bilgi için bkz. .NET bağımlılık ekleme: Anahtarlı hizmetler.

Konfigürasyon

.NET Aspire Elasticsearch istemci tümleştirmesi, sunucu bağlantısını projenizin gereksinimlerine ve kurallarına göre yapılandırmak için birden çok seçenek sağlar.

Bağlantı dizesi kullanma

ConnectionStrings yapılandırma bölümünden bir bağlantı dizesi kullanırken, builder.AddElasticsearchClientçağırırken bağlantı dizesinin adını sağlayabilirsiniz:

builder.AddElasticsearchClient("elasticsearch");

Ardından bağlantı dizesi ConnectionStrings yapılandırma bölümünden alınır:

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

Yapılandırma sağlayıcılarını kullanma

.NET Aspire Elasticsearch Client tümleştirmesi, Microsoft.Extensions.Configuration'ü destekler. Yapılandırmadan ElasticClientsElasticsearchSettings'i Aspire:Elastic:Clients:Elasticsearch anahtarını kullanarak yükler. Seçeneklerden bazılarını yapılandıran aşağıdaki örnek appsettings.json göz önünde bulundurun:

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

Tam Elasticsearch istemci entegrasyonu JSON şeması için bkz. Aspire. Elastic.Clients.Elasticsearch/ConfigurationSchema.json.

Satır içi temsilcileri kullan

Ayrıca Action<ElasticClientsElasticsearchSettings> configureSettings temsilcisini geçirerek satır içi seçeneklerin bazılarını veya tümünü ayarlayabilirsiniz; örneğin koddan API anahtarını ayarlayabilirsiniz:

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

Yapılandırma sağlayıcılarıyla CloudId ve ApiKey kullanma

Elastic Cloud kullanırken, builder.AddElasticsearchClient çağrılırken CloudId ve ApiKey öğelerini Aspire:Elastic:Clients:Elasticsearch bölümünde sağlayabilirsiniz.

builder.AddElasticsearchClient("elasticsearch");

Seçenekleri yapılandıran aşağıdaki örnek appsettings.json göz önünde bulundurun:

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

CloudId ve ApiKey'i satır içi temsilcilerle kullanma

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

Client entegrasyon sağlık kontrolleri

Varsayılan olarak, .NET.NET Aspire tümleştirmeleri tüm hizmetler için sağlık kontrollerini etkinleştirir. Daha fazla bilgi için bkz. .NET.NET Aspire tümleştirmelere genel bakış.

.NET Aspire Elasticsearch tümleştirmesi, bir PingAsync gerçekleştirmek için yapılandırılmış istemciyi kullanır. Sonuç bir HTTP 200 OK ise, sağlık kontrolü sağlıklı kabul edilir, aksi takdirde sağlıksız kabul edilir. Benzer şekilde, bir istisna varsa, sağlık denetimi, sağlık denetimi hatası nedeniyle yayılan bir hatayla sağlıksız kabul edilir.

Gözlemlenebilirlik ve telemetri

.NET .NET Aspire tümleştirmeler, otomatik olarak Günlüğü, İzlemeyi ve Ölçüm yapılandırmalarını ayarlar ki bunlar bazen gözlemlenebilirliğin sütunları olarak bilinir. Tümleştirme gözlemlenebilirliği ve telemetri hakkında daha fazla bilgi için bkz. tümleştirmelere genel bakış. Yedekleme hizmetine bağlı olarak, bazı tümleştirmeler bu özelliklerden yalnızca bazılarını destekleyemeyebilir. Örneğin, bazı tümleştirmeler günlük kaydını ve izlemeyi destekler, ancak ölçümleri desteklemez. Telemetri özellikleri, Yapılandırma bölümünde sunulan teknikler kullanılarak da devre dışı bırakılabilir.

İzleme

.NET Aspire Elasticsearch entegrasyonu, OpenTelemetrykullanarak aşağıdaki izleme etkinliklerini oluşturacak:

• Elastic.Transport

Ayrıca bkz.

• Elasticsearch .NET
• .NET .NET Aspire tümleştirmeleri
• .NET Aspire GitHub repo