.NET .NET Aspire 커뮤니티 도구 키트 RavenDB 통합

포함: 호스팅 통합 -&— Client 통합

RavenDB 는 빠르고 효율적이며 확장 가능한 데이터 스토리지를 위해 설계된 고성능 오픈 소스 NoSQL 데이터베이스입니다. ACID 트랜잭션, 분산 데이터 복제 및 시계열 데이터 관리와 같은 고급 기능을 지원하므로 최신 애플리케이션 개발에 적합합니다. .NET Aspire RavenDB 통합을 사용하면 기존 RavenDB 인스턴스에 연결하거나 docker.io/library/ravendb 컨테이너 이미지를 사용하여 새 인스턴스 .NET 를 만들 수 있습니다.

호스팅 통합

RavenDB 호스팅 통합은 서버를 RavenDBServerResource 형식으로, 데이터베이스를 RavenDBDatabaseResource 형식으로 모델화합니다. 이러한 형식 및 API에 액세스하려면 CommunityToolkit를📦Aspire 추가합니다. 앱 호스트 프로젝트의 Hosting.RavenDB NuGet 패키지입니다.

dotnet add package CommunityToolkit.Aspire.Hosting.RavenDB

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

자세한 내용을 보려면 dotnet add package 또는 .NET 응용 프로그램에서 패키지 종속성 관리를 참조하세요.

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

앱 호스트 프로젝트에서 RavenDB를 설정하려면 인스턴스의 확장 메서드 builder 중 AddRavenDB 하나를 호출하여 RavenDB 서버 리소스를 추가한 다음 서버 리소스를 호출 AddDatabase 하여 데이터베이스를 추가합니다. 예제는 다음과 같습니다.

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer");
var ravendb = ravenServer.AddDatabase("ravendb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravendb)
       .WaitFor(ravendb);

// After adding all resources, build and run the app...

이전 예제 docker.io/ravendb/ravendb 와 같이 컨테이너 이미지를 앱 호스트에 추가하면 .NET.NET Aspire 로컬 컴퓨터에 새 RavenDB 인스턴스가 만들어집니다. RavenDB 데이터베이스 리소스에 대한 참조(ravendb 변수)가 ExampleProject에 추가됩니다.

자세한 내용은 컨테이너 리소스 수명 주기를 참조하세요.

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

RavenDB 서버 리소스에 데이터 볼륨을 추가하려면 RavenDB 서버 리소스에서 메서드를 호출 Aspire.Hosting.RavenDBBuilderExtensions.WithDataVolume 합니다.

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
                         .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravenServer)
       .WaitFor(ravenServer);

데이터 볼륨은 컨테이너의 수명 주기가 종료된 후에도 사용할 수 있으며 RavenDB 데이터는 유지됩니다. 데이터 볼륨은 RavenDB 컨테이너의 /var/lib/ravendb/data 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 자세한 데이터 볼륨 정보와 그것들이 바인드 마운트보다 선호되는 이유에 대해서는 Docker 문서: '볼륨'을 참조하세요.

데이터 바인딩 탑재를 사용하여 RavenDB 서버 리소스 추가

RavenDB 서버 리소스에 데이터 바인딩 탑재를 추가하려면 다음 메서드를 호출합니다 Aspire.Hosting.RavenDBBuilderExtensions.WithDataBindMount .

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
                         .WithDataBindMount(source: @"C:\RavenDb\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravenServer)
       .WaitFor(ravenServer);

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

보안 RavenDB 서버 리소스 추가

미리 구성된 settings.json 파일 또는 자체 서명된 인증서의 설정을 사용하여 새 보안 RavenDB 인스턴스를 만들려면 RavenDBServerSettings.Secured 메서드를 사용하거나 RavenDBServerSettings.SecuredWithLetsEncrypt Let's Encrypt 구성용을 사용합니다. 이러한 방법을 사용하면 도메인 URL, 인증서 세부 정보 및 추가 서버 설정을 지정할 수 있습니다. 다음은 Let's Encrypt를 사용하여 보안 RavenDB 서버 리소스를 추가하는 방법의 예입니다.

var builder = DistributedApplication.CreateBuilder(args);

var serverSettings = RavenDBServerSettings.SecuredWithLetsEncrypt(
    domainUrl: "https://mycontainer.development.run",
    certificatePath: "/etc/ravendb/security/cluster.server.certificate.mycontainer.pfx");

var ravendb = builder.AddRavenDB("ravenSecuredServer", serverSettings)
    .WithBindMount("C:/RavenDB/Server/Security", "/etc/ravendb/security", false)
    .AddDatabase("ravendbSecured");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravendb)
       .WaitFor(ravendb);

통합 건강 검사를 호스팅

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

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

Client 통합

RavenDB 클라이언트 통합을 .NET.NET Aspire 시작하려면 CommunityToolkit를📦Aspire 설치합니다. RavenDB.Client 클라이언트 사용 프로젝트의 NuGet 패키지, 즉 RavenDB 클라이언트를 사용하는 애플리케이션에 대한 프로젝트입니다. RavenDB 클라이언트 통합은 RavenDB 서버 리소스 또는 기존 RavenDB 인스턴스와 상호 작용하기 위한 진입점 역할을 하는 IDocumentStore 인스턴스를 등록합니다. 앱 호스트에 RavenDB 데이터베이스 리소스가 포함된 경우 연결된 IDocumentSession 및 IAsyncDocumentSession 인스턴스도 종속성 주입을 위해 등록됩니다.

dotnet add package CommunityToolkit.Aspire.RavenDB.Client

<PackageReference Include="CommunityToolkit.Aspire.RavenDB.Client"
                  Version="*" />

RavenDB 클라이언트 추가

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

builder.AddRavenDBClient(connectionName: "ravendb");

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

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

를 사용하여 RavenDB 클라이언트 추가 RavenDBClientSettings

AddRavenDBClient 메서드는 RavenDBClientSettings 객체를 허용하는 오버로드를 제공합니다. 이렇게 하면 호스팅 통합과 독립적으로 클라이언트 통합을 사용할 수 있습니다. 클래스에는 RavenDBClientSettings 연결을 설정하는 데 필요한 매개 변수가 포함되어 있습니다. 사용 가능한 구성 옵션에 대한 자세한 내용은 아래 구성 옵션 섹션에서 확인할 수 있습니다.

예제는 다음과 같습니다.

var settings = new RavenDBClientSettings
{
    Urls = new[] { serverUrl },
    DatabaseName =  myDatabaseName,
    Certificate = myCertificate
};

builder.AddRavenDBClient(settings: settings);

등록 후에는 IDocumentStore 인스턴스를 검색하고 그와 연결된 IDocumentSession 및 IAsyncDocumentSession 인스턴스를 다음과 같이 검색할 수 있습니다.

var documentStore = host.Services.GetRequiredService<IDocumentStore>();
var session = host.Services.GetRequiredService<IDocumentSession>();
var asyncSession = host.Services.GetRequiredService<IAsyncDocumentSession>();

키 지정된 RavenDB 클라이언트 추가

애플리케이션에서 서로 다른 연결 구성이 필요한 여러 IDocumentStore 인스턴스를 사용하는 경우, Microsoft.Extensions.Hosting.RavenDBClientExtension.AddKeyedRavenDBClient 확장 메서드를 사용하여 키 지정된 RavenDB 클라이언트를 등록할 수 있습니다.

builder.AddKeyedRavenDBClient(serviceKey: "production", connectionName: "production");
builder.AddKeyedRavenDBClient(serviceKey: "testing", connectionName: "testing");

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

public class ExampleService(
    [FromKeyedServices("production")] IDocumentStore production,
    [FromKeyedServices("testing")] IDocumentStore testing)
{
    // Use databases...
}

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

구성 / 설정

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

연결 문자열 사용

구성 섹션에서 연결 문자열을 ConnectionStrings 사용하는 경우 다음을 호출 builder.AddRavenDBClient할 때 연결 문자열의 이름을 입력합니다.

builder.AddRavenDBClient("ravendb");

연결 문자열은 ConnectionStrings 구성 섹션에서 검색됩니다.

{
  "ConnectionStrings": {
    "ravendb": "Url=http://localhost:8080/;Database=ravendb"
  }
}

구성 공급자 사용

RavenDB 통합에서 .NET.NET Aspire 지원합니다.Microsoft.Extensions.Configuration 구성에서 RavenDBClientSettings을(를) Aspire:RavenDB:Client 키를 사용하여 로드합니다. 몇 가지 옵션을 구성하는 다음 예제 appsettings.json 살펴보겠습니다.

{
  "Aspire": {
    "RavenDB": {
      "Client": {
        "ConnectionString": "URL=http://localhost:8080;Database=ravendb",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      }
    }
  }
}

인라인 구성 사용

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

builder.AddRavenDBClient(connectionName: "ravendb", configureSettings: 
    settings => 
    {
        settings.CreateDatabase = true;
        settings.Certificate = myCertificate;
        settings.DisableTracing = true;
    }

구성 옵션

RavenDB 클라이언트 통합은 .NET.NET Aspire 클래스를 통해 RavenDBClientSettings 유연한 구성 옵션을 제공하므로 프로젝트의 요구 사항에 맞게 연결을 조정할 수 있습니다. 주요 속성은 다음과 같습니다.

Client 통합 시스템 상태 점검

RavenDB 클라이언트 통합은 .NET.NET Aspire으로 구성된 클라이언트를 사용하여 IsHealthyAsync 작업을 수행합니다. 결과가 true이면, 상태 검사는 정상으로 간주되며, 그렇지 않으면 비정상으로 간주됩니다. 마찬가지로 예외가 있는 경우, 오류가 상태 검사 실패를 통해 전파되어 상태 검사가 비정상으로 간주됩니다.

참고하십시오

• RavenDB
• 컨테이너에서 Docker 실행
• RavenDB 코드
• .NET Aspire 커뮤니티 도구 키트 GitHub 리포지토리