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
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...
Nota
Kontainer MongoDB bisa lambat untuk memulai, jadi yang terbaik adalah menggunakan dengan masa pakai persisten untuk dapat menghindari restart yang tidak perlu. Untuk informasi selengkapnya, lihat masa pakai sumber daya Kontainer.
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
: Nilaiadmin
. -
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.
Saran
Jika Anda lebih suka menyambungkan ke server MongoDB yang sudah ada, panggil AddConnectionString sebagai gantinya. Untuk informasi selengkapnya, lihat sumber daya yang ada .
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.
Peringatan
Kata sandi disimpan dalam volume data. Saat menggunakan volume data dan jika kata sandi berubah, itu tidak akan berfungsi sampai Anda menghapus volume.
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...
Penting
Bind mount data memiliki fungsionalitas terbatas dibandingkan dengan volume , yang menawarkan performa, portabilitas, dan keamanan yang lebih baik, sehingga lebih cocok untuk lingkungan produksi. Namun, bind mount memungkinkan akses langsung dan modifikasi file pada sistem host, yang ideal untuk pengembangan dan pengujian di mana perubahan secara real-time diperlukan.
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...
Saran
Untuk mengonfigurasi port host untuk rantai MongoExpressContainerResource dengan panggilan ke API WithHostPort, dan berikan nomor port yang diinginkan.
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 indukMongoDBServerResource
, dalam hal ini akan menjadimongo
. -
ME_CONFIG_BASICAUTH
: Nilaifalse
. -
ME_CONFIG_MONGODB_PORT
: Ditetapkan dari port target dari titik akhir utama indukMongoDBServerResource
. -
ME_CONFIG_MONGODB_ADMINUSERNAME
: Nama pengguna yang sama seperti yang dikonfigurasi diMongoDBServerResource
induk . -
ME_CONFIG_MONGODB_ADMINPASSWORD
: Kata sandi yang sama seperti yang dikonfigurasi diMongoDBServerResource
induk .
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
dotnet add package Aspire.MongoDB.Driver
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");
Saran
Parameter connectionName
harus cocok dengan nama yang digunakan saat menambahkan sumber daya server MongoDB (atau sumber daya database saat disediakan) dalam proyek host aplikasi. Dengan kata lain, ketika Anda memanggil AddDatabase
dan memberikan nama mongodb
nama yang sama harus digunakan saat memanggil AddMongoDBClient
. Untuk informasi selengkapnya, lihat Menambahkan sumber daya server MongoDB dan sumber daya database.
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");
Penting
Saat menggunakan layanan dengan kunci, diharapkan sumber daya MongoDB Anda mengonfigurasi dua database bernama, satu untuk mainDb
dan satu untuk 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:
Nama | Deskripsi |
---|---|
ConnectionString |
String koneksi dari database MongoDB yang akan dihubungkan. |
DisableHealthChecks |
Nilai boolean yang menunjukkan apakah pemeriksaan kesehatan database dinonaktifkan atau tidak. |
HealthCheckTimeout |
Nilai int? yang menunjukkan batas waktu pemeriksaan kesehatan MongoDB dalam milidetik. |
DisableTracing |
Nilai boolean yang menunjukkan apakah pelacakan OpenTelemetry dinonaktifkan atau tidak. |
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
.NET Aspire