.NET Aspire Milvus database integration

Includes: Hosting integration and Client integration

Milvus is an open-source vector database system that efficiently stores, indexes, and searches large-scale vector data. It's commonly used in machine learning, artificial intelligence, and data science applications.

Vector data encodes information as mathematical vectors, which are arrays of numbers or coordinates. Machine learning and AI systems often use vectors to represent unstructured objects like images, text, audio, or video. Each dimension in the vector describes a specific characteristic of the object. By comparing them, systems can classify, search, and identify clusters of objects.

In this article, you learn how to use the .NET Aspire Milvus database integration. The .NET Aspire Milvus database integration enables you to connect to existing Milvus databases or create new instances with the milvusdb/milvus container image.

Hosting integration

The Milvus database hosting integration models the server as the MilvusServerResource type and the database as the MilvusDatabaseResource type. To access these types and APIs, add the 📦 Aspire.Hosting.Milvus NuGet package in the app host project.

.NET CLI

dotnet add package Aspire.Hosting.Milvus

PackageReference

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

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

Add Milvus server and database resources

In your app host project, call AddMilvus to add and return a Milvus resource builder. Chain a call to the returned resource builder to AddDatabase, to add a Milvus database resource.

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

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

Note

The Milvus container can be slow to start, so it's best to use a persistent lifetime to avoid unnecessary restarts. For more information, see Container resource lifetime.

When .NET Aspire adds a container image to the app host, as shown in the preceding example with the milvusdb/milvus image, it creates a new Milvus instance on your local machine. A reference to your Milvus resource builder (the milvus variable) is used to add a database. The database is named milvusdb and then added to the ExampleProject.

The WithReference method configures a connection in the ExampleProject named milvusdb.

Tip

If you'd rather connect to an existing Milvus server, call AddConnectionString instead. For more information, see Reference existing resources.

Handling credentials and passing other parameters for the Milvus resource

The Milvus resource includes default credentials with a username of root and the password Milvus. Milvus supports configuration-based default passwords by using the environment variable COMMON_SECURITY_DEFAULTROOTPASSWORD. To change the default password in the container, pass an apiKey parameter when calling the AddMilvus hosting API:

var apiKey = builder.AddParameter("apiKey", secret: true);

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

var myService = builder.AddProject<Projects.ExampleProject>()
                       .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.

Add a Milvus resource with a data volume

To add a data volume to the Milvus service resource, call the WithDataVolume method on the Milvus resource:

var builder = DistributedApplication.CreateBuilder(args);

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

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

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

The data volume is used to persist the Milvus data outside the lifecycle of its container. The data volume is mounted at the /var/lib/milvus path in the SQL Server 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 a Milvus resource with a data bind mount

To add a data bind mount to the Milvus resource, call the WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataBindMount(source: @"C:\Milvus\Data");

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

// 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 Milvus data across container restarts. The data bind mount is mounted at the C:\Milvus\Data on Windows (or /Milvus/Data on Unix) path on the host machine in the Milvus container. For more information on data bind mounts, see Docker docs: Bind mounts.

Create an Attu resource

Attu is a graphical user interface (GUI) and management tool designed to interact with Milvus and its databases. It includes rich visualization features that can help you investigate and understand your vector data.

If you want to use Attu to manage Milvus in your .NET Aspire solution, call the WithAttu extension method on your Milvus resource. The method creates a container from the zilliz/attu image:

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithAttu()
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

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

When you debug the .NET Aspire solution, you'll see an Attu container listed in the solution's resources. Select the resource's endpoint to open the GUI and start managing databases.

Client integration

To get started with the .NET Aspire Milvus client integration, install the 📦 Aspire.Milvus.Client NuGet package in the client-consuming project, that is, the project for the application that uses the Milvus database client. The Milvus client integration registers a Milvus.Client.MilvusClient instance that you can use to interact with Milvus databases.

.NET CLI

dotnet add package Aspire.Milvus.Client

PackageReference

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

Add a Milvus client

In the Program.cs file of your client-consuming project, call the AddMilvusClient extension method on any IHostApplicationBuilder to register a MilvusClient for use through the dependency injection container. The method takes a connection name parameter.

builder.AddMilvusClient("milvusdb");

Tip

The connectionName parameter must match the name used when adding the Milvus database resource in the app host project. In other words, when you call AddDatabase and provide a name of milvusdb that same name should be used when calling AddMilvusClient. For more information, see Add a Milvus server resource and database resource.

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

public class ExampleService(MilvusClient client)
{
    // Use the Milvus Client...
}

For more information on dependency injection, see .NET dependency injection.

Add a keyed Milvus client

There might be situations where you want to register multiple MilvusClient instances with different connection names. To register keyed Milvus clients, call the AddKeyedMilvusClient method:

builder.AddKeyedMilvusClient(name: "mainDb");
builder.AddKeyedMilvusClient(name: "loggingDb");

Important

When using keyed services, it's expected that your Milvus resource configured two named databases, one for the mainDb and one for the loggingDb.

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

public class ExampleService(
    [FromKeyedServices("mainDb")] MilvusClient mainDbClient,
    [FromKeyedServices("loggingDb")] MilvusClient loggingDbClient)
{
    // Use clients...
}

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

Configuration

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

Tip

The default use is root and the default password is Milvus. To configure a different password in the Milvus container, see Handling credentials and passing other parameters for the Milvus resource. Use the following techniques to configure consuming client apps in your .NET Aspire solution with the same password or other settings.

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:Non-default-P@ssw0rd"
  }
}

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 MilvusClientSettings from configuration by using the Aspire:Milvus:Client key. The following snippet is an example of a appsettings.json that configures some of the options:

{
  "Aspire": {
    "Milvus": {
      "Client": {
        "Endpoint": "http://localhost:19530/",
        "Database": "milvusdb",
        "Key": "root:Non-default-P@ssw0rd",
        "DisableHealthChecks": false
      }
    }
  }
}

For the complete Milvus client integration JSON schema, see Aspire.Milvus.Client/ConfigurationSchema.json.

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",
    static settings => settings.Key = "root:Non-default-P@ssw0rd");

Client integration 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:

• Adds the health check when MilvusClientSettings.DisableHealthChecks is false, which attempts to connect to the Milvus server.
• 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

Tracing

The .NET Aspire Milvus database integration doesn't currently emit tracing activities because they are not supported by the Milvus.Client library.

Metrics

The .NET Aspire Milvus database integration doesn't currently emit metrics because they are not supported by the Milvus.Client library.

See also

• Milvus
• Milvus GitHub repo
• Milvus .NET SDK
• .NET Aspire integrations
• .NET Aspire GitHub repo