From a74d820bb15eb39247e42dddfed79652f533c9d2 Mon Sep 17 00:00:00 2001 From: "alireza.baloochi1380@gmail.com" Date: Wed, 23 Oct 2024 22:09:04 +0330 Subject: [PATCH 1/5] Add Meilisearch integeration docs --- docs/community-toolkit/hosting-meilisearch.md | 227 ++++++++++++++++++ docs/toc.yml | 2 + 2 files changed, 229 insertions(+) create mode 100644 docs/community-toolkit/hosting-meilisearch.md diff --git a/docs/community-toolkit/hosting-meilisearch.md b/docs/community-toolkit/hosting-meilisearch.md new file mode 100644 index 0000000000..8775779004 --- /dev/null +++ b/docs/community-toolkit/hosting-meilisearch.md @@ -0,0 +1,227 @@ +--- +title: Meilisearch hosting +description: Learn how to use the .NET Aspire Meilisearch hosting and client integration to run the Meilisearch container and accessing it via the Meilisearch client. +ms.date: 10/23/2024 +--- + +# .NET Aspire Community Toolkit Meilisearch integration + +[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)] + +[!INCLUDE [banner](includes/banner.md)] + +In this article, you learn how to use the .NET Aspire Meilisearch hosting integration to run [Meilisearch](https://meilisearch.com) container and accessing it via the [Meilisearch](https://github.com/meilisearch/meilisearch-dotnet) client. + +## Hosting integration + +To run the Meilisearch container, install the [📦 CommunityToolkit.Aspire.Hosting.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Meilisearch) NuGet package in the [app host](xref:aspire/app-host) project. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package CommunityToolkit.Aspire.Hosting.Meilisearch +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). + +### 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. + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var meilisearch = builder.AddMeilisearch("meilisearch"); + +builder.AddProject() + .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 method when a master key wasn't provided. +For more information, see [Container resource lifecycle](../fundamentals/app-host-overview.md#container-resource-lifecycle). + +### Add Meilisearch resource with data volume + +To add a data volume to the Meilisearch resource, call the method on the Meilisearch resource: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var meilisearch = builder.AddMeilisearch("meilisearch") + .WithDataVolume(); + +builder.AddProject() + .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](#add-meilisearch-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes). + +### Add Meilisearch resource with data bind mount + +To add a data bind mount to the Meilisearch resource, call the method: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var meilisearch = builder.AddMeilisearch("meilisearch") + .WithDataBindMount( + source: @"C:\Meilisearch\Data"); + +builder.AddProject() + .WithReference(meilisearch); + +// After adding all resources, run the app... +``` + +[!INCLUDE [data-bind-mount-vs-volumes](../includes/data-bind-mount-vs-volumes.md)] + +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](https://docs.docker.com/engine/storage/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: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var masterkey = builder.AddParameter("masterkey", secret: true); +var meilisearch = builder.AddMeilisearch("meilisearch", masterkey); + +builder.AddProject() + .WithReference(meilisearch); + +// After adding all resources, run the app... +``` + +For more information on providing parameters, see [External parameters](../fundamentals/external-parameters.md). + +## Client integration + +To get started with the .NET Aspire Meilisearch client integration, install the [CommunityToolkit.Aspire.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Meilisearch) NuGet package in the client-consuming project, that is, the project for the application that uses the Meilisearch client. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package CommunityToolkit.Aspire.Meilisearch +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +### Add Meilisearch client + +In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the extension method on any to register an `MeilisearchClient` for use via the dependency injection container. The method takes a connection name parameter. + +```csharp +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](#add-meilisearch-resource). + +You can then retrieve the `MeilisearchClient` instance using dependency injection. For example, to retrieve the connection from an example service: + +```csharp +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 : + +```csharp +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: + +```csharp +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](/dotnet/core/extensions/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`: + +```csharp +builder.AddMeilisearchClient("meilisearch"); +``` + +Then the connection string will be retrieved from the `ConnectionStrings` configuration section: + +```json +{ + "ConnectionStrings": { + "meilisearch": "Endpoint=http://localhost:19530/;MasterKey=123456!@#$%" + } +} +``` + +#### Use configuration providers + +The .NET Aspire Meilisearch Client integration supports . It loads the from configuration by using the `Aspire:Meilisearch:Client` key. Consider the following example _appsettings.json_ that configures some of the options: + +```json +{ + "Aspire": { + "Meilisearch": { + "Client": { + "Endpoint": "http://localhost:19530/", + "MasterKey": "123456!@#$%" + } + } + } +} +``` + +#### Use inline delegates + +Also you can pass the `Action configureSettings` delegate to set up some or all the options inline, for example to set the API key from code: + +```csharp +builder.AddMeilisearchClient("meilisearch", 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 + +- [Meilisearch](https://meilisearch.com) +- [Meilisearch Client](https://github.com/meilisearch/meilisearch-dotnet) +- [.NET Aspire Community Toolkit GitHub repo](https://github.com/CommunityToolkit/Aspire) diff --git a/docs/toc.yml b/docs/toc.yml index f12812694e..bb0fbd4a17 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -246,6 +246,8 @@ items: href: community-toolkit/hosting-nodejs-extensions.md - name: Ollama href: community-toolkit/ollama.md + - name: Meilisearch + href: community-toolkit/hosting-meilisearch.md - name: Custom integrations items: From bcbe6ef37dc4f62779534de052445dc056dd2db7 Mon Sep 17 00:00:00 2001 From: "alireza.baloochi1380@gmail.com" Date: Wed, 23 Oct 2024 22:20:46 +0330 Subject: [PATCH 2/5] Replace xref with backtick --- docs/community-toolkit/hosting-meilisearch.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/community-toolkit/hosting-meilisearch.md b/docs/community-toolkit/hosting-meilisearch.md index 8775779004..08d8bf0d83 100644 --- a/docs/community-toolkit/hosting-meilisearch.md +++ b/docs/community-toolkit/hosting-meilisearch.md @@ -53,7 +53,7 @@ For more information, see [Container resource lifecycle](../fundamentals/app-hos ### Add Meilisearch resource with data volume -To add a data volume to the Meilisearch resource, call the method on the Meilisearch resource: +To add a data volume to the Meilisearch resource, call the `Aspire.Hosting.MeilisearchBuilderExtensions.WithDataVolume` method on the Meilisearch resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -71,7 +71,7 @@ The data volume is used to persist the Meilisearch data outside the lifecycle of ### Add Meilisearch resource with data bind mount -To add a data bind mount to the Meilisearch resource, call the method: +To add a data bind mount to the Meilisearch resource, call the `Aspire.Hosting.MeilisearchBuilderExtensions.WithDataBindMount` method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -129,7 +129,7 @@ dotnet add package CommunityToolkit.Aspire.Meilisearch ### Add Meilisearch client -In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the extension method on any to register an `MeilisearchClient` for use via the dependency injection container. The method takes a connection name parameter. +In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the `Microsoft.Extensions.Hosting.AspireMeilisearchExtensions.AddMeilisearchClient` extension method on any to register an `MeilisearchClient` for use via the dependency injection container. The method takes a connection name parameter. ```csharp builder.AddMeilisearchClient(connectionName: "meilisearch"); @@ -149,7 +149,7 @@ public class ExampleService(MeilisearchClient 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 : +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` ```csharp builder.AddKeyedMeilisearchClient(name: "products"); @@ -193,7 +193,7 @@ Then the connection string will be retrieved from the `ConnectionStrings` config #### Use configuration providers -The .NET Aspire Meilisearch Client integration supports . It loads the from configuration by using the `Aspire:Meilisearch:Client` key. Consider the following example _appsettings.json_ that configures some of the options: +The .NET Aspire Meilisearch Client integration supports . 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: ```json { From 086a0b555ed29cb8a8c30b05615e59a060ce8689 Mon Sep 17 00:00:00 2001 From: Alireza Baloochi Date: Thu, 24 Oct 2024 11:38:23 +0330 Subject: [PATCH 3/5] Update integrations-overview.md --- docs/fundamentals/integrations-overview.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index a022faaa8e..d5e3a8f5e0 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -138,6 +138,7 @@ For more information, see [GitHub: Aspire.Hosting.AWS library](https://github.co | **Learn More**: [📄 Java/Spring hosting](../community-toolkit/hosting-java.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Java](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java)
- **Client**: N/A | A integration for running Java code in .NET Aspire either using the local JDK or using a container. | | - **Learn More**: [📄 Node.js hosting extensions](../community-toolkit/hosting-nodejs-extensions.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.NodeJs.Extensions](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.NodeJS.Extensions)
- **Client**: N/A | An integration that contains some additional extensions for running Node.js applications | | - **Learn More**: [📄 Ollama](../community-toolkit/ollama.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Ollama](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Ollama)
- **Client**: [📦 Aspire.CommunitToolkit.OllamaSharp](https://nuget.org/packages/CommunityToolkit.Aspire.OllamaSharp) | An Aspire component leveraging the [Ollama](https://ollama.com) container with support for downloading a model on startup. | +| - **Learn More**: [📄 Meilisearch hosting](../community-toolkit/hosting-meilisearch.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Meilisearch)
- **Client**: [📦 Aspire.CommunitToolkit.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Meilisearch) | An Aspire component leveraging the [Meilisearch](https://meilisearch.com) container. | For more information, see [GitHub: CommunityToolkit.Aspire library](https://github.com/CommunityToolkit/Aspire). From 0bd6ff6cbba835d307f6f6abd3b1b93a22ac8262 Mon Sep 17 00:00:00 2001 From: "alireza.baloochi1380@gmail.com" Date: Thu, 24 Oct 2024 11:39:58 +0330 Subject: [PATCH 4/5] Update ms.date --- docs/fundamentals/integrations-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index d5e3a8f5e0..f642657e6c 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -1,7 +1,7 @@ --- title: .NET Aspire integrations overview description: Explore the fundamental concepts of .NET Aspire integrations and learn how to integrate them into your apps. -ms.date: 09/25/2024 +ms.date: 10/24/2024 ms.topic: conceptual uid: aspire/integrations --- From 667cfe2671c44398a24aa0421d540d25488fdf17 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 24 Oct 2024 07:13:59 -0500 Subject: [PATCH 5/5] Apply suggestions from code review --- docs/community-toolkit/hosting-meilisearch.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/community-toolkit/hosting-meilisearch.md b/docs/community-toolkit/hosting-meilisearch.md index 08d8bf0d83..72f44a8bd9 100644 --- a/docs/community-toolkit/hosting-meilisearch.md +++ b/docs/community-toolkit/hosting-meilisearch.md @@ -49,6 +49,7 @@ builder.AddProject() ``` 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 method when a master key wasn't provided. + For more information, see [Container resource lifecycle](../fundamentals/app-host-overview.md#container-resource-lifecycle). ### Add Meilisearch resource with data volume @@ -59,10 +60,10 @@ To add a data volume to the Meilisearch resource, call the `Aspire.Hosting.Meili var builder = DistributedApplication.CreateBuilder(args); var meilisearch = builder.AddMeilisearch("meilisearch") - .WithDataVolume(); + .WithDataVolume(); builder.AddProject() - .WithReference(meilisearch); + .WithReference(meilisearch); // After adding all resources, run the app... ``` @@ -77,11 +78,11 @@ To add a data bind mount to the Meilisearch resource, call the `Aspire.Hosting.M var builder = DistributedApplication.CreateBuilder(args); var meilisearch = builder.AddMeilisearch("meilisearch") - .WithDataBindMount( - source: @"C:\Meilisearch\Data"); + .WithDataBindMount( + source: @"C:\Meilisearch\Data"); builder.AddProject() - .WithReference(meilisearch); + .WithReference(meilisearch); // After adding all resources, run the app... ``` @@ -110,7 +111,7 @@ For more information on providing parameters, see [External parameters](../funda ## Client integration -To get started with the .NET Aspire Meilisearch client integration, install the [CommunityToolkit.Aspire.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Meilisearch) NuGet package in the client-consuming project, that is, the project for the application that uses the Meilisearch client. +To get started with the .NET Aspire Meilisearch client integration, install the [📦 CommunityToolkit.Aspire.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Meilisearch) NuGet package in the client-consuming project, that is, the project for the application that uses the Meilisearch client. ### [.NET CLI](#tab/dotnet-cli) @@ -213,7 +214,9 @@ The .NET Aspire Meilisearch Client integration supports configureSettings` delegate to set up some or all the options inline, for example to set the API key from code: ```csharp -builder.AddMeilisearchClient("meilisearch", settings => settings.MasterKey = "123456!@#$%"); +builder.AddMeilisearchClient( + "meilisearch", + static settings => settings.MasterKey = "123456!@#$%"); ``` #### Client integration health checks