integracja z bazą danych .NET AspireMongoDB

Artykuł
12/16/2024

obejmuje:integracja hostingu oraz Client integracja

MongoDB to baza danych NoSQL, która zapewnia wysoką wydajność, wysoką dostępność i łatwą skalowalność. Integracja .NET AspireMongoDB umożliwia łączenie się z istniejącymi wystąpieniami MongoDB (w tym MongoDB Atlas) lub tworzenie nowych wystąpień z .NET przy użyciu obrazu kontenera docker.io/library/mongo

Integracja hostingu

MongoDB server hostowanie modeli integracji server jako typu MongoDBServerResource i bazy danych jako typu MongoDBDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.MongoDB w projekcie hosta aplikacji .

.NET SIP (interfejs wiersza poleceń)
OdwołaniePakietu

dotnet add package Aspire.Hosting.MongoDB

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

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietu w .NET aplikacjach.

Dodawanie zasobu MongoDBserver i zasobu bazy danych

W projekcie hosta aplikacji wywołaj AddMongoDB, aby dodać i zwrócić kreatora zasobów MongoDBserver. Połącz wywołanie zwróconego konstruktora zasobów do AddDatabase, aby dodać zasób bazy danych 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...

Notatka

Kontener MongoDB może być powolny do uruchomienia, dlatego najlepiej użyć trwałego okresu, aby uniknąć niepotrzebnych ponownych uruchomień. Aby uzyskać więcej informacji, zobacz okres istnienia zasobu kontenera.

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem docker.io/library/mongo, tworzy nowe wystąpienie MongoDB na komputerze lokalnym. Odwołanie do konstruktora zasobów MongoDBserver (zmiennej mongo) służy do dodawania bazy danych. Baza danych nosi nazwę mongodb, a następnie jest dodawana do ExampleProject. Zasób MongoDBserver zawiera poświadczenia domyślne:

MONGO_INITDB_ROOT_USERNAME: wartość admin.
MONGO_INITDB_ROOT_PASSWORD: losowe password wygenerowane przy użyciu metody CreateDefaultPasswordParameter.

Po uruchomieniu hosta aplikacji hasło jest przechowywane w magazynie tajnym hosta aplikacji. Jest on dodawany do sekcji Parameters, na przykład:

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

Nazwa parametru jest mongo-password, ale naprawdę wystarczy sformatować nazwę zasobu z sufiksem -password. Aby uzyskać więcej informacji, zobacz Bezpieczne przechowywanie tajnych danych aplikacji w środowisku deweloperskim w ASP.NET Core i Dodaj zasób MongoDBserver z parametrami.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie mongodb, a WaitFor instruuje hosta aplikacji, aby nie uruchamiał usługi zależnej, dopóki zasób mongodb nie będzie gotowy.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym MongoDBserver, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zobacz Odnieś się do istniejących zasobów.

Dodawanie zasobu MongoDBserver z woluminem danych

Aby dodać wolumin danych do zasobu MongoDBserver, wywołaj metodę WithDataVolume w zasobie MongoDBserver:

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

Wolumin danych służy do utrzymywania MongoDBserver danych poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /data/db w kontenerze MongoDBserver, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat wolumenów danych i dlaczego są preferowane od zamontowanych wolumenów , zobacz dokumentację Docker: Wolumeny.

Ostrzeżenie

Hasło jest przechowywane w woluminie danych. W przypadku korzystania z woluminu danych i zmiany hasła nie będzie działać, dopóki wolumin nie zostanie usunięty.

Dodawanie zasobu MongoDBserver z montowaniem wiązania danych

Aby dodać instalację powiązania danych do zasobu MongoDBserver, wywołaj metodę 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...

Ważny

Instalacje powiązane danych mają ograniczoną funkcjonalność w porównaniu z woluminami , co zapewnia lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak punkty montowania za pomocą wiązania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do prac deweloperskich i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Powiązania danych opierają się na systemie plików hosta, aby utrwalić dane MongoDBserver między ponownymi uruchomieniami kontenera. Instalacja powiązania danych jest instalowana w C:\MongoDB\Data w systemie Windows (lub /MongoDB/Data w Unix) ścieżki na maszynie hosta w kontenerze MongoDBserver. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Dodawanie zasobu MongoDBserver z instalacją powiązania danych inicjowania

Aby dodać zamontowanie powiązania danych folderu inicjalizacji do zasobu MongoDBserver, wywołaj metodę 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...

Montowanie powiązania danych inicjalizacyjnych służy do inicjalizacji MongoDBserver z danymi. Powiązanie danych inicjalizacyjnych jest montowane w C:\MongoDB\Init w systemie Windows (lub /MongoDB/Init w Unix) na komputerze hosta w kontenerze MongoDBserver i mapuje do ścieżki /docker-entrypoint-initdb.d w kontenerze MongoDBserver. MongoDB wykonuje skrypty znalezione w tym folderze, co jest przydatne do ładowania danych do bazy danych.

Dodawanie zasobu MongoDBserver z parametrami

Jeśli chcesz jawnie podać hasło używane przez obraz kontenera, możesz podać te poświadczenia w formie parametrów. Rozważmy następujący przykład alternatywny:

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

Aby uzyskać więcej informacji na temat udostępniania parametrów, zobacz Parametry zewnętrzne.

Dodawanie zasobu MongoDB Express

MongoDB Express to internetowy interfejs użytkownika MongoDB administratora. Aby dodać zasób MongoDB Express odpowiadający obrazowi kontenera docker.io/library/mongo-express, wywołaj metodę WithMongoExpress w zasobie MongoDBserver:

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

Napiwek

Aby skonfigurować port hosta dla łańcucha MongoExpressContainerResource, należy wywołać interfejs API WithHostPort i podać żądany numer portu.

Powyższy kod dodaje zasób MongoDB Express skonfigurowany do łączenia się z zasobem MongoDBserver. Poświadczenia domyślne to:

ME_CONFIG_MONGODB_SERVER: nazwa przypisana do nadrzędnego MongoDBServerResource, w tym przypadku będzie to mongo.
ME_CONFIG_BASICAUTH: wartość false.
ME_CONFIG_MONGODB_PORT: przypisano z portu docelowego podstawowego punktu końcowego jednostki nadrzędnej MongoDBServerResource.
ME_CONFIG_MONGODB_ADMINUSERNAME: ta sama nazwa użytkownika, która została skonfigurowana w nadrzędnym MongoDBServerResource.
ME_CONFIG_MONGODB_ADMINPASSWORD: to samo hasło skonfigurowane w nadrzędnym MongoDBServerResource.

Ponadto interfejs API WithMongoExpress uwidacznia opcjonalny parametr configureContainer typu Action<IResourceBuilder<MongoExpressContainerResource>> używany do konfigurowania zasobu kontenera MongoDB Express.

Przeprowadzanie sprawdzania stanu integracji

Integracja hostowania MongoDB automatycznie dodaje kontrolę kondycji zasobu MongoDBserver. Kontrola kondycji sprawdza, czy zasób MongoDBserver jest uruchomiony i czy można nawiązać z nim połączenie.

Integracja hostingu opiera się na pakiecie NuGet 📦 AspNetCore.HealthChecks.MongoDb.

integracja Client

Aby rozpocząć pracę z integracją .NET AspireMongoDBclient, zainstaluj 📦Aspire.MongoDB. Sterownik pakiet NuGet w projekcie korzystającym z client, czyli projektu dla aplikacji korzystającej z MongoDBclient. Integracja MongoDBclient rejestruje instancję IMongoClient, którą można wykorzystać do interakcji z zasobem MongoDBserver. Jeśli host aplikacji dodaje zasoby bazy danych MongoDB, zostanie również zarejestrowane wystąpienie IMongoDatabase.

.NET interfejs wiersza poleceń
PackageReference

dotnet add package Aspire.MongoDB.Driver

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

Dodaj MongoDBclient

W pliku Program.cs projektu korzystającego z clientwywołaj metodę rozszerzenia AddMongoDBClient na dowolnym IHostApplicationBuilder, aby zarejestrować IMongoClient do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddMongoDBClient(connectionName: "mongodb");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu MongoDBserver (lub zasobu bazy danych, jeśli podano) w projekcie hosta aplikacji. Innymi słowy, podczas wywoływania AddDatabase i przekazywania nazwy mongodb, tej samej nazwy należy użyć przy wywoływaniu AddMongoDBClient. Aby uzyskać więcej informacji, zobacz Dodawanie zasobu MongoDBserver i zasobu bazy danych.

Następnie można pobrać instancję IMongoClient, korzystając ze wstrzykiwania zależności. Na przykład, aby pobrać client z przykładowej usługi:

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

IMongoClient służy do interakcji z zasobem MongoDBserver. Może służyć do tworzenia baz danych, które nie są jeszcze znane projektowi hosta aplikacji. Podczas definiowania zasobu bazy danych MongoDB na hoście aplikacji można zamiast tego wymagać, aby kontener wstrzykiwania zależności dostarczał wystąpienie IMongoDatabase. Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET.

Dodaj przypisane klucze MongoDBclient

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień IMongoDatabase z różnymi nazwami połączeń. Aby zarejestrować klientów z kluczem MongoDB, wywołaj metodę AddKeyedMongoDBClient.

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

Ważny

W przypadku korzystania z usług z kluczem należy oczekiwać, że zasób MongoDB będzie skonfigurowany z dwiema nazwanymi bazami danych, jedną dla mainDb i jedną dla loggingDb.

Następnie można pobrać wystąpienia IMongoDatabase przy użyciu wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług z kluczem, zobacz .NET wstrzykiwanie zależności: usługi z kluczem.

Konfiguracja

Integracja z bazą danych .NET AspireMongoDB zapewnia wiele metod konfiguracji i opcji spełniających wymagania i konwencje projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

Parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings. Rozważmy następującą konfigurację przykładu MongoDBJSON:

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

Alternatywnie, rozważmy następujący MongoDB przykład konfiguracji Atlas JSON:

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

Aby uzyskać więcej informacji na temat formatowania tych parametrów połączenia, zobacz MongoDB: ConnectionString documentation.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireMongoDB obsługuje Microsoft.Extensions.Configuration. Ładuje MongoDBSettings z konfiguracji przy użyciu klucza Aspire:MongoDB:Driver. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Korzystanie z wbudowanych konfiguracji

Możesz również przekazać delegata Action<MongoDBSettings>, aby skonfigurować niektóre lub wszystkie opcje wbudowane:

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

Opcje konfiguracji

Poniżej przedstawiono opcje konfigurowalne z odpowiednimi wartościami domyślnymi:

Nazwa	Opis
`ConnectionString`	Parametry połączenia bazy danych MongoDB do nawiązania połączenia.
`DisableHealthChecks`	Wartość logiczna wskazująca, czy sprawdzanie kondycji bazy danych jest wyłączone, czy nie.
`HealthCheckTimeout`	Wartość `int?` wskazująca limit czasu kontroli kondycji MongoDB w milisekundach.
`DisableTracing`	Wartość logiczna wskazująca, czy śledzenie OpenTelemetry jest wyłączone, czy nie.

Kontrole kondycji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Domyślnie integracja .NET AspireMongoDBclient obsługuje następujące scenariusze:

Dodaje test kondycji po włączeniu, który weryfikuje, czy można nawiązać połączenie oraz uruchomić polecenia w bazie danych MongoDB w określonym czasie.
Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane kontrole stanu zdrowia muszą zostać pomyślnie zakończone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Logowanie

Integracja z bazą danych .NET AspireMongoDB korzysta ze standardowego rejestrowania .NET i widzisz wpisy dziennika z następujących kategorii:

MongoDB[.*]: wszelkie wpisy dziennika z przestrzeni nazw MongoDB.

Śledzenie

Integracja bazy danych .NET AspireMongoDB emituje następujące działania śledzenia przy użyciu OpenTelemetry:

MongoDB.Driver.Core.Extensions.DiagnosticSources

Wskaźniki

Integracja .NET AspireMongoDB z bazą danych nie uwidacznia obecnie żadnych metryk OpenTelemetry.

Udostępnij za pośrednictwem

integracja z bazą danych .NET AspireMongoDB

Integracja hostingu

Dodawanie zasobu MongoDBserver i zasobu bazy danych

Dodawanie zasobu MongoDBserver z woluminem danych

Dodawanie zasobu MongoDBserver z montowaniem wiązania danych

Dodawanie zasobu MongoDBserver z instalacją powiązania danych inicjowania

Dodawanie zasobu MongoDBserver z parametrami

Dodawanie zasobu MongoDB Express

Przeprowadzanie sprawdzania stanu integracji

integracja Client

Dodaj MongoDBclient

Dodaj przypisane klucze MongoDBclient

Konfiguracja

Używanie parametrów połączenia

Korzystanie z dostawców konfiguracji

Korzystanie z wbudowanych konfiguracji

Opcje konfiguracji

Kontrole kondycji

Obserwowanie i telemetria

Logowanie

Śledzenie

Wskaźniki

Zobacz też

Dodatkowe zasoby