integración de .NET AspireMySQL

Incluye:integración de hospedaje y Client integración

MySQL es un sistema de administración de bases de datos relacionales (RDBMS) de código abierto que usa lenguaje de consulta estructurado (SQL) para administrar y manipular datos. Se emplea en muchos entornos diferentes, desde proyectos pequeños hasta sistemas empresariales a gran escala y es una opción popular hospedar datos que respaldan microservicios en una aplicación nativa de nube. La integración de base de datos .NET AspireMySQL permite conectarse a bases de datos de MySQL existentes o crear nuevas instancias desde .NET con la imagen de contenedor mysql.

Integración de hospedaje

El modelo de integración de alojamiento MySQL modela al server como tipo MySqlServerResource y a la base de datos como tipo MySqlDatabaseResource. Para acceder a estos tipos y APIs, agregue el paquete de NuGet 📦Aspire.Hosting.MySql en el proyecto del host de aplicación de .

dotnet add package Aspire.Hosting.MySql

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

Para obtener más información, consulte dotnet add package o Manage package dependencies in .NET applications.

Agregar recurso MySQL, recursoserver y recurso de base de datos

En el proyecto host de tu aplicación, llama a AddMySql para añadir y devolver un constructor de recursos MySQL. Encadene una llamada al generador de recursos devuelto para AddDatabase, para agregar un recurso de base de datos de MySQL.

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithLifetime(ContainerLifetime.Persistent);

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

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

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

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de mysql, crea una nueva instancia de MySQL en el equipo local. Se usa una referencia al generador de recursos de MySQL (la variable mysql) para agregar una base de datos. La base de datos se denomina mysqldb y, a continuación, se agrega al ExampleProject. El recurso MySQL incluye credenciales predeterminadas con un username de root y un password aleatorio generado mediante el método CreateDefaultPasswordParameter.

Cuando se ejecuta el host de la aplicación, la contraseña se almacena en el almacén de secretos del host de la aplicación. Se agrega a la sección Parameters, por ejemplo:

{
  "Parameters:mysql-password": "<THE_GENERATED_PASSWORD>"
}

El nombre del parámetro es mysql-password, pero realmente solo da formato al nombre del recurso con un sufijo -password. Para obtener más información, consulte almacenamiento seguro de secretos de aplicación en desarrollo en ASP.NET Core y Agregar MySQL recurso con parámetros.

El método WithReference configura una conexión en el ExampleProject denominado mysqldb.

Agrega un recurso de MySQL con un volumen de datos

Para agregar un volumen de datos al recurso de SQL Server, llame al método WithDataVolume en el recurso SQL Server:

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithDataVolume();

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

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

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

El volumen de datos se utiliza para conservar los datos de MySQLserver fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta de acceso /var/lib/mysql dentro del contenedor SQL Server y, si no se proporciona un parámetro name, el nombre se genera de manera aleatoria. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a enlazar montajes, consulte Docker documentos: Volúmenes.

Agrega un recurso MySQL con una vinculación de datos

Para agregar una montura de enlace de datos al recurso de MySQL, llame al método WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithDataBindMount(source: @"C:\MySql\Data");

var db = sql.AddDatabase("mysqldb");

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

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

Los montajes de enlace de datos dependen del sistema de archivos del equipo host para persistir los datos de MySQL a través de los reinicios de los contenedores. El montaje de enlace de datos se realiza en C:\MySql\Data en Windows (o en /MySql/Data en Unix) en la máquina host en el contenedor MySQL. Para obtener más información sobre los montajes de enlace de datos, consulte los documentos Docker: Montajes de enlace.

Añadir el recurso MySQL con parámetros

Cuando desee proporcionar explícitamente una contraseña de raíz MySQL, puede pasarla como parámetro. Considere el siguiente ejemplo alternativo:

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

var mysql = builder.AddMySql("mysql", password)
                   .WithLifetime(ContainerLifetime.Persistent);

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

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

Para obtener más información, vea Parámetros externos.

Adición de un recurso PhpMyAdmin

phpMyAdmin es una popular herramienta de administración basada en web para MySQL. Puede usarlo para examinar y modificar MySQL objetos como bases de datos, tablas, vistas e índices. Para usar phpMyAdmin en la solución de .NET.NET Aspire, llame al método WithPhpMyAdmin. Este método agrega un nuevo recurso de contenedor a la solución que hospeda phpMyAdmin y lo conecta al contenedor de MySQL:

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithPhpMyAdmin();

var db = sql.AddDatabase("mysqldb");

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

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

Al ejecutar la solución, el tablero .NET.NET Aspire muestra los recursos phpMyAdmin con un punto de conexión. Seleccione el vínculo al punto de conexión para ver phpMyAdmin en una nueva pestaña del explorador.

Verificaciones de estado de integraciones de alojamiento

La integración de hospedaje MySQL agrega automáticamente una verificación del estado para el recurso MySQL. La comprobación de estado comprueba que el MySQLserver está en funcionamiento y que se puede establecer una conexión con él.

La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.MySql.

integración de Client

Para empezar a trabajar con la integración de base de datos de .NET AspireMySQL, instale el paquete NuGet 📦Aspire.MySqlConnector en el proyecto que consume client, es decir, en el proyecto de aplicación que utiliza MySQLclient. La integración de MySQLclient registra una instancia de MySqlConnector.MySqlDataSource que puede usar para interactuar con el MySQLserver.

dotnet add package Aspire.MySqlConnector

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

Para obtener más información, consulte dotnet add package o Administración de dependencias de paquetes en aplicaciones .NET.

Añadir un origen de datos de MySQL

En el archivo Program.cs del proyecto que consume client, llame al método de extensión AddMySqlDataSource para registrar un MySqlDataSource para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

A continuación, puede obtener la instancia MySqlConnector.MySqlDataSource mediante la inserción de dependencias. Por ejemplo, para recuperar el origen de datos de un servicio de ejemplo:

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

Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.

Agregar origen de datos MySQL claveada

Puede haber situaciones en las que quiera registrar varias instancias de MySqlDataSource con nombres de conexión diferentes. Para registrar los orígenes de datos con clave MySQL, llame al método AddKeyedMySqlDataSource:

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

A continuación, puede recuperar las instancias de MySqlDatSource mediante inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(
    [FromKeyedServices("mainDb")] MySqlDataSource mainDbConnection,
    [FromKeyedServices("loggingDb")] MySqlDataSource loggingDbConnection)
{
    // Use connections...
}

Para obtener más información sobre los servicios con claves específicas, consulte .NET inyección de dependencias: Servicios con claves específicas.

Configuración

La integración de base de datos .NET AspireMySQL proporciona varias opciones para configurar la conexión en función de los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar al método AddMySqlDataSource:

builder.AddMySqlDataSource(connectionName: "mysql");

A continuación, la cadena de conexión se recupera de la sección de configuración de ConnectionStrings:

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

Para obtener más información sobre cómo dar formato a esta cadena de conexión, consulte Documentación de MySqlConnector: ConnectionString.

Uso de proveedores de configuración

La integración de la base de datos .NET AspireMySQL admite Microsoft.Extensions.Configuration. Carga el MySqlConnectorSettings desde la configuración utilizando la clave Aspire:MySqlConnector. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

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

Para obtener el esquema completo MySQL de integración JSON, consulte Aspire.MySqlConnector/ConfigurationSchema.json.

Utilizar delegados en línea

También puede pasar el delegado de Action<MySqlConnectorSettings> para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar las comprobaciones de salud desde el código:

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

comprobaciones de estado de integración de Client

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan las comprobaciones de integridad de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración de la base de datos .NET AspireMySQL:

• Agrega la comprobación de estado cuando MySqlConnectorSettings.DisableHealthChecks es false, que comprueba que se puede realizar una conexión y que los comandos se pueden ejecutar en la base de datos MySQL.
• Se integra con el punto de conexión HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben pasar para que la aplicación se considere lista para aceptar el tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

La integración de .NET AspireMySQL usa las siguientes categorías de registro:

• MySqlConnector.ConnectionPool
• MySqlConnector.MySqlBulkCopy
• MySqlConnector.MySqlCommand
• MySqlConnector.MySqlConnection
• MySqlConnector.MySqlDataSource

Rastreo

La integración de .NET AspireMySQL emite las siguientes actividades de seguimiento mediante OpenTelemetry:

• MySqlConnector

Métricas

La integración de .NET AspireMySQL emitirá las métricas siguientes mediante OpenTelemetry:

• MySqlConnector
  • db.client.connections.create_time
  • db.client.connections.use_time
  • db.client.connections.wait_time
  • db.client.connections.idle.max
  • db.client.connections.idle.min
  • db.client.connections.max
  • db.client.connections.pending_requests
  • db.client.connections.timeouts
  • db.client.connections.usage

Consulte también

• base de datos MySQL
• ejemplo de contenedores de base de datos .NET.NET Aspire
• .NET .NET Aspire integraciones
• .NET Aspire GitHub del repositorio