Skip to content

Latest commit

 

History

History
162 lines (109 loc) · 5.85 KB

mysql-integration.md

File metadata and controls

162 lines (109 loc) · 5.85 KB
Raw
title description ms.topic ms.date
.NET Aspire MySQL database integration
This article describes the .NET Aspire MySQL database integration.
how-to
11/22/2024

.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.

.NET CLI

dotnet add package Aspire.MySqlConnector

PackageReference

<PackageReference Include="Aspire.MySqlConnector"
                  Version="*" />

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

Example usage

In the :::no-loc text="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

[!INCLUDE mysql-app-host]

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("mysql");

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

{
  "ConnectionStrings": {
    "mysql": "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 xref:Microsoft.Extensions.Configuration?displayProperty=fullName. It loads the MySqlConnectorSettings from configuration files such as :::no-loc text="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 :::no-loc text="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.

[!INCLUDE integration-health-checks]

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

[!INCLUDE integration-observability-and-telemetry]

See also