.NET Aspire MySQL database integration
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
.NET Aspire