Modifica

Condividi tramite

.NET Aspire Community Toolkit Meilisearch integration

  • Articolo

Includes: Hosting integration and Client integration

Note

This integration is part of the .NET Aspire Community Toolkit and isn't officially supported by the .NET Aspire team.

In this article, you learn how to use the .NET Aspire Meilisearch hosting integration to run Meilisearch container and accessing it via the Meilisearch client.

Hosting integration

To run the Meilisearch container, install the 📦 CommunityToolkit.Aspire.Hosting.Meilisearch NuGet package in the app host project.

dotnet add package CommunityToolkit.Aspire.Hosting.Meilisearch

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add Meilisearch resource

In the app host project, register and consume the Meilisearch integration using the AddMeilisearch extension method to add the Meilisearch container to the application builder.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

When .NET Aspire adds a container image to the app host, as shown in the preceding example with the docker.io/getmeili/meilisearch image, it creates a new Meilisearch instance on your local machine. A reference to your Meilisearch resource (the meilisearch variable) is added to the ExampleProject. The Meilisearch resource includes a randomly generated master key using the CreateDefaultPasswordParameter method when a master key wasn't provided.

For more information, see Container resource lifecycle.

Add Meilisearch resource with data volume

To add a data volume to the Meilisearch resource, call the Aspire.Hosting.MeilisearchBuilderExtensions.WithDataVolume method on the Meilisearch resource:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

The data volume is used to persist the Meilisearch data outside the lifecycle of its container. The data volume is mounted at the /meili_data path in the Meilisearch container and when a name parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see Docker docs: Volumes.

Add Meilisearch resource with data bind mount

To add a data bind mount to the Meilisearch resource, call the Aspire.Hosting.MeilisearchBuilderExtensions.WithDataBindMount method:

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

Important

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine's filesystem to persist the Meilisearch data across container restarts. The data bind mount is mounted at the C:\Meilisearch\Data on Windows (or /Meilisearch/Data on Unix) path on the host machine in the Meilisearch container. For more information on data bind mounts, see Docker docs: Bind mounts.

Add Meilisearch resource with master key parameter

When you want to explicitly provide the master key used by the container image, you can provide these credentials as parameters. Consider the following alternative example:

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

For more information on providing parameters, see External parameters.

Client integration

To get started with the .NET Aspire Meilisearch client integration, install the 📦 CommunityToolkit.Aspire.Meilisearch NuGet package in the client-consuming project, that is, the project for the application that uses the Meilisearch client.

dotnet add package CommunityToolkit.Aspire.Meilisearch

Add Meilisearch client

In the Program.cs file of your client-consuming project, call the Microsoft.Extensions.Hosting.AspireMeilisearchExtensions.AddMeilisearchClient extension method on any IHostApplicationBuilder to register an MeilisearchClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddMeilisearchClient(connectionName: "meilisearch");

Tip

The connectionName parameter must match the name used when adding the Meilisearch resource in the app host project. For more information, see Add Meilisearch resource.

You can then retrieve the MeilisearchClient instance using dependency injection. For example, to retrieve the connection from an example service:

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

Add keyed Meilisearch client

There might be situations where you want to register multiple MeilisearchClient instances with different connection names. To register keyed Meilisearch clients, call the Microsoft.Extensions.Hosting.AspireMeilisearchExtensions.AddKeyedMeilisearchClient

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

Then you can retrieve the MeilisearchClient instances using dependency injection. For example, to retrieve the connection from an example service:

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

For more information on keyed services, see .NET dependency injection: Keyed services.

Configuration

The .NET Aspire Meilisearch client integration provides multiple options to configure the server connection based on the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling builder.AddMeilisearchClient:

builder.AddMeilisearchClient("meilisearch");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

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

Use configuration providers

The .NET Aspire Meilisearch Client integration supports Microsoft.Extensions.Configuration. It loads the CommunityToolkit.Aspire.Meilisearch.MeilisearchClientSettings from configuration by using the Aspire:Meilisearch:Client key. Consider the following example appsettings.json that configures some of the options:

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

Use inline delegates

Also you can pass the Action<MeilisearchClientSettings> configureSettings delegate to set up some or all the options inline, for example to set the API key from code:

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

Client integration health checks

The .NET Aspire Meilisearch integration uses the configured client to perform a IsHealthyAsync. If the result is true, the health check is considered healthy, otherwise it's unhealthy. Likewise, if there's an exception, the health check is considered unhealthy with the error propagating through the health check failure.

See also