integrasi database .NET AspireMongoDB

Meliputi:integrasi Hosting dan Client integrasi

MongoDB adalah database NoSQL yang memberikan performa tinggi, ketersediaan tinggi, dan skalabilitas yang mudah. Integrasi .NET AspireMongoDB memungkinkan Anda terhubung ke instans MongoDB yang ada (termasuk MongoDB Atlas) atau membuat instans baru dari .NET dengan gambar kontainer docker.io/library/mongo

Integrasi hosting

Integrasi hosting server MongoDB memodelkan server sebagai jenis MongoDBServerResource dan database sebagai jenis MongoDBDatabaseResource. Untuk mengakses jenis dan API ini, tambahkan paket NuGet 📦Aspire.Hosting.MongoDB di proyek host aplikasi .

dotnet add package Aspire.Hosting.MongoDB

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

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket di aplikasi .NET.

Menambahkan sumber daya server MongoDB dan sumber daya database

Di proyek host aplikasi Anda, panggil AddMongoDB untuk menambahkan dan mengembalikan pembangun sumber daya server MongoDB. Sambungkan panggilan ke resource builder yang dikembalikan ke AddDatabase, kemudian tambahkan resource database MongoDB.

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

Saat .NET.NET Aspire menambahkan gambar kontainer ke host aplikasi, seperti yang ditunjukkan dalam contoh sebelumnya dengan gambar docker.io/library/mongo, gambar tersebut membuat instans MongoDB baru di komputer lokal Anda. Referensi ke penyusun sumber daya server MongoDB Anda (variabel mongo) digunakan untuk menambahkan database. Database diberi nama mongodb lalu ditambahkan ke ExampleProject. Sumber daya server MongoDB menyertakan kredensial default:

• MONGO_INITDB_ROOT_USERNAME: Nilai admin.
• MONGO_INITDB_ROOT_PASSWORD: password acak yang dihasilkan menggunakan metode CreateDefaultPasswordParameter.

Saat host aplikasi berjalan, kata sandi disimpan di penyimpanan rahasia host aplikasi. Penambahan dilakukan ke bagian Parameters, misalnya:

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

Nama parameter adalah mongo-password, tetapi sebenarnya itu hanya memformat nama resource dengan akhiran -password. Untuk informasi lebih lanjut, lihat penyimpanan aman rahasia aplikasi saat pengembangan di ASP.NET Core dan tambahkan sumber daya server MongoDB dengan parameter.

Metode WithReference mengonfigurasi koneksi di ExampleProject bernama mongodb dan WaitFor menginstruksikan host aplikasi untuk tidak memulai layanan dependen sampai sumber daya mongodb siap.

Tambahkan sumber daya server MongoDB dengan volume data

Untuk menambahkan volume data ke sumber daya server MongoDB, panggil metode WithDataVolume pada sumber daya server MongoDB:

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

Volume data digunakan untuk mempertahankan data server MongoDB di luar siklus hidup kontainernya. Volume data dipasang di jalur /data/db di kontainer server MongoDB dan ketika parameter name tidak disediakan, nama dihasilkan secara acak. Untuk informasi lebih lanjut tentang volume data dan detail mengapa mereka lebih disukai dibandingkan mount bind , lihat dokumen Docker: Volumes.

Menambahkan sumber daya server MongoDB dengan pemasangan ikatan data

Untuk menambahkan pemasangan ikatan data ke sumber daya server MongoDB, panggil metode WithDataBindMount:

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

Pemasangan bind data mengandalkan sistem berkas pada mesin host untuk menyimpan data server MongoDB setiap kali kontainer di-restart. "Data bind mount dipasang di C:\MongoDB\Data pada jalur Windows (atau /MongoDB/Data di Unix) pada komputer host dalam kontainer server MongoDB." Untuk informasi selengkapnya tentang pemasangan ikatan data, lihat dokumen Docker: Pemasangan ikatan.

Menambahkan sumber daya server MongoDB dengan pemasangan ikatan data inisialisasi

Untuk menambahkan ikatan data folder inisialisasi ke sumber daya server MongoDB, panggil metode WithInitBindMount:

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

Pemasangan pengikatan data inisialisasi digunakan untuk menginisialisasi server MongoDB dengan data. Pengikatan data inisialisasi dilakukan di jalur C:\MongoDB\Init pada Windows (atau /MongoDB/Init di Unix) pada komputer host di kontainer server MongoDB dan dipetakan ke jalur /docker-entrypoint-initdb.d di kontainer server MongoDB. MongoDB menjalankan skrip yang ditemukan di folder ini, yang berguna untuk memuat data ke dalam database.

Menambahkan sumber daya server MongoDB dengan parameter

Ketika Anda ingin secara eksplisit memberikan kata sandi yang digunakan oleh gambar kontainer, Anda dapat memberikan kredensial ini sebagai parameter. Pertimbangkan contoh alternatif berikut:

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

Untuk informasi selengkapnya tentang menyediakan parameter, lihat Parameter eksternal.

Menambahkan sumber daya MongoDB Express

MongoDB Express adalah antarmuka pengguna admin MongoDB berbasis web. Untuk menambahkan sumber daya MongoDB Express yang sesuai dengan gambar kontainer docker.io/library/mongo-express, panggil metode WithMongoExpress pada sumber daya server MongoDB:

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

Kode sebelumnya menambahkan sumber daya MongoDB Express yang dikonfigurasi untuk terhubung ke sumber daya server MongoDB. Kredensial default adalah:

• ME_CONFIG_MONGODB_SERVER: Nama yang diberikan kepada induk MongoDBServerResource, dalam hal ini akan menjadi mongo.
• ME_CONFIG_BASICAUTH: Nilai false.
• ME_CONFIG_MONGODB_PORT: Ditetapkan dari port target dari titik akhir utama induk MongoDBServerResource.
• ME_CONFIG_MONGODB_ADMINUSERNAME: Nama pengguna yang sama seperti yang dikonfigurasi di MongoDBServerResourceinduk .
• ME_CONFIG_MONGODB_ADMINPASSWORD: Kata sandi yang sama seperti yang dikonfigurasi di MongoDBServerResourceinduk .

Selain itu, API WithMongoExpress mengekspos parameter configureContainer opsional jenis Action<IResourceBuilder<MongoExpressContainerResource>> yang Anda gunakan untuk mengonfigurasi sumber daya kontainer MongoDB Express.

Pemeriksaan kesehatan integrasi pada hosting

Integrasi hosting MongoDB secara otomatis menambahkan pemeriksaan kesehatan untuk sumber daya server MongoDB. Pemeriksaan kesehatan memverifikasi bahwa sumber daya server MongoDB berjalan dan bahwa koneksi dapat dibuat untuknya.

Integrasi hosting bergantung pada paket 📦 AspNetCore.HealthChecks.MongoDb NuGet.

Client integrasi

Untuk mulai menggunakan integrasi klien , instal paket NuGet Driver untuk .dalam proyek yang menggunakan klien, yaitu proyek untuk aplikasi yang menggunakan klien . Integrasi klien mendaftarkan instans IMongoClient yang dapat Anda gunakan untuk berinteraksi dengan sumber daya server . Jika host aplikasi Anda menambahkan sumber daya database , instans IMongoDatabase juga terdaftar.

dotnet add package Aspire.MongoDB.Driver

<PackageReference Include="Aspire.MongoDB.Driver"
                  Version="*" />

Menambahkan klien MongoDB

Dalam file Program.cs proyek klien Anda yang memanfaatkan, panggil metode ekstensi AddMongoDBClient pada IHostApplicationBuilder apa pun untuk mendaftarkan IMongoClient untuk digunakan melalui wadah injeksi ketergantungan. Metode ini mengambil parameter nama koneksi.

builder.AddMongoDBClient(connectionName: "mongodb");

Anda kemudian dapat mengambil instans IMongoClient menggunakan injeksi dependensi. Misalnya, untuk mengambil klien dari layanan contoh:

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

IMongoClient digunakan untuk berinteraksi dengan sumber daya server MongoDB. Ini dapat digunakan untuk membuat database yang belum diketahui oleh proyek host aplikasi. Saat Anda menentukan sumber daya database MongoDB di host aplikasi, Anda dapat mengharuskan kontainer injeksi dependensi menyediakan instans IMongoDatabase. Untuk informasi selengkapnya tentang injeksi dependensi, lihat .NET injeksi dependensi.

Menambahkan klien MongoDB yang berkode

Mungkin ada situasi di mana Anda ingin mendaftarkan beberapa instans IMongoDatabase dengan nama koneksi yang berbeda. Untuk mendaftarkan klien dengan kunci MongoDB, panggil metode bernama AddKeyedMongoDBClient:

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

Selanjutnya, Anda dapat mengambil instans IMongoDatabase melalui injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

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

Untuk informasi selengkapnya tentang layanan berpenanda kunci, lihat .NET injeksi dependensi: Layanan berpenanda kunci.

Konfigurasi

Integrasi database .NET AspireMongoDB menyediakan beberapa pendekatan dan opsi konfigurasi untuk memenuhi persyaratan dan konvensi proyek Anda.

Menggunakan string koneksi

Saat menggunakan string koneksi dari bagian konfigurasi ConnectionStrings, Anda dapat memberikan nama string koneksi saat memanggil builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

String koneksi diambil dari bagian konfigurasi ConnectionStrings. Pertimbangkan contoh MongoDB konfigurasi JSON berikut:

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

Atau, pertimbangkan konfigurasi contoh Atlas MongoDB berikut ini: JSON

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

Untuk informasi selengkapnya tentang cara memformat string koneksi ini, lihat MongoDB: Dokumentasi ConnectionString.

Menggunakan penyedia konfigurasi

Integrasi .NET AspireMongoDB mendukung Microsoft.Extensions.Configuration. Ini memuat MongoDBSettings dari konfigurasi dengan menggunakan kunci Aspire:MongoDB:Driver. Cuplikan berikut adalah contoh file appsettings.json yang mengonfigurasi beberapa opsi:

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

Menggunakan konfigurasi sebaris

Anda juga dapat meneruskan delegasi Action<MongoDBSettings> untuk menyiapkan beberapa atau semua opsi secara langsung.

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

Opsi konfigurasi

Berikut adalah opsi yang dapat dikonfigurasi dengan nilai default yang sesuai:

Pemeriksaan kesehatan

Secara default, integrasi .NET.NET Aspire memungkinkan pemeriksaan kesehatan untuk semua layanan. Untuk informasi selengkapnya, lihat gambaran umum integrasi .NET.NET Aspire.

Secara default, integrasi klien .NET AspireMongoDB menangani skenario berikut:

• Menambahkan pemeriksaan kesehatan yang, saat diaktifkan, memverifikasi bahwa koneksi dapat dibuat dan perintah dapat dijalankan terhadap database MongoDB dalam batas waktu tertentu.
• Terintegrasi dengan titik akhir HTTP /health, yang menentukan semua pemeriksaan kesehatan terdaftar harus lulus agar aplikasi dianggap siap menerima lalu lintas

Pengamatan dan telemetri

.NET .NET Aspire integrasi secara otomatis menyiapkan konfigurasi Pengelogan, Pelacakan, dan Metrik, yang terkadang dikenal sebagai pilar pengamatan. Untuk informasi selengkapnya tentang pengamatan integrasi dan telemetri, lihat gambaran umum integrasi .NET.NET Aspire. Bergantung pada layanan pendukung, beberapa integrasi mungkin hanya mendukung beberapa fitur ini. Misalnya, beberapa integrasi mendukung pengelogan dan pelacakan, tetapi bukan metrik. Fitur telemetri juga dapat dinonaktifkan menggunakan teknik yang disajikan di bagian Konfigurasi .

Penebangan

Integrasi database .NET AspireMongoDB menggunakan pengelogan .NET standar, dan Anda melihat entri log dari kategori berikut:

• MongoDB[.*]: Entri log apa pun dari namespace MongoDB.

Menelusuri

Integrasi database .NET AspireMongoDB memancarkan aktivitas Pelacakan berikut menggunakan OpenTelemetry:

• MongoDB.Driver.Core.Extensions.DiagnosticSources

Metrik

Integrasi database .NET AspireMongoDB saat ini tidak mengekspos metrik OpenTelemetry apa pun.

Lihat juga

• MongoDB basis data
• .NET .NET Aspire integrasi
• .NET Aspire GitHub repositori