Edit

Share via

.NET Aspire MySQL database integration

  • Article

In this article, you learn how to use the .NET Aspire MySQL database integration. The Aspire.MySqlConnector library:

  • Registers a MySqlDataSource in the DI container for connecting MySQL database.
  • Automatically configures the following:
    • Health checks, logging and telemetry to improve app monitoring and diagnostics

Prerequisites

  • MySQL database and connection string for accessing the database.

Get started

To get started with the .NET Aspire MySQL database integration, install the 📦 Aspire.MySqlConnector NuGet package.

dotnet add package Aspire.MySqlConnector

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

Example usage

In the Program.cs file of your client-consuming project, call the AddMySqlDataSource extension to register a MySqlDataSource for use via the dependency injection container.

builder.AddMySqlDataSource("mysqldb");

To retrieve your MySqlDataSource object, consider the following example service:

public class ExampleService(MySqlDataSource dataSource)
{
    // Use dataSource...
}

After adding a MySqlDataSource, you can require the MySqlDataSource instance using DI.

App host usage

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

dotnet add package Aspire.Hosting.MySql

In your app host project, register a MySql database and consume the connection using the following methods:

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql");
var mysqldb = mysql.AddDatabase("mysqldb");

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

When you want to explicitly provide a root MySQL password, you can provide it as a parameter. Consider the following alternative example:

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

var mysql = builder.AddMySql("mysql", password);
var mysqldb = mysql.AddDatabase("mysqldb");

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

For more information, see External parameters.

Configuration

The .NET Aspire MySQL database integration provides multiple configuration approaches and options to meet 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.AddMySqlDataSource():

builder.AddMySqlDataSource("MySqConnection");

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

{
  "ConnectionStrings": {
    "MySqConnection": "Server=mysql;Database=mysqldb"
  }
}

For more information on how to format this connection string, see MySqlConnector: ConnectionString documentation.

Use configuration providers

The .NET Aspire MySQL database supports Microsoft.Extensions.Configuration. It loads the MySqlConnectorSettings from configuration files such as appsettings.json by using the Aspire:MySqlConnector key. If you have set up your configurations in the Aspire:MySqlConnector section, you can just call the method without passing any parameter.

The following example shows an appsettings.json file that configures some of the available options:

{
  "Aspire": {
    "MySqlConnector": {
      "DisableHealthChecks": true,
      "DisableTracing": true
    }
  }
}

Use inline configurations

You can also pass the Action<MySqlConnectorSettings> delegate to set up some or all the options inline, for example to disable health checks from code:

builder.AddMySqlDataSource("mysql",
    static settings => settings.DisableHealthChecks  = true);

Configuration options

Here are the configurable options with corresponding default values:

Name Description
ConnectionString The connection string of the MySQL database database to connect to.
DisableHealthChecks A boolean value that indicates whether the database health check is disabled or not.
DisableTracing A boolean value that indicates whether the OpenTelemetry tracing is disabled or not.
DisableMetrics A boolean value that indicates whether the OpenTelemetry metrics are disabled or not.

Health checks

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

By default, the .NET Aspire MySQL database integration handles the following:

  • Adds a MySqlHealthCheck, which verifies that a connection can be made commands can be run against the MySql database.
  • Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic

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.

See also