intégration .NET Aspire Pomelo MySQLEntity Framework Core

inclut :intégration d’hébergement et Client intégration

MySQL est un système de gestion de base de données relationnelle open source (SGBDR) qui utilise le langage SQL (Structured Query Language) pour gérer et manipuler des données. Il est utilisé dans un grand nombre d’environnements différents, de petits projets à des systèmes d’entreprise à grande échelle et il est un choix populaire d’héberger des données qui sous-tendent les microservices dans une application native cloud. L’intégration .NET Aspire Pomelo MySQLEntity Framework Core vous permet de vous connecter à des bases de données MySQL existantes ou de créer de nouvelles instances à partir de .NET avec l’image conteneur mysql.

Intégration de l’hébergement

Le modèle d'intégration MySQL représente le serveur comme un type MySqlServerResource et la base de données comme un type MySqlDatabaseResource. Pour accéder à ces types et API, ajoutez le package NuGet 📦Aspire.Hosting.MySql dans le projet hôte de l'application .

.NET CLI

dotnet add package Aspire.Hosting.MySql

packageReference

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

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages dans les applications .NET.

Ajouter MySQL ressource de serveur et ressource de base de données

Dans votre projet hôte d’application, appelez AddMySql pour ajouter et retourner un générateur de ressources MySQL. Enchaînez un appel au constructeur de ressources retourné à AddDatabaseafin d'ajouter une ressource de base de données 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...

Note

Le conteneur SQL Server est lent à démarrer. Il est donc préférable d’utiliser une durée de vie persistante pour éviter les redémarrages inutiles. Pour plus d’informations, consultez la durée de vie des ressources du conteneur.

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image mysql, il crée une instance de MySQL sur votre ordinateur local. Une référence à votre générateur de ressources MySQL (la variable mysql) est utilisée pour ajouter une base de données. La base de données est nommée mysqldb, puis ajoutée au ExampleProject. La ressource MySQL inclut les informations d’identification par défaut avec une username de root et une password aléatoire générée à l’aide de la méthode CreateDefaultPasswordParameter.

Lorsque l’hôte de l’application s’exécute, le mot de passe est stocké dans le répertoire de secrets de l’hôte d’application. Elle est ajoutée à la section Parameters, par exemple :

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

Le nom du paramètre est mysql-password, mais il suffit de mettre en forme le nom de la ressource avec un suffixe -password. Pour plus d’informations, consultez Stockage sécurisé des secrets d’application en développement dans ASP.NET Core et Ajoutez la ressource MySQL avec les paramètres.

La méthode WithReference configure une connexion dans le ExampleProject nommé mysqldb.

Pourboire

Si vous préférez vous connecter à un serveur MySQL existant, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter une ressource MySQL avec un volume de données

Pour ajouter un volume de données à la ressource SQL Server, appelez la méthode WithDataVolume sur la ressource 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...

Le volume de données est utilisé pour conserver les données du serveur MySQL en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin d’accès /var/lib/mysql dans le conteneur SQL Server et lorsqu’un paramètre name n’est pas fourni, le nom est généré de manière aléatoire. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison , consultez Docker documentation : Volumes.

Avertissement

Le mot de passe est stocké dans le volume de données. Lors de l’utilisation d’un volume de données et si le mot de passe change, il ne fonctionnera pas tant que vous ne supprimez pas le volume.

Ajouter une ressource MySQL avec un montage avec liaison de données

Pour ajouter un montage de liaison de données à la ressource MySQL, appelez la méthode 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...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , qui offrent de meilleures performances, de la portabilité et de la sécurité, les rendant ainsi plus adaptés aux environnements de production. Toutefois, les montages de liaison permettent un accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests dans lesquels des modifications en temps réel sont nécessaires.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données MySQL entre les redémarrages de conteneur. Le montage de liaison des données est monté sur le chemin d’accès C:\MySql\Data sous Windows (ou /MySql/Data sur Unix) sur l’ordinateur hôte dans le conteneur MySQL. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Ajouter MySQL ressource avec des paramètres

Lorsque vous souhaitez fournir explicitement un mot de passe racine MySQL, vous pouvez le transmettre en tant que paramètre. Prenons l’exemple de remplacement suivant :

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);

Pour plus d’informations, consultez paramètres externes.

Ajouter une ressource PhpMyAdmin

phpMyAdmin est un outil d’administration web populaire pour MySQL. Vous pouvez l’utiliser pour parcourir et modifier des objets MySQL tels que des bases de données, des tables, des vues et des index. Pour utiliser phpMyAdmin dans votre solution .NET.NET Aspire, appelez la méthode WithPhpMyAdmin. Cette méthode ajoute une nouvelle ressource de conteneur à la solution qui héberge phpMyAdmin et la connecte au conteneur 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...

Lorsque vous exécutez la solution, le tableau de bord .NET.NET Aspire affiche les ressources phpMyAdmin avec un point de terminaison. Sélectionnez le lien vers le point de terminaison pour afficher phpMyAdmin dans un nouvel onglet de navigateur.

Vérifications d’intégrité de l’intégration d’hébergement

L’intégration d’hébergement MySQL ajoute automatiquement un contrôle d’intégrité pour la ressource MySQL. La vérification d’intégrité vérifie que le serveur MySQL est en cours d’exécution et qu’une connexion peut être établie à celle-ci.

L’intégration de l’hébergement s’appuie sur le package NuGet 📦 AspNetCore.HealthChecks.MySql.

intégration de Client

Pour commencer à utiliser l’intégration .NET Aspire Pomelo MySQL Entity Framework, installez le package NuGet 📦Aspire.Pomelo.EntityFrameworkCore.MySql dans le projet consommateur, c'est-à-dire le projet de l’application qui utilise le client MySQLEntity Framework Core.

.NET CLI

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

packageReference

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

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages dans les applications .NET.

Ajouter un contexte de base de données MySQL

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddMySqlDbContext sur n’importe quel IHostApplicationBuilder pour inscrire un DbContext à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddMySqlDbContext<ExampleDbContext>(connectionName: "mysqldb");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource de base de données SQL Server dans le projet hôte de l’application. En d’autres termes, lorsque vous appelez AddDatabase et fournissez un nom de mysqldb ce même nom doit être utilisé lors de l’appel de AddMySqlDbContext. Pour plus d’informations, consultez Ajouter MySQL ressource serveur et ressource de base de données.

Pour récupérer l'objet ExampleDbContext à partir d’un service :

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

Pour plus d’informations sur l’injection de dépendances, consultez .NETinjection de dépendances.

Enrichir un contexte de base de données MySQL

Vous préférez peut-être utiliser la méthode Entity Framework standard pour obtenir un contexte de base de données et l’ajouter au conteneur d’injection de dépendances :

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseMySql(builder.Configuration.GetConnectionString("mysqldb")
        ?? throw new InvalidOperationException("Connection string 'mysqldb' not found.")));

Note

Le nom de la chaîne de connexion que vous passez à la méthode GetConnectionString doit correspondre au nom utilisé lors de l’ajout de la ressource MySQL dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter MySQL ressource serveur et ressource de base de données.

Vous disposez d’une plus grande flexibilité lorsque vous créez le contexte de base de données de cette façon, par exemple :

• Vous pouvez réutiliser le code de configuration existant pour le contexte de base de données sans le réécrire pour .NET.NET Aspire.
• Vous pouvez utiliser les intercepteurs Entity Framework Core pour modifier les opérations de base de données.
• Vous pouvez choisir de ne pas utiliser le regroupement de contextes Entity Framework Core, ce qui peut mieux fonctionner dans certaines circonstances.

Si vous utilisez cette méthode, vous pouvez améliorer le contexte de la base de données avec des réessais de style .NET.NET Aspire, des contrôles de l'intégrité, la journalisation, et des fonctionnalités de télémétrie en appelant la méthode EnrichMySqlDbContext :

builder.EnrichMySqlDbContext<ExampleDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

Le paramètre settings est une instance de la classe PomeloEntityFrameworkCoreMySqlSettings.

Configuration

L’intégration .NET Aspire Pomelo MySQLEntity Framework Core fournit plusieurs options pour configurer la connexion de base de données en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de builder.AddMySqlDatabaseDbContext<TContext>():

builder.AddMySqlDatabaseDbContext<MyDbContext>("mysql");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

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

La EnrichMySqlDbContext n’utilise pas la section de configuration ConnectionStrings, car elle s’attend à ce qu’un DbContext soit inscrit au point où il est appelé.

Pour plus d’informations, consultez la documentation MySqlConnector : ConnectionString.

Utiliser des fournisseurs de configuration

L’intégration .NET Aspire Pomelo MySQLEntity Framework Core prend en charge Microsoft.Extensions.Configuration. Il charge le PomeloEntityFrameworkCoreMySqlSettings à partir de fichiers de configuration tels que appsettings.json à l’aide de la clé Aspire:Pomelo:EntityFrameworkCore:MySql.

L’exemple suivant montre une appsettings.json qui configure certaines des options disponibles :

{
  "Aspire": {
    "Pomelo": {
      "EntityFrameworkCore": {
        "MySql": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Pour obtenir le schéma complet MySQL d’intégration JSON, consultez Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<PomeloEntityFrameworkCoreMySqlSettings> pour configurer certaines ou toutes les options en ligne, par exemple pour désactiver les contrôles de l'état de santé depuis le code :

builder.AddMySqlDbContext<MyDbContext>(
    "mysqldb",
    static settings => settings.DisableHealthChecks = true);

ou

builder.EnrichMySqlDbContext<MyDbContext>(
    static settings => settings.DisableHealthChecks = true);

Client contrôles de santé de l’intégration

Par défaut, les intégrations de clients .NET.NET Aspire ont les contrôles de santé activés pour tous les services. De même, de nombreuses intégrations d'hébergement .NET.NET Aspire activent également les endpoints de vérification de santé. Pour plus d’informations, consultez :

• .NET vérification de l'état de santé des applications en C#
• vérifications de santé dans ASP.NET Core

Intégration .NET Aspire Pomelo MySQLEntity Framework Core :

• Ajoute la vérification de l'état de santé lorsque PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecks est false, qui appelle la méthode EF Core de CanConnectAsync.
• S’intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications d’intégrité inscrites doivent passer pour que l’application soit considérée comme prête à accepter le trafic.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent de manière automatique la journalisation, le suivi et les métriques, parfois appelés les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET Aspire Pomelo MySQLEntity Framework Core utilise les catégories de journaux suivantes :

• Microsoft.EntityFrameworkCore.ChangeTracking
• Microsoft.EntityFrameworkCore.Database.Command
• Microsoft.EntityFrameworkCore.Database.Connection
• Microsoft.EntityFrameworkCore.Database.Transaction
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

Traçage

L’intégration Pomelo .NET AspireMySQLEntity Framework Core émet les activités de suivi suivantes à l’aide de OpenTelemetry:

• MySqlConnector

Métriques

L’intégration .NET Aspire Pomelo MySQLEntity Framework Core prend actuellement en charge les métriques suivantes :

• 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

Voir aussi

• MySQL base de données
• Entity Framework Core docs
• intégrations .NET.NET Aspire
• .NET Aspire GitHub dépôt