integracja z bazą danych .NET AspireMongoDB

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

Serwer integracyjny MongoDB jest modelowany jako typ MongoDBServerResource, a baza danych jako typ MongoDBDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.MongoDB w projekcie hosta aplikacji .

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 serwera MongoDB i zasobu bazy danych

W projekcie hosta aplikacji wywołaj AddMongoDB, aby dodać i zwrócić konstruktor zasobów serwera MongoDB. 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...

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 serwera MongoDB (zmiennej mongo) służy do dodawania bazy danych. Baza danych nosi nazwę mongodb, a następnie jest dodawana do ExampleProject. Zasób serwera MongoDB 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 tworzeniu w ASP.NET Core oraz Dodaj zasób serwera MongoDB 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.

Dodaj zasób serwera MongoDB z woluminem danych

Aby dodać wolumin danych do zasobu serwera MongoDB, wywołaj metodę WithDataVolume w zasobie serwera 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...

Wolumin danych jest używany do utrwalania danych serwera MongoDB poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /data/db w kontenerze serwera MongoDB, 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.

Dodaj zasób serwera MongoDB z montowaniem danych za pomocą powiązania

Aby dodać powiązanie danych do zasobu serwera MongoDB, 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...

Montaże powiązań danych polegają na systemie plików maszyny hosta do utrwalania danych serwera MongoDB podczas ponownych uruchomień kontenera. Powiązanie danych jest montowane na C:\MongoDB\Data w systemie Windows (lub na /MongoDB/Data na Unix) na ścieżce maszyny hosta w kontenerze serwera MongoDB. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Dodaj zasób serwera MongoDB z montowaniem danych inicjalizacji

Aby dodać montowanie powiązania danych folderu inicjalizacji do zasobu serwera MongoDB, 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...

Powiązanie montowania danych inicjalizacji służy do inicjalizacji serwera MongoDB z wykorzystaniem danych. Powiązanie danych inicjalizacyjnych jest montowane na ścieżce C:\MongoDB\Init w systemie Windows (lub /MongoDB/Init w Unix) na maszynie hosta, w kontenerze serwera MongoDB, i odwzorowuje na ścieżkę /docker-entrypoint-initdb.d w kontenerze serwera MongoDB. MongoDB wykonuje skrypty znalezione w tym folderze, co jest przydatne do ładowania danych do bazy danych.

Dodawanie zasobu serwera MongoDB 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 serwera 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...

Powyższy kod dodaje zasób MongoDB Express skonfigurowany do łączenia się z zasobem serwera MongoDB. 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 serwera MongoDB. Sprawdzanie kondycji sprawdza, czy zasób serwera MongoDB 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ą klienta .NET AspireMongoDB, zainstaluj pakiet NuGet 📦Aspire.MongoDB.Driver w projekcie konsumpcyjnym klienta, czyli projekt aplikacji korzystającej z klienta MongoDB. Integracja klienta MongoDB rejestruje instancję IMongoClient, której można użyć, aby połączyć się z zasobem serwera MongoDB. Jeśli host aplikacji dodaje zasoby bazy danych MongoDB, zostanie również zarejestrowane wystąpienie IMongoDatabase.

dotnet add package Aspire.MongoDB.Driver

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

Dodaj klienta MongoDB

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

builder.AddMongoDBClient(connectionName: "mongodb");

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

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

IMongoClient służy do interakcji z zasobem serwera MongoDB. 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 klienta MongoDB z kluczem

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");

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:

Client kontrole stanu integracji

Domyślnie .NET.NET Aspireintegracje klienta mają kontrole stanu włączone dla wszystkich usług. Podobnie wiele .NET.NET Aspirehostowanie integracji również włączyć punkty końcowe sprawdzania kondycji. Aby uzyskać więcej informacji, zobacz:

• .NET sprawdzanie kondycji aplikacji w języku C#
• kontrole kondycji w ASP.NET Core

Domyślnie integracja klienta .NET AspireMongoDB 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.

Zobacz też

• MongoDB bazy danych
• .NET .NET Aspire integracji
• .NET Aspire GitHub repozytorium