Aspire 社区工具包与 RavenDB 集成

包含： - Client 集成

RavenDB 是一种高性能开源 NoSQL 数据库，专为快速、高效且可缩放的数据存储而设计。 它支持 ACID 事务、分布式数据复制和时序数据管理等高级功能，使其成为新式应用程序开发的极佳选择。 Aspire RavenDB 集成使你能够连接到现有的 RavenDB 实例，或使用 .NET创建新实例。

托管集成

托管集成的 RavenDB 将服务器建模为 RavenDBServerResource 类型，并将数据库建模为类型 RavenDBDatabaseResource 。 若要访问这些类型和 API，请添加 📦 CommunityToolkit。Aspire。AppHost 项目中的 Hosting.RavenDB NuGet 包。

dotnet add package CommunityToolkit.Aspire.Hosting.RavenDB

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

有关详细信息，请参阅 dotnet 添加包 或 管理 .NET 应用程序中的包依赖性。

添加 RavenDB 服务器资源和数据库资源

若要在 AppHost 项目中设置 RavenDB，请在实例上AddRavenDB调用其中builder一种扩展方法以添加 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...

将 Aspire 容器映像添加到 AppHost 时，如前面的示例 docker.io/ravendb/ravendb 所示，它会在您的本地计算机上创建一个新的 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 数据。 数据绑定挂载在主机上的 Windows（或 C:\RavenDb\Data 上的 /RavenDB/Data）路径中的 RavenDB 容器中的 Unix。 有关数据绑定挂载的详细信息，请参阅 Docker 文档：数据绑定挂载。

添加受保护的 RavenDB 服务器资源

若要使用预配置的 settings.json 文件或自签名证书中的设置创建新的安全 RavenDB 实例，请使用 RavenDBServerSettings.Secured 该方法或 RavenDBServerSettings.SecuredWithLetsEncrypt “让我们加密”配置。 这些方法允许你指定域 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 集成

若要开始使用 Aspire RavenDB 客户端集成，请在依赖于 RavenDB 客户端的项目中安装 📦 CommunityToolkit.Aspire.RavenDB.Client NuGet 包，该项目即是使用 RavenDB 客户端的应用程序的项目。 RavenDB 客户端集成注册 IDocumentStore 实例，该实例充当与 RavenDB 服务器资源或现有 RavenDB 实例交互的入口点。 如果 AppHost 包含 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...
}

使用 RavenDBClientSettings 添加 RavenDB 客户端

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 依赖关系注入：密钥服务。

配置

Aspire RavenDB Client 集成提供了多种配置方法和选项，以满足项目的要求和约定。

使用连接字符串

使用配置部分中的连接字符串 ConnectionStrings 时，在调用 builder.AddRavenDBClient时提供连接字符串的名称：

builder.AddRavenDBClient("ravendb");

将从配置部分检索 ConnectionStrings 连接字符串：

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

使用配置提供器

Aspire RavenDB 集成支持 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;
    }

配置选项

Aspire RavenDB 客户端集成通过RavenDBClientSettings类提供灵活的配置选项，使你能够定制与项目要求的连接。 以下是关键属性：

Client 集成健康检查

Aspire RavenDB 客户端集成使用配置的客户端来执行 IsHealthyAsync。 如果结果是 true，则健康检查被视为健康，否则视为不健康。 同样，如果存在异常，则健康检查被视为不正常，错误会通过健康检查的失败进行传播。

另请参阅

• RavenDB
• RavenDB Dockerfile 指南
• RavenDB 代码
• Aspire 社区工具包 GitHub 存储库