.NET Aspire Milvus database integration

Article
11/12/2024

In this article, you learn how to use the .NET Aspire Milvus database integration. The Aspire.Milvus.Client library registers a MilvusClient in the DI container for connecting to a Milvus server.

Prerequisites

Milvus server and connection string for accessing the server API endpoint.

Get started

To get started with the .NET Aspire Milvus database integration, install the 📦 Aspire.Milvus.Client NuGet package in the client-consuming project, i.e., the project for the application that uses the Milvus database client.

.NET CLI
PackageReference

dotnet add package Aspire.Milvus.Client

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

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

Example usage

In the Program.cs file of your project, call the AddMilvusClient extension method to register a MilvusClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddMilvusClient("milvus");

App host usage

To model the Milvus resource in the app host, install the 📦 Aspire.Hosting.Milvus NuGet package in the app host project.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Milvus

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

In the Program.cs file of AppHost, register a Milvus server and consume the connection using the following methods:

var milvus = builder.AddMilvus("milvus");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(milvus);

The WithReference method configures a connection in the MyService project named milvus. In the Program.cs file of MyService, the Milvus connection can be consumed using:

builder.AddMilvusClient("milvus");

Milvus supports configuration-based (environment variable COMMON_SECURITY_DEFAULTROOTPASSWORD) default passwords. The default user is root and the default password is Milvus. To change the default password in the container, pass an apiKey parameter when calling the AddMilvus hosting API:

var apiKey = builder.AddParameter("apiKey");

var milvus = builder.AddMilvus("milvus", apiKey);

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(milvus);

The preceding code gets a parameter to pass to the AddMilvus API, and internally assigns the parameter to the COMMON_SECURITY_DEFAULTROOTPASSWORD environment variable of the Milvus container. The apiKey parameter is usually specified as a user secret:

{
  "Parameters": {
    "apiKey": "Non-default P@ssw0rd"
  }
}

For more information, see External parameters.

Configuration

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

Tip

The default use is root and the default password is Milvus. Currently, Milvus doesn't support changing the superuser password at startup. It needs to be manually changed with the client.

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.AddMilvusClient():

builder.AddMilvusClient("milvus");

And then the connection string will be retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "milvus": "Endpoint=http://localhost:19530/;Key=root:123456!@#$%"
  }
}

By default the MilvusClient uses the gRPC API endpoint.

Use configuration providers

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

{
  "Aspire": {
    "Milvus": {
      "Client": {
        "Key": "root:123456!@#$%"
      }
    }
  }
}

Use inline delegates

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

builder.AddMilvusClient(
    "milvus",
    settings => settings.Key = "root:12345!@#$%");

Health checks

By default, .NET Aspire integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.

The .NET Aspire Milvus database integration uses the configured client to perform a HealthAsync. If the result is healthy, 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.

Observability and telemetry

.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire Milvus database integration uses standard .NET logging, and you'll see log entries from the following category:

Milvus.Client

Share via