Integrazione .NET Aspire Pomelo MySQLEntity Framework Core

include:integrazione dell'hosting e Client 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 dell'hosting

Il MySQL che ospita l'integrazione modella il server come tipo di MySqlServerResource e il database come tipo di 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

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

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

Aggiungere la risorsa MySQLserver e la 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...

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

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 MySQLserver al di fuori del ciclo di vita del contenitore. Il volume dei dati è montato nel percorso /var/lib/mysql del contenitore SQL Server e, quando un parametro name non viene fornito, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai montaggi bind, vedere i Docker docs: Volumi.

Aggiungere una risorsa MySQL con un montaggio di associazione dati

Per aggiungere un punto di montaggio 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...

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati MySQL tra i riavvii del contenitore. Il data bind mount viene montato su C:\MySql\Data su Windows (o su /MySql/Data nel percorso di Unix) sul computer host nel contenitore MySQL. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: 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.

Hosting dei controlli di integrità dell'integrazione

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

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

Client integrazione

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

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

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

Aggiungere un contesto di database MySQL

Nel file Program.cs del progetto client-consuming, chiama il metodo di estensione AddMySqlDbContext su qualsiasi IHostApplicationBuilder per registrare un DbContext da usare tramite il contenitore per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

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

Per recuperare un oggetto ExampleDbContext da un servizio:

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

Per altre informazioni sull'inserimento delle dipendenze, vedere .NET 'inserimento delle dipendenze.

Aggiungere un contesto di database MySQL con arricchimento

Per arricchire il DbContext con servizi aggiuntivi, come ritentativi automatici, controlli di integrità, registrazione log e telemetria, chiamare il metodo EnrichMySqlDbContext.

builder.EnrichMySqlDbContext<ExampleDbContext>(
    connectionName: "mysqldb",
    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);

Controlli della salute

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano controlli di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

Integrazione .NET Aspire Pomelo MySQLEntity Framework Core:

• Aggiunge il controllo dell'integrità quando PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecks è false, che chiama il metodo CanConnectAsync di EF Core.
• Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere superati perché l'app possa essere considerata pronta ad accettare 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 MySQLEntity Framework Core.NET Aspire 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 MySQLEntity Framework Core pomelo .NET Aspire 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

• MySQL di database
• Entity Framework Core documenti
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repo