.NET Aspire MongoDB 데이터베이스 통합

포함:호스팅 통합 및 Client 통합

MongoDB 고성능, 고가용성 및 간편한 확장성을 제공하는 NoSQL 데이터베이스입니다. .NET Aspire MongoDB 통합을 사용하면 기존 MongoDB 인스턴스(MongoDB Atlas포함)에 연결하거나 .NET 컨테이너 이미지를 사용하여 docker.io/library/mongo 새 인스턴스를 만들 수

호스팅 통합

통합을 호스팅하는 MongoDB 서버는 서버를 MongoDBServerResource 형식으로, 데이터베이스를 MongoDBDatabaseResource 형식으로 모델화합니다. 이러한 형식 및 API에 액세스하려면 📦 프로젝트에서 AspireMongoDB.Hosting. NuGet 패키지를 추가합니다.

dotnet add package Aspire.Hosting.MongoDB

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

자세한 내용은 dotnet add package 또는 .NET 애플리케이션에서 패키지 종속성 관리하기를 참조하십시오.

MongoDB 서버 리소스 및 데이터베이스 리소스 추가

앱 호스트 프로젝트에서 AddMongoDB 호출하여 MongoDB 서버 리소스 작성기를 추가하고 반환합니다. 반환된 리소스 작성기에 대한 호출을 연결하여 AddDatabase에 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...

.NET .NET Aspire docker.io/library/mongo 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하면 로컬 컴퓨터에 새 MongoDB 인스턴스가 만들어집니다. MongoDB 서버 리소스 작성기(mongo 변수)에 대한 참조는 데이터베이스를 추가하는 데 사용됩니다. 데이터베이스는 mongodb로 명명된 후 ExampleProject에 추가됩니다. MongoDB 서버 리소스에는 기본 자격 증명이 포함됩니다.

• MONGO_INITDB_ROOT_USERNAME: admin값입니다.
• MONGO_INITDB_ROOT_PASSWORD: password 메서드를 사용하여 생성된 임의 CreateDefaultPasswordParameter.

앱 호스트가 실행되면 암호가 앱 호스트의 비밀 저장소에 저장됩니다. Parameters 섹션에 추가되었습니다. 예를 들어:

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

매개 변수의 이름은 mongo-password, 실제로는 리소스 이름에 -password 접미사를 사용하여 서식을 지정하는 것입니다. 자세한 내용은 ASP.NET Core의 개발 시 앱 비밀 안전 스토리지에서 확인하고, 매개 변수를 사용하여에서 MongoDB 서버 리소스를 추가하십시오.

WithReference 메서드는 ExampleProject에 명명된 mongodb 연결을 구성하고, WaitFor는 mongodb 리소스가 준비될 때까지 앱 호스트에 의존 서비스를 시작하지 않도록 지시합니다.

데이터 볼륨을 사용하여 MongoDB 서버 리소스 추가

MongoDB 서버 리소스에 데이터 볼륨을 추가하려면 WithDataVolume 서버 리소스에서 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...

데이터 볼륨은 컨테이너의 수명 주기 외부에 MongoDB 서버 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 /data/db 서버 컨테이너의 MongoDB 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및바인딩 탑재보다는 왜 선호되는지에 대한 이유에 대해서는 문서: 볼륨을 참조하세요.

데이터 바인드 마운트를 사용하여 MongoDB 서버 리소스를 추가합니다.

MongoDB 서버 리소스에 데이터 바인딩 탑재를 추가하려면 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...

데이터 바인딩 탑재는 호스트 컴퓨터의 파일 시스템을 사용하여 컨테이너를 다시 시작할 때 MongoDB 서버 데이터를 유지합니다. 호스트 컴퓨터의 C:\MongoDB\Data 서버 컨테이너에서 데이터 바인드 마운트는 Windows의 /MongoDB/Data 경로(또는 Unix의 MongoDB 경로)에 탑재됩니다. 데이터 바인드 마운트에 대한 자세한 내용은 Docker 문서: Bind mounts를 참조하세요.

초기화 데이터 바인드 마운트를 사용하여 MongoDB 서버 리소스 추가

초기화 폴더 데이터 바인딩 탑재를 MongoDB 서버 리소스에 추가하려면 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...

초기화 데이터 바인딩 탑재는 데이터를 사용하여 MongoDB 서버를 초기화하는 데 사용됩니다. 초기화 데이터 바인딩 탑재는 MongoDB 서버 컨테이너 내에서 Windows의 C:\MongoDB\Init 경로(또는 호스트 컴퓨터의 Unix경로 /MongoDB/Init)에 탑재되며, MongoDB 서버 컨테이너의 /docker-entrypoint-initdb.d 경로로 매핑됩니다. MongoDB 데이터베이스에 데이터를 로드하는 데 유용한 이 폴더에 있는 스크립트를 실행합니다.

매개 변수를 사용하여 MongoDB 서버 리소스 추가

컨테이너 이미지에서 사용하는 암호를 명시적으로 제공하려는 경우 이러한 자격 증명을 매개 변수로 제공할 수 있습니다. 다음 대체 예제를 고려합니다.

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

매개 변수를 제공하는 방법에 대한 자세한 내용은 외부 매개 변수참조하세요.

MongoDB Express 리소스 추가

MongoDB Express 웹 기반 MongoDB 관리 사용자 인터페이스입니다. docker.io/library/mongo-express 컨테이너 이미지해당하는 MongoDB Express 리소스를 추가하려면 MongoDB 서버 리소스에서 WithMongoExpress 메서드를 호출합니다.

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

앞의 코드는 MongoDB 서버 리소스에 연결하도록 구성된 MongoDB Express 리소스를 추가합니다. 기본 자격 증명은 다음과 같습니다.

• ME_CONFIG_MONGODB_SERVER: 부모 MongoDBServerResource에 할당된 이름은 이 경우 mongo입니다.
• ME_CONFIG_BASICAUTH: false값입니다.
• ME_CONFIG_MONGODB_PORT: 부모 MongoDBServerResource의 기본 엔드포인트의 대상 포트에서부터 할당됩니다.
• ME_CONFIG_MONGODB_ADMINUSERNAME: 부모 MongoDBServerResource에 구성된 것과 동일한 사용자 이름입니다.
• ME_CONFIG_MONGODB_ADMINPASSWORD: 부모 MongoDBServerResource에 구성된 것과 동일한 비밀번호입니다.

또한 WithMongoExpress API는 configureContainer Express 컨테이너 리소스를 구성하는 데 사용하는 Action<IResourceBuilder<MongoExpressContainerResource>> 형식의 선택적 MongoDB 매개 변수를 노출합니다.

호스팅 통합의 상태 검사

MongoDB 호스팅 통합은 MongoDB 서버 리소스에 대한 상태 검사를 자동으로 추가합니다. 상태 검사는 MongoDB 서버 리소스가 실행 중이고 해당 리소스에 대한 연결을 설정할 수 있는지 확인합니다.

호스팅 통합은 📦 AspNetCore.HealthChecks.MongoDb NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire MongoDB 클라이언트 통합을 시작하려면 📦Aspire설치합니다.MongoDB. 클라이언트 사용 프로젝트에서 드라이버 NuGet 패키지, 즉 MongoDB 클라이언트를 사용하는 애플리케이션의 프로젝트입니다. MongoDB 클라이언트 통합은 MongoDB 서버 리소스와 상호 작용하는 데 사용할 수 있는 IMongoClient 인스턴스를 등록합니다. 앱 호스트가 MongoDB 데이터베이스 리소스를 추가하는 경우 IMongoDatabase 인스턴스도 등록됩니다.

dotnet add package Aspire.MongoDB.Driver

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

MongoDB 클라이언트 추가

클라이언트 사용 프로젝트의 Program.cs 파일에서 모든 AddMongoDBClient에 대해 IHostApplicationBuilder 확장 메서드를 호출하여 종속성 주입 컨테이너를 통해 사용할 수 있도록 IMongoClient을 등록하십시오. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddMongoDBClient(connectionName: "mongodb");

그런 다음 종속성 주입을 사용하여 IMongoClient 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 클라이언트를 검색하려면 다음을 수행합니다.

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

IMongoClient MongoDB 서버 리소스와 상호 작용하는 데 사용됩니다. 앱 호스트 프로젝트에 아직 알려지지 않은 데이터베이스를 만드는 데 사용할 수 있습니다. 앱 호스트에서 MongoDB 데이터베이스 리소스를 정의할 때 종속성 주입 컨테이너가 IMongoDatabase 인스턴스를 제공하도록 요구할 수 있습니다. 종속성 주입에 대한 자세한 내용은 .NET 종속성 주입참조하세요.

키로 설정된 MongoDB 클라이언트 추가

여러 IMongoDatabase 인스턴스를 서로 다른 연결 이름으로 등록하려는 경우가 있을 수 있습니다. 키 MongoDB 클라이언트를 등록하려면 AddKeyedMongoDBClient 메서드를 호출합니다.

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

그런 다음 종속성 주입을 사용하여 IMongoDatabase 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 연결을 검색하려면 다음을 수행합니다.

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

키 서비스에 대한 자세한 내용은 .NET 종속성 주입: 키 서비스를 참조하세요.

설정

.NET Aspire MongoDB 데이터베이스 통합은 프로젝트의 요구 사항 및 규칙을 충족하기 위한 여러 구성 접근 방식과 옵션을 제공합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 builder.AddMongoDBClient()호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddMongoDBClient("mongo");

연결 문자열은 ConnectionStrings 구성 섹션에서 검색됩니다. 다음과 같은 MongoDB 예제 JSON 구성을 고려하십시오.

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

또는 다음 MongoDB Atlas 예제 JSON 구성을 고려해 보세요.

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

이 연결 문자열의 서식을 지정하는 방법에 대한 자세한 내용은 MongoDB: ConnectionString 설명서참조하세요.

구성 공급자 사용

.NET Aspire MongoDB 통합은 Microsoft.Extensions.Configuration지원합니다. 구성에서 MongoDBSettings를 Aspire:MongoDB:Driver 키를 사용하여 로드합니다. 다음 코드 조각은 일부 옵션을 구성하는 appsettings.json 파일의 예입니다.

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

인라인 구성 사용

Action<MongoDBSettings> 대리자를 전달하여 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다.

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

구성 옵션

해당 기본값을 사용하여 구성할 수 있는 옵션은 다음과 같습니다.

Client 통합 시스템 상태 점검

기본적으로 .NET.NET Aspire클라이언트 통합에는 모든 서비스에 대해 상태 검사 사용하도록 설정될 있습니다. 마찬가지로, 많은 .NET.NET Aspire호스팅 통합도 상태 검사 엔드포인트를 활성화합니다. 자세한 내용은 다음을 참조하세요.

• .NET C# 애플리케이션 상태 검사
• 의 ASP.NET Core 상태 검사

기본적으로 .NET AspireMongoDB 클라이언트 통합은 다음 시나리오를 처리합니다.

• 활성화되면 특정 시간 내에 MongoDB 데이터베이스에 대해 연결할 수 있는지 확인하고 명령을 실행할 수 있는지 확인하는 상태 검사가 추가됩니다.
• 통합되는 /health HTTP 엔드포인트는 등록된 모든 건강 확인을 통과해야만 애플리케이션이 트래픽을 허용할 준비가 된 것으로 간주되도록 지정합니다.

관찰 가능성 및 원격 분석

.NET .NET Aspire 통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이는 때때로 관찰성의 핵심 요소 라고도 합니다. 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire MongoDB 데이터베이스 통합은 표준 .NET 로깅을 사용하며 다음 범주의 로그 항목이 표시됩니다.

• MongoDB[.*]: MongoDB 네임스페이스의 모든 로그 항목입니다.

추적

.NET Aspire MongoDB 데이터베이스 통합은 OpenTelemetry를 사용하여 다음과 같은 추적 활동을 발생시킵니다.

• MongoDB.Driver.Core.Extensions.DiagnosticSources

측정 지표

.NET Aspire MongoDB 데이터베이스 통합은 현재 OpenTelemetry 메트릭을 노출하지 않습니다.

참조

• MongoDB 데이터베이스
• .NET .NET Aspire 통합
• .NET Aspire GitHub 리포지토리