.NET .NET Aspire 社区工具包与 Meilisearch 的集成

项目
12/19/2024

注意

此集成是 .NET.NET Aspire 社区工具包的一部分，不受 .NET.NET Aspire 团队正式支持。

本文介绍如何使用 .NET.NET Aspire Meilisearch 托管集成来运行 Meilisearch 容器，并通过 Meilisearchclient访问它。

托管集成

若要运行 Meilisearch 容器，请在 📦 项目中安装 Aspire CommunityToolkit..Hosting.Meilisearch NuGet 包。

.NET 命令行界面
PackageReference

dotnet add package CommunityToolkit.Aspire.Hosting.Meilisearch

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

有关详细信息，请参阅 dotnet add package 或在 .NET 应用程序中管理包依赖项。

添加 Meilisearch 资源

在应用主机项目中，使用 AddMeilisearch 扩展方法注册和使用 Meilisearch 集成，以将 Meilisearch 容器添加到应用程序生成器。

var builder = DistributedApplication.CreateBuilder(args);

var meilisearch = builder.AddMeilisearch("meilisearch");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(meilisearch);

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

当 .NET.NET Aspire 向应用主机添加容器映像时（如前面的 docker.io/getmeili/meilisearch 映像示例所示），它会在本地计算机上创建一个新的 Meilisearch 实例。对 Meilisearch 资源（meilisearch 变量）的引用被添加到 ExampleProject。未提供主密钥时，Meilisearch 资源包含使用 master key 方法随机生成的 CreateDefaultPasswordParameter。

有关详细信息，请参阅容器资源生命周期。

将带有数据量的 Meilisearch 资源添加

若要向 Meilisearch 资源添加数据卷，请在 Meilisearch 资源上调用 Aspire.Hosting.MeilisearchBuilderExtensions.WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

var meilisearch = builder.AddMeilisearch("meilisearch")
                         .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(meilisearch);

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

数据卷用于在容器的生命周期之外保留 Meilisearch 数据。数据卷装载在 Meilisearch 容器中的 /meili_data 路径，如果未提供 name 参数，则会随机生成名称。关于数据卷以及为何它们比挂载更受欢迎的详细信息，请参阅 Docker 文档：Volumes。

添加包含数据绑定挂载的 Meilisearch 资源

若要向 Meilisearch 资源添加数据绑定装载，请调用 Aspire.Hosting.MeilisearchBuilderExtensions.WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var meilisearch = builder.AddMeilisearch("meilisearch")
                         .WithDataBindMount(
                             source: @"C:\Meilisearch\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(meilisearch);

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

重要

与卷相比，绑定装载的数据功能有限，从而提供更好的性能、可移植性和安全性，使它们更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据挂载依赖于主机的文件系统，以在容器重启时保持 Meilisearch 数据的持久性。数据绑定装载安装在 Windows 上的 C:\Meilisearch\Data（或 /Meilisearch/Data上的 Unix）路径上的 Meilisearch 容器中的主机上。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

使用主密钥参数添加 Meilisearch 资源

如果要显式提供容器映像使用的主密钥，可以将这些凭据作为参数提供。请考虑以下替代示例：

var builder = DistributedApplication.CreateBuilder(args);

var masterkey = builder.AddParameter("masterkey", secret: true);
var meilisearch = builder.AddMeilisearch("meilisearch", masterkey);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(meilisearch);

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

有关提供参数的详细信息，请参阅外部参数。

Client 集成

若要开始使用 .NET Aspire Meilisearch client 集成，请安装 📦 CommunityToolkit。Aspire。Meilisearchclient消耗项目中的 NuGet 包，即使用 Meilisearch client的应用程序的项目。

.NET 命令行界面
PackageReference

dotnet add package CommunityToolkit.Aspire.Meilisearch

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

添加 Meilisearch client

在 Program.cs消耗项目的 client 文件中，对任何 Microsoft.Extensions.Hosting.AspireMeilisearchExtensions.AddMeilisearchClient 调用 IHostApplicationBuilder 扩展方法，以注册 MeilisearchClient，以便通过依赖项注入容器使用。该方法采用连接名称参数。

builder.AddMeilisearchClient(connectionName: "meilisearch");

提示

connectionName 参数必须与在应用主机项目中添加 Meilisearch 资源时使用的名称匹配。有关详细信息，请参阅添加 Meilisearch 资源。

然后，可以使用依赖项注入检索 MeilisearchClient 实例。例如，若要从示例服务检索连接，

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

添加带密钥的 Meilisearch client

在某些情况下，可能需要使用不同的连接名称注册多个 MeilisearchClient 实例。若要注册带密钥的 Meilisearch 客户端，请调用 Microsoft.Extensions.Hosting.AspireMeilisearchExtensions.AddKeyedMeilisearchClient

builder.AddKeyedMeilisearchClient(name: "products");
builder.AddKeyedMeilisearchClient(name: "orders");

然后，可以使用依赖项注入检索 MeilisearchClient 实例。例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("products")] MeilisearchClient productsClient,
    [FromKeyedServices("orders")] MeilisearchClient ordersClient)
{
    // Use clients...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET Aspire Meilisearch client 集成提供了多个选项，用于根据项目的要求和约定配置 server 连接。

使用连接字符串

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

builder.AddMeilisearchClient("meilisearch");

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

{
  "ConnectionStrings": {
    "meilisearch": "Endpoint=http://localhost:19530/;MasterKey=123456!@#$%"
  }
}

使用配置提供程序

.NET Aspire Meilisearch Client 集成支持 Microsoft.Extensions.Configuration。它使用 CommunityToolkit.Aspire.Meilisearch.MeilisearchClientSettings 键从配置加载 Aspire:Meilisearch:Client。请考虑以下示例 appsettings：json 配置某些选项。

{
  "Aspire": {
    "Meilisearch": {
      "Client": {
        "Endpoint": "http://localhost:19530/",
        "MasterKey": "123456!@#$%"
      }
    }
  }
}

使用内联委托

您还可以传递 Action<MeilisearchClientSettings> configureSettings 委托对象来直接在代码中设置某些或全部选项，例如，通过代码设置 API 密钥：

builder.AddMeilisearchClient(
    "meilisearch",
    static settings => settings.MasterKey = "123456!@#$%");

Client 集成系统健康检查

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

通过