.NET Aspire Pomelo MySQLEntity Framework Core Integration

umfasst:Hosting-Integration und Client Integration

MySQL ist ein Open Source Relational Database Management System (RDBMS), das die Structured Query Language (SQL) zum Verwalten und Bearbeiten von Daten verwendet. Es wird in vielen verschiedenen Umgebungen eingesetzt, von kleinen Projekten bis hin zu groß angelegten Enterprise-Systemen und es ist eine beliebte Wahl, Daten zu hosten, die Microservices in einer cloudeigenen Anwendung unterstützen. Die .NET Aspire Pomelo MySQLEntity Framework Core Integration ermöglicht es, eine Verbindung mit vorhandenen MySQL Datenbanken herzustellen oder neue Instanzen aus .NET mit dem mysql Containerimagezu erstellen.

Hosting-Integration

Die MySQL-Hostintegrationsmodelle ordnen das server als Typ MySqlServerResource und die Datenbank als Typ MySqlDatabaseResource zu. Um auf diese Typen und APIs zuzugreifen, fügen Sie das 📦Aspire.Hosting.MySql NuGet-Paket zum App-Host Projekt hinzu.

dotnet add package Aspire.Hosting.MySql

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

Weitere Informationen finden Sie unter dotnet add package oder Verwaltung von Paketabhängigkeiten in .NET-Anwendungen.

Hinzufügen von MySQLserver Ressourcen und Datenbankressourcen.

Rufen Sie in Ihrem App-Hostprojekt AddMySql auf, um einen MySQL Ressourcen-Generator hinzuzufügen und zurückzugeben. Verketten Sie einen Aufruf des zurückgegebenen Ressourcen-Generators an AddDatabase, um eine MySQL Datenbankressource hinzuzufügen.

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

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem mysql-Image gezeigt, wird eine neue MySQL Instanz auf dem lokalen Computer erstellt. Ein Verweis auf den MySQL Ressourcen-Generator (die mysql Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank wird mysqldb genannt und dann zu ExampleProjecthinzugefügt. Die MySQL-Ressource enthält Standardanmeldeinformationen mit einem username von root und einem zufälligen password, der mithilfe der CreateDefaultPasswordParameter-Methode generiert wurde.

Wenn der App-Host ausgeführt wird, wird das Kennwort im geheimen Speicher des App-Hosts gespeichert. Sie wird dem Abschnitt Parameters hinzugefügt, z. B.:

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

Der Name des Parameters ist mysql-password, aber tatsächlich wird nur der Ressourcenname mit einem -password Suffix formatiert. Weitere Informationen finden Sie unter "Sichere Speicherung von App-Geheimnissen in der Entwicklung" in ASP.NET Core, und "Ressource mit Parametern hinzufügen" MySQL.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens mysqldb.

Hinzufügen einer MySQL-Ressource mit einem Datenvolumen

Rufen Sie die WithDataVolume-Methode für die SQL Server-Ressource auf, um der SQL Server-Ressource ein Datenvolume hinzuzufügen:

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

Das Datenvolumen wird verwendet, um die MySQLserver Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird am /var/lib/mysql Pfad im Container SQL Server bereitgestellt. Wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Daten-Volumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Volumes.

Hinzufügen einer MySQL Ressource mit einer Datenbindungs-Bereitstellung

Rufen Sie die WithDataBindMount-Methode auf, um der MySQL-Ressource eine Datenbindung hinzuzufügen:

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

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die MySQL Daten über Containerneustarts hinweg beizubehalten. Die Datenbindungsbereitstellung wird auf dem C:\MySql\Data unter Windows (oder /MySql/Data auf Unix) Pfad auf dem Hostcomputer im container MySQL bereitgestellt. Weitere Informationen zu Datenbindungs-Bereitstellungen finden Sie unter Docker Docs: Binden von Bereitstellungen.

Ressource MySQL mit Parametern hinzufügen

Wenn Sie ein Root-MySQL Kennwort explizit angeben möchten, können Sie es als Parameter übergeben. Betrachten Sie das folgende alternative Beispiel:

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

Weitere Informationen finden Sie unter Externe Parameter.

Hinzufügen einer PhpMyAdmin-Ressource

phpMyAdmin ist ein beliebtes webbasiertes Verwaltungstool für MySQL. Sie können es verwenden, um MySQL Objekte wie Datenbanken, Tabellen, Ansichten und Indizes zu durchsuchen und zu ändern. Um phpMyAdmin in Ihrer .NET.NET Aspire Lösung zu verwenden, rufen Sie die WithPhpMyAdmin-Methode auf. Diese Methode fügt der Lösung, die phpMyAdmin hostt, eine neue Containerressource hinzu und verbindet sie mit dem MySQL-Container:

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

Wenn Sie die Lösung ausführen, zeigt das .NET.NET Aspire-Dashboard die phpMyAdmin-Ressourcen mit einem Endpunkt an. Wählen Sie den Endpunkt-Link aus, um phpMyAdmin in einem neuen Browsertab anzuzeigen.

Durchführung von Integrations-Gesundheitsprüfungen

Die MySQL Hostingintegration fügt automatisch eine Integritätsprüfung für die MySQL Ressource hinzu. Die Integritätsprüfung überprüft, ob die MySQLserver ausgeführt wird und ob eine Verbindung hergestellt werden kann.

Die Hosting-Integration basiert auf den 📦 AspNetCore.HealthChecks und demMySql NuGet-Paket.

Client Integration

Um mit der Integration von .NET Aspire Pomelo MySQL Entity Framework zu beginnen, installieren Sie das 📦Aspire. Pomelo.EntityFrameworkCore.MySql NuGet-Paket im Projekt, das clientverwendet, d. h. im Projekt für die Anwendung, welche MySQLEntity Framework Coreclientnutzt.

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

Weitere Informationen finden Sie unter dotnet add package oder Verwaltung von Paketabhängigkeiten in .NET-Anwendungen.

Hinzufügen eines MySQL Datenbankkontexts

Rufen Sie in der Datei Program.cs des client-verbrauchenden Projekts die AddMySqlDbContext-Erweiterungsmethode auf jedem IHostApplicationBuilder auf, um eine DbContext zur Verwendung im Dependency Injection Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

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

So rufen Sie ExampleDbContext Objekt aus einem Dienst ab:

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

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Fügen Sie einen MySQL-Datenbankkontext mit Anreicherung hinzu.

Um die DbContext mit zusätzlichen Diensten zu bereichern, wie z.B. automatische Wiederholungen, Integritätsprüfungen, Protokollierung und Telemetrie, rufen Sie die EnrichMySqlDbContext-Methode auf.

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

Der settings-Parameter ist eine Instanz der PomeloEntityFrameworkCoreMySqlSettings Klasse.

Konfiguration

Die .NET Aspire Pomelo MySQLEntity Framework Core Integration bietet mehrere Optionen zum Konfigurieren der Datenbankverbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden einer Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddMySqlDatabaseDbContext<TContext>()den Namen der Verbindungszeichenfolge angeben:

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

Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings abgerufen.

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

Der EnrichMySqlDbContext wird den ConnectionStrings-Konfigurationsabschnitt nicht verwenden, da erwartet wird, dass eine DbContext zum Zeitpunkt des Aufrufs registriert wird.

Weitere Informationen finden Sie in der MySqlConnector: ConnectionString-Dokumentation.

Konfigurationsanbieter verwenden

Die .NET Aspire Pomelo MySQLEntity Framework Core Integration unterstützt Microsoft.Extensions.Configuration. Es lädt die PomeloEntityFrameworkCoreMySqlSettings aus Konfigurationsdateien wie appsettings.json mithilfe des Aspire:Pomelo:EntityFrameworkCore:MySql-Schlüssels.

Das folgende Beispiel zeigt ein appsettings.json-Gerät, das einige der verfügbaren Optionen konfiguriert.

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

Die vollständige MySQL Integration JSON Schemas finden Sie unter Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Verwenden Sie Inline-Delegaten

Sie können auch den Action<PomeloEntityFrameworkCoreMySqlSettings> Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. um Integritätsprüfungen aus Code zu deaktivieren:

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

oder

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

Gesundheitsprüfungen

Standardmäßig aktivieren .NET.NET Aspire Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Die .NET Aspire Pomelo MySQLEntity Framework Core Integration:

• Fügt die Integritätsprüfung hinzu, wenn PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecksfalseist, der die CanConnectAsync-Methode von EF Coreaufruft.
• Integriert wird mit dem /health HTTP-Endpunkt, der angibt, dass alle registrierten Integritätsprüfungen bestehen müssen, damit die App bereit ist, um Datenverkehr anzunehmen.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Logging-, Tracing- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zu Integrationsobservability und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst unterstützen einige Integrationen möglicherweise nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Konfiguration beschrieben werden.

Protokollierung

Die .NET Aspire Pomelo MySQLEntity Framework Core Integration verwendet die folgenden Protokollkategorien:

• 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

Verfolgung

Die .NET Aspire Pomelo MySQLEntity Framework Core Integration gibt die folgenden Tracing-Aktivitäten mithilfe von OpenTelemetryaus.

• MySqlConnector

Metriken

Die .NET Aspire Pomelo MySQLEntity Framework Core Integration unterstützt derzeit die folgenden Metriken:

• 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

Siehe auch

• MySQL Datenbank
• Entity Framework Core Dokumente
• .NET .NET Aspire Integrationen
• .NET Aspire GitHub repo