Aracılığıyla paylaş


.NET Aspire MongoDB veritabanı tümleştirmesi

Şunları içerir:Barındırma tümleştirmesi ve Client tümleştirme

MongoDB yüksek performans, yüksek kullanılabilirlik ve kolay ölçeklenebilirlik sağlayan bir NoSQL veritabanıdır. .NET Aspire MongoDB tümleştirmesi, mevcut MongoDB örneklerine (MongoDB Atlasdahil) bağlanmanızı veya docker.io/library/mongo ile yeni örnekler oluşturmanızı sağlar

Barındırma tümleştirmesi

MongoDB sunucusu barındırma tümleştirmesi, sunucuyu MongoDBServerResource türü olarak ve veritabanını MongoDBDatabaseResource türü olarak modeller. Bu türlere ve API'lere erişmek için 📦Aspire.Hosting.MongoDB NuGet paketini uygulama konağı projesine ekleyin.

dotnet add package Aspire.Hosting.MongoDB

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

MongoDB sunucu kaynağı ve veritabanı kaynağı ekleme

Uygulama ana bilgisayar projenizde AddMongoDB'ı çağırarak MongoDB sunucu kaynak oluşturucusunu ekleyip geri döndürün. AddDatabase veritabanı kaynağı eklemek için döndürülen kaynak oluşturucusuna ait çağrıları MongoDBile zincirleyin.

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithLifetime(ContainerLifetime.Persistent);

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Not

MongoDB kapsayıcısı yavaş başlatılabilir, bu nedenle gereksiz yeniden başlatmaları önlemek için kalıcı ömrü kullanmak en iyisidir. Daha fazla bilgi için bkz. kapsayıcı kaynak ömrü.

.NET .NET Aspire, önceki örnekte docker.io/library/mongo 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 MongoDB örneği oluşturur. Veritabanı eklemek için MongoDB sunucu kaynak oluşturucunuza (mongo değişkeni) başvuru kullanılır. Veritabanı mongodb olarak adlandırılır ve ardından ExampleProject'e eklenir. MongoDB sunucusu kaynağı varsayılan kimlik bilgilerini içerir:

  • MONGO_INITDB_ROOT_USERNAME: admindeğeri.
  • MONGO_INITDB_ROOT_PASSWORD: password yöntemi kullanılarak oluşturulan rastgele CreateDefaultPasswordParameter.

Uygulama ana bilgisayarı çalıştırıldığında, parola uygulama ana bilgisayarının gizli deposunda depolanır. Bu, örneğin Parameters bölümüne eklenmiştir:

{
  "Parameters:mongo-password": "<THE_GENERATED_PASSWORD>"
}

Parametrenin adı mongo-password, fakat aslında sadece kaynak adını bir -password sonekiyle biçimlendirmektir. Daha fazla bilgi için bkz. Geliştirme aşamasında uygulama sırlarının güvenli bir şekilde depolanması ASP.NET Core, ve parametreleriyle MongoDB sunucu kaynağı ekleme.

WithReference yöntemi, ExampleProject adlı bir mongodb bağlantısını yapılandırıyor ve WaitFor, uygulama konağına, mongodb kaynağı hazır olana kadar bağımlı hizmeti başlatmamasını söylüyor.

Bahşiş

Mevcut bir MongoDB sunucusuna bağlanmak isterseniz bunun yerine AddConnectionString'ı arayın. Daha fazla bilgi için bkz. Var olan kaynaklara başvurma.

Veri birimi ile MongoDB sunucu kaynağı ekleme

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

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataVolume();

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Veri hacmi, MongoDB sunucu verilerini kapsayıcısının yaşam döngüsü dışında kalıcı hale getirmek için kullanılır. Veri birimi, MongoDB sunucu kapsayıcısında /data/db yoluna bağlanır ve name parametresi sağlanmazsa ad rastgele oluşturulur. Veri birimleri hakkında daha fazla bilgi edinmek vebağlamaları neden tercih edildiklerine ilişkin ayrıntılar için bkz. belgeler: Birimler.

Uyarı

Parola, veri biriminde depolanır. Veri birimi kullanılırken parola değişirse, birimi silene kadar çalışmayacaktır.

Veri bağlama yuvası ile MongoDB sunucu kaynağı ekleme

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

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataBindMount(@"C:\MongoDB\Data");

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Önemli

Veri bağlama bağlamaları, daha iyi performans, taşınabilirlik ve güvenlik sunanbirimleriyle karşılaştırıldığında sınırlı işlevselliğe sahiptir ve bu da üretim ortamları için daha uygun olmasını sağlar. Ancak bağlamalar, gerçek zamanlı değişikliklerin gerekli olduğu geliştirme ve test için ideal olan ana sistemdeki dosyaların doğrudan erişimine ve değiştirilmesine olanak sağlar.

Veri bağlama yerleştirmeleri, kapsayıcı yeniden başlatmaları arasında MongoDB sunucu verilerini kalıcı olarak saklamak için ana makinenin dosya sistemini kullanır. Veri bağlaması, MongoDB sunucu kapsayıcısında konak makinedeki Windows üzerindeki C:\MongoDB\Data (veya Unix/MongoDB/Data) yoluna bağlanır. Veri bağlama noktaları hakkında daha fazla bilgi için bkz. Docker dokümantasyon: Bağlama noktaları.

Başlatma veri bağlama bağlaması ile MongoDB sunucu kaynağı ekleme

MongoDB sunucu kaynağına bir başlangıç klasörü veri bağlama eklemek için WithInitBindMount yöntemini çağırın.

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithInitBindMount(@"C:\MongoDB\Init");

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Başlatma veri bağlama noktası, MongoDB sunucusunu verilerle başlatmak amacıyla kullanılır. Başlatma verisi bağlama montajı, MongoDB sunucu kapsayıcısındaki konak makinede Windows'un C:\MongoDB\Init yoluna (veya Unixüzerindeki /MongoDB/Init yoluna) monte edilir ve MongoDB sunucu kapsayıcısında /docker-entrypoint-initdb.d yoluna eşlenir. MongoDB bu klasörde bulunan betikleri yürütür ve bu da verileri veritabanına yüklemek için kullanışlıdır.

Parametrelerle MongoDB sunucu 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 username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var mongo = builder.AddMongoDB("mongo", username, password);
var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Parametre sağlamaya yönelik daha fazla bilgi için bkz. Dış parametreler.

MongoDB Express kaynağı ekleme

MongoDB Express, web tabanlı MongoDB yönetici kullanıcı arabirimidir. kapsayıcı görüntüsüne karşılık gelen bir Express kaynağı eklemek için sunucu kaynağında yöntemini çağırın:

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithMongoExpress();

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

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

Bahşiş

MongoExpressContainerResource zinciri için konak bağlantı noktasını yapılandırmak için WithHostPort API'sine bir çağrı yapın ve istenen bağlantı noktası numarasını sağlayın.

Yukarıdaki kod, MongoDB sunucu kaynağına bağlanmak için yapılandırılmış bir MongoDB Express kaynağı ekler. Varsayılan kimlik bilgileri şunlardır:

  • ME_CONFIG_MONGODB_SERVER: Üst MongoDBServerResourceiçin atanan ad, bu durumda mongoolacaktır.
  • ME_CONFIG_BASICAUTH: falsedeğeri.
  • ME_CONFIG_MONGODB_PORT: Birincil uç noktanın üst MongoDBServerResourcehedef bağlantı noktasından atanır.
  • ME_CONFIG_MONGODB_ADMINUSERNAME: MongoDBServerResource'de yapılandırılan kullanıcı adıyla aynı kullanıcı adıdır.
  • ME_CONFIG_MONGODB_ADMINPASSWORD: Ebeveyn MongoDBServerResource'de yapılandırılan parolanın aynısı.

Ayrıca, WithMongoExpress API'sinde configureContainer Express kapsayıcı kaynağını yapılandırmak için kullandığınız Action<IResourceBuilder<MongoExpressContainerResource>> türündeki isteğe bağlı bir MongoDB parametresi gösterilir.

Barındırma entegrasyonu sağlık kontrolleri

MongoDB barındırma tümleştirmesi, MongoDB sunucu kaynağı için otomatik olarak bir sistem durumu denetimi ekler. Sistem durumu denetimi, MongoDB sunucu kaynağının çalıştığını ve bu kaynakla bağlantı kurulabileceğini doğrular.

Barındırma tümleştirmesi, 📦 AspNetCore.HealthChecks.MongoDb NuGet paketine dayanır.

Client tümleştirmesi

.NET Aspire MongoDB istemci entegrasyonuna başlamak için, 📦Aspire.MongoDB.Driver NuGet paketini istemciyi kullanan projeye, yani MongoDB istemcisini kullanan uygulamanın projesine yükleyin. MongoDB istemci tümleştirmesi, MongoDB sunucu kaynağıyla etkileşimde bulunurken kullanabileceğiniz bir IMongoClient örneği kaydeder. Uygulama konağınız MongoDB veritabanı kaynağı eklerse IMongoDatabase örneği de kaydedilir.

dotnet add package Aspire.MongoDB.Driver

MongoDB müşterisi ekle

İstemci kullanan projenizin Program.cs dosyasındaki herhangi bir IHostApplicationBuilder üzerinde AddMongoDBClient genişletme yöntemini çağırarak bağımlılık enjeksiyonu kapsayıcısı aracılığıyla kullanılmak üzere bir IMongoClient kaydedin. yöntemi bir bağlantı adı parametresi alır.

builder.AddMongoDBClient(connectionName: "mongodb");

Bahşiş

connectionName parametresi, uygulama ana bilgisayar projesinde MongoDB sunucu kaynağını (veya sağlandığında veritabanı kaynağını) eklerken kullanılan adla eşleşmelidir. Başka bir deyişle, AddDatabase çağırdığınızda ve mongodbçağrılırken, AddMongoDBClient adını sağladığınız aynı ad kullanılmalıdır. Daha fazla bilgi için bkz. MongoDB sunucu kaynağı veveritabanı kaynağı ekleme.

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

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

IMongoClient, MongoDB sunucu kaynağıyla etkileşime geçmek için kullanılır. Uygulama barındırma projesi tarafından önceden bilinmeyen veritabanları oluşturmak için kullanılabilir. Uygulama konağınızda bir MongoDB veritabanı kaynağı tanımladığınızda bunun yerine bağımlılık ekleme kapsayıcısının IMongoDatabase bir örnek sağlamasını zorunlu kılabilirsiniz. Bağımlılık ekleme hakkında daha fazla bilgi için bkz. .NET bağımlılık ekleme.

Anahtarlı MongoDB istemcisi ekleme

Farklı bağlantı adlarına sahip birden çok IMongoDatabase örneğini kaydetmek istediğiniz durumlar olabilir. Anahtarlı MongoDB istemcilerini kaydetmek için AddKeyedMongoDBClient yöntemini çağırın:

builder.AddKeyedMongoDBClient(name: "mainDb");
builder.AddKeyedMongoDBClient(name: "loggingDb");

Önemli

Anahtarlı hizmetleri kullanırken, MongoDB kaynağınızın biri mainDb ve biri loggingDbolarak adlandırılmış iki veritabanını yapılandırması beklenir.

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

public class ExampleService(
    [FromKeyedServices("mainDb")] IMongoDatabase mainDatabase,
    [FromKeyedServices("loggingDb")] IMongoDatabase loggingDatabase)
{
    // Use databases...
}

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

Konfigürasyon

.NET Aspire MongoDB veritabanı tümleştirmesi, projenizin gereksinimlerini ve kurallarını karşılamak için birden çok yapılandırma yaklaşımı ve seçeneği sağlar.

Bağlantı dizesi kullanma

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

builder.AddMongoDBClient("mongo");

Bağlantı dizesi ConnectionStrings yapılandırma bölümünden alınır. Aşağıdaki MongoDB örnek JSON yapılandırmayı göz önünde bulundurun:

{
  "ConnectionStrings": {
    "mongo": "mongodb://server:port/test",
  }
}

Alternatif olarak, aşağıdaki Atlas MongoDB örneği JSON konfigürasyonunu göz önünde bulundurun.

{
  "ConnectionStrings": {
    "mongo": "mongodb+srv://username:password@server.mongodb.net/",
  }
}

Bu bağlantı dizesini biçimlendirme hakkında daha fazla bilgi için bkz. MongoDB: ConnectionString belgeleri.

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

.NET Aspire MongoDB tümleştirmesi Microsoft.Extensions.Configurationdestekler. Yapılandırmadan MongoDBSettings'ı, Aspire:MongoDB:Driver anahtarını kullanarak yükler. Aşağıdaki kod parçacığı, bazı seçenekleri yapılandıran bir appsettings.json dosyası örneğidir:

{
  "Aspire": {
    "MongoDB": {
      "Driver": {
        "ConnectionString": "mongodb://server:port/test",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      },
    }
  }

Satır içi yapılandırmaları kullanma

Satır içi seçeneklerin bazılarını veya tümünü ayarlamak için Action<MongoDBSettings> temsilcisini de geçirebilirsiniz:

builder.AddMongoDBClient("mongodb",
    static settings => settings.ConnectionString = "mongodb://server:port/test");

Yapılandırma seçenekleri

buna karşılık gelen varsayılan değerlere sahip yapılandırılabilir seçenekler şunlardır:

Ad Açıklama
ConnectionString Bağlanılacak MongoDB veritabanının bağlantı dizesi.
DisableHealthChecks Veritabanı sistem durumu denetiminin devre dışı bırakılıp bırakılmadığını gösteren boole değeri.
HealthCheckTimeout int? sistem durumu denetim zaman aşımını milisaniye cinsinden gösteren bir MongoDB değeri.
DisableTracing OpenTelemetry izlemenin devre dışı bırakılıp bırakılmadığını belirten boolean değeri.

Sağlık kontrolleri

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

varsayılan olarak, .NET AspireMongoDB istemci tümleştirmesi aşağıdaki senaryoları işler:

  • Etkinleştirildiğinde, belirli bir süre içinde MongoDB veritabanına bağlantı yapılabildiğini ve komutların çalıştırılabildiğini doğrulayan bir sağlık kontrolü ekler.
  • Uygulamanın trafiği kabul etmeye hazır olarak kabul edilmesi için tüm kayıtlı sistem durumu denetimlerinin geçmesi gerektiğini belirten /health HTTP uç noktasıyla tümleşir

Gözlemlenebilirlik ve telemetri

tümleştirmeleri, bazen gözlemlenebilirliğindayanakları olarak bilinen Loglama, Takip Etme ve Metrikler yapılandırmalarını otomatik olarak ayarlar. 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ı entegrasyonlar günlüğe kaydetmeyi 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.

Kayıt tutma

.NET Aspire MongoDB veritabanı tümleştirmesi standart .NET günlüğü kullanır ve aşağıdaki kategorilerdeki günlük girdilerini görürsünüz:

  • MongoDB[.*]: MongoDB ad alanından tüm günlük girdileri.

İzleme

.NET Aspire MongoDB veritabanı tümleştirmesi, OpenTelemetrykullanarak aşağıdaki İzleme aktivitelerini yayar:

  • MongoDB.Driver.Core.Extensions.DiagnosticSources

Ölçüm

.NET Aspire MongoDB veritabanı tümleştirmesi şu anda hiçbir OpenTelemetry ölçümünü kullanılabilir hale getirmemektedir.

Ayrıca bkz.