Condividi tramite

Integrazione .NET Aspire Pomelo MySQLEntity Framework Core

  • Articolo

Include:,,, l'integrazione dell'hosting e ,,Client, l'integrazione

MySQL è un sistema RDBMS (Relational Database Management System) open source che usa Structured Query Language (SQL) per gestire e modificare i dati. Viene impiegato in molti ambienti diversi, da progetti di piccole dimensioni a sistemi aziendali su larga scala ed è una scelta comune per ospitare i dati che supportano i microservizi in un'applicazione nativa del cloud. L'integrazione .NET Aspire Pomelo MySQLEntity Framework Core permette di connettersi ai database MySQL esistenti o creare nuove istanze da .NET con l'immagine del contenitore mysql.

Integrazione del servizio di hosting

L'integrazione di hosting MySQL modella il server come tipo MySqlServerResource e il database come tipo MySqlDatabaseResource. Per accedere a questi tipi e API, aggiungere il pacchetto NuGet 📦Aspire.Hosting.MySql nel progetto host dell'app.

dotnet add package Aspire.Hosting.MySql

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere MySQL risorsa server e risorsa di database

Nel progetto host dell'app, invocare AddMySql per aggiungere e restituire un generatore di risorse MySQL. Esegui una chiamata concatenata al generatore di risorse restituito fino a AddDatabaseper aggiungere una risorsa di database 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...

Nota

L'avvio del contenitore SQL Server è lento, quindi è consigliabile usare un ciclo di vita persistente per evitare inutili riavvii. Per ulteriori informazioni, vedere la durata delle risorse del contenitore .

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine mysql, crea una nuova istanza MySQL nel computer locale. Per aggiungere un database viene usato un riferimento al generatore di risorse MySQL (la variabile mysql). Il database viene denominato mysqldb e quindi aggiunto al ExampleProject. La risorsa MySQL include le credenziali predefinite con un username di root e un password casuale generato usando il metodo CreateDefaultPasswordParameter.

Quando viene eseguito l'host dell'app, la password viene archiviata nell'archivio protetto dell'host dell'app. Viene aggiunto alla sezione Parameters, ad esempio:

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

Il nome del parametro è mysql-password, ma in realtà è sufficiente formattare il nome della risorsa con un suffisso -password. Per altre informazioni, vedere Archiviazione sicura dei segreti dell'app in fase di sviluppo in ASP.NET Core e Aggiungere una risorsa MySQL con parametri.

Il metodo WithReference configura una connessione nel ExampleProject denominato mysqldb.

Suggerimento

Se preferisci connetterti a un server MySQL esistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere una risorsa MySQL con un volume di dati

Per aggiungere un volume di dati alla risorsa SQL Server, chiamare il metodo WithDataVolume nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati del server MySQL al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /var/lib/mysql del contenitore SQL Server e, quando non viene specificato un parametro name, il nome viene generato a caso. Per ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai montaggi bind , consulta la documentazione Docker: Volumi.

Avvertimento

La password viene archiviata nel volume di dati. Quando si usa un volume di dati e se la password viene modificata, non funzionerà fino a quando non si elimina il volume.

Aggiungere una risorsa MySQL con un bind mount dei dati

Per aggiungere un punto di montaggio per l'associazione dati alla risorsa MySQL, chiamare il metodo 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...

Importante

I montaggi di bind dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretti dei file sul sistema host, rendendoli ideali per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere i dati MySQL persistenti tra i riavvii dei container. Il data bind mount è montato al percorso C:\MySql\Data su Windows (o su /MySql/Data nel percorso Unix) sulla macchina host nel contenitore MySQL. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.

Aggiungere MySQL risorsa con parametri

Quando vuoi specificare esplicitamente una password root MySQL, puoi passarla come parametro. Si consideri l'esempio alternativo seguente:

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

Per altre informazioni, vedere Parametri esterni.

Aggiungere una risorsa PhpMyAdmin

phpMyAdmin è uno strumento di amministrazione diffuso basato sul Web per MySQL. È possibile usarlo per esplorare e modificare MySQL oggetti quali database, tabelle, viste e indici. Per usare phpMyAdmin all'interno della soluzione .NET.NET Aspire, chiamare il metodo WithPhpMyAdmin. Questo metodo aggiunge una nuova risorsa contenitore alla soluzione che ospita phpMyAdmin e la connette al contenitore 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...

Quando si esegue la soluzione, il pannello di controllo .NET.NET Aspire visualizza le risorse phpMyAdmin con un endpoint. Selezionare il collegamento all'endpoint per visualizzare phpMyAdmin in una nuova scheda del browser.

Verifica dell'integrità delle integrazioni di hosting

L'integrazione dell'hosting MySQL aggiunge automaticamente un controllo dello stato di integrità per la risorsa MySQL. Il controllo di integrità verifica che il server MySQL sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.MySql.

Client integrazione

Per iniziare a usare l'integrazione di .NET Aspire Pomelo MySQL Entity Framework, installare il 📦Aspire. Pomelo.EntityFrameworkCore.MySql pacchetto NuGet nel progetto che utilizza il client, ovvero il progetto per l'applicazione che usa il client MySQLEntity Framework Core.

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere un contesto di database MySQL

Nel file Program.cs del progetto che utilizza il client chiamare il metodo di estensione AddMySqlDbContext su qualsiasi IHostApplicationBuilder per registrare un DbContext da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

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

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa di database SQL Server nel progetto host dell'app. In altre parole, quando si chiama AddDatabase e si specifica un nome di mysqldb lo stesso nome deve essere usato quando si chiama AddMySqlDbContext. Per altre informazioni, vedere Aggiungere MySQL risorsa server e risorsa del database.

Per recuperare un oggetto ExampleDbContext da un servizio:

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

Per ulteriori informazioni sull'iniezione di dipendenze, vedere .NET iniezione di dipendenze.

Arricchire un contesto di database MySQL

È consigliabile usare il metodo Entity Framework standard per ottenere un contesto di database e aggiungerlo al contenitore di inserimento delle dipendenze:

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

Nota

Il nome della stringa di connessione passato al metodo GetConnectionString deve corrispondere al nome usato quando si aggiunge la risorsa MySQL nel progetto host dell'app. Per altre informazioni, vedere Aggiungere MySQL risorsa server e risorsa del database.

È possibile avere maggiore flessibilità quando si crea il contesto del database in questo modo, ad esempio:

  • È possibile riutilizzare il codice di configurazione esistente per il contesto del database senza riscriverlo per .NET.NET Aspire.
  • È possibile usare gli intercettori Entity Framework Core per modificare le operazioni del database.
  • È possibile scegliere di non usare l'aggregazione del contesto Entity Framework Core, che può avere prestazioni migliori in alcune circostanze.

Se utilizzi questo metodo, puoi migliorare il contesto del database con tentativi in stile .NET.NET Aspire, controlli di integrità, logging e funzionalità di telemetria chiamando il metodo EnrichMySqlDbContext:

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

Il parametro settings è un'istanza della classe PomeloEntityFrameworkCoreMySqlSettings.

Configurazione

L'integrazione .NET Aspire Pomelo MySQLEntity Framework Core offre più opzioni per configurare la connessione al database in base ai requisiti e alle convenzioni del tuo progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama builder.AddMySqlDatabaseDbContext<TContext>():

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

La stringa di connessione verrà quindi recuperata dalla sezione di configurazione ConnectionStrings:

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

Il EnrichMySqlDbContext non userà la sezione di configurazione ConnectionStrings perché prevede che un DbContext venga registrato nel momento in cui viene chiamato.

Per altre informazioni, vedere la documentazione MySqlConnector: ConnectionString.

Usare i provider di configurazione

L'integrazione .NET Aspire Pomelo MySQLEntity Framework Core supporta Microsoft.Extensions.Configuration. Carica il PomeloEntityFrameworkCoreMySqlSettings dai file di configurazione, ad esempio appsettings.json, utilizzando la chiave Aspire:Pomelo:EntityFrameworkCore:MySql.

L'esempio seguente illustra un appsettings.json che configura alcune delle opzioni disponibili:

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

Per lo schema completo dell'integrazione MySQLJSON, vedere Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<PomeloEntityFrameworkCoreMySqlSettings> per configurare alcune o tutte le opzioni inline, ad esempio per disabilitare i controlli di integrità dal codice:

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

o

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

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni client .NET.NET Aspire hanno i controlli di integrità abilitati per tutti i servizi. Analogamente, molte integrazioni di hosting .NET.NET Aspire abilitano anche gli endpoint di controllo dell'integrità. Per altre informazioni, vedere:

Integrazione .NET Aspire Pomelo MySQLEntity Framework Core:

  • Aggiunge il controllo dell'integrità quando PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecks è false, che chiama il metodo EF Core di CanConnectAsync.
  • Si integra con l'endpoint HTTP /health, il quale specifica che tutti i controlli di integrità registrati devono essere superati con successo affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireMySQLEntity Framework Core Pomelo usa le categorie di log seguenti:

  • 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

Tracciamento

L'integrazione .NET Aspire Pomelo MySQLEntity Framework Core genererà le attività di traccia seguenti usando OpenTelemetry:

  • MySqlConnector

Metriche

L'integrazione .NET AspireMySQL pomelo Entity Framework Core supporta attualmente le metriche seguenti:

  • 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

Vedere anche