Condividi tramite

integrazione di .NET AspireMySQL

  • Articolo

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 del database .NET AspireMySQL consente di connettersi ai database MySQL esistenti o di creare nuove istanze da .NET con l'immagine del contenitore mysql.

Integrazione 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 alle 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 del pacchetto in .NET applicazioni.

Aggiungere risorsa MySQLe risorsa di databaseserver

Nel progetto host dell'app, invocare AddMySql per aggiungere e restituire un generatore di risorse MySQL. Collega una chiamata al costruttore di risorse restituito 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 altre informazioni, vedere durata di vita 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 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.

Mancia

Se vuoi collegarti a un MySQLserveresistente, chiama AddConnectionString invece. 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 MySQLserver al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /var/lib/mysql nel contenitore SQL Server e quando non viene specificato un parametro name, il nome viene generato in modo casuale. 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 montaggio con associazione di dati

Per aggiungere un montaggio dell'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 bind mount 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 montaggi di associazione consentono l'accesso e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test dove sono necessarie modifiche in tempo reale.

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 montaggio di bind dei dati viene montato al percorso C:\MySql\Data su Windows (o al percorso /MySql/Data su Unix) nella macchina host nel contenitore MySQL. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

Aggiungere MySQL risorsa con parametri

Quando si desidera specificare in modo esplicito una password di root MySQL, è possibile 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 dashboard .NET.NET Aspire visualizza le risorse phpMyAdmin con un endpoint. Selezionare il collegamento all'endpoint per visualizzare phpMyAdmin in una nuova scheda del browser.

Controlli di integrità per l'integrazione di hosting

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

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

Client integrazione

Per iniziare a usare l'integrazione del database .NET AspireMySQL, installare il pacchetto NuGet 📦Aspire.MySqlConnector nel progetto clientdi utilizzo, ovvero il progetto per l'applicazione che usa il MySQLclient. L'integrazione MySQLclient registra un'istanza di MySqlConnector.MySqlDataSource che puoi usare per interagire con il MySQLserver.

dotnet add package Aspire.MySqlConnector

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze del pacchetto in .NET applicazioni.

Aggiungere un'origine dati MySQL

Nel file Program.cs del progetto client-consuming, chiamare il metodo di estensione AddMySqlDataSource per registrare un MySqlDataSource da utilizzare tramite il contenitore di iniezione delle dipendenze. Il metodo accetta un parametro connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa di database MySQL 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 AddMySqlDataSource. Per ulteriori informazioni, consultare Aggiungi la risorsa MySQLserver e la risorsa di database.

È quindi possibile recuperare l'istanza di MySqlConnector.MySqlDataSource tramite iniezione delle dipendenze. Ad esempio, per recuperare l'origine dati da un servizio di esempio:

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

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

Aggiungere un'origine dati MySQL con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di MySqlDataSource con nomi di connessione diversi. Per registrare le origini dati MySQL con chiave, chiamare il metodo AddKeyedMySqlDataSource:

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

Importante

Quando si usano i servizi con chiave, è previsto che la risorsa MySQL sia configurata con due database denominati, uno per il mainDb e uno per l'loggingDb.

È quindi possibile recuperare le istanze di MySqlDatSource usando l'inserimento delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per altre informazioni sui servizi con chiave, vedere .NET inserimento delle dipendenze: Servizi con chiave.

Configurazione

L'integrazione del database .NET AspireMySQL offre più opzioni per configurare la connessione in base ai requisiti e alle convenzioni del 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 AddMySqlDataSource metodo:

builder.AddMySqlDataSource(connectionName: "mysql");

La stringa di connessione viene quindi recuperata dalla sezione di configurazione ConnectionStrings:

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

Per altre informazioni su come formattare questa stringa di connessione, vedere MySqlConnector: documentazione di ConnectionString.

Utilizzare i provider di configurazione

L'integrazione del database .NET AspireMySQL supporta Microsoft.Extensions.Configuration. Carica il MySqlConnectorSettings dalla configurazione usando la chiave Aspire:MySqlConnector. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

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

Per lo schema completo dell'integrazione MySQLJSON, vedere Aspire. MySqlConnector/ConfigurationSchema.json.

Usare delegati inline

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

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

Client controlli di integrità dell'integrazione

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

Integrazione del database .NET AspireMySQL:

  • Aggiunge il controllo di integrità quando MySqlConnectorSettings.DisableHealthChecks è false, che verifica che sia possibile stabilire una connessione e che i comandi possano essere eseguiti nel database MySQL.
  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente la registrazione, la tracciabilità e le 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 AspireMySQL usa le categorie di log seguenti:

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

Tracciamento

L'integrazione .NET AspireMySQL emette le seguenti attività di tracciazione utilizzando OpenTelemetry:

  • MySqlConnector

Metriche

L'integrazione .NET AspireMySQL genererà le metriche seguenti usando 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

Vedere anche