.NET Aspire-IntegrationMySQL-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. Mit der .NET AspireMySQL-Datenbankintegration können Sie vorhandene MySQL-Datenbanken verbinden oder neue Instanzen aus .NET mit dem mysql-Container-Imageerstellen.

Hosting-Integration

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

.NET CLI

dotnet add package Aspire.Hosting.MySql

PackageReference

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

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

Hinzufügen von MySQL- undserver-Ressourcen sowie Datenbankressource

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

Anmerkung

Der SQL Server Container beginnt langsam, daher empfiehlt es sich, eine persistente Lebensdauer zu verwenden, um unnötige Neustarts zu vermeiden. Weitere Informationen finden Sie unter Lebensdauer von Containerressourcen.

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 Ihren MySQL Ressourcen-Baustein (die mysql Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank erhält den Namen mysqldb und wird dann dem 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. Es wird dem Abschnitt Parameters hinzugefügt, zum Beispiel:

{
  "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 sicheres Speichern von App-Geheimnissen in der Entwicklung in ASP.NET Core und Ressource MySQL mit Parameternhinzufügen.

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

Trinkgeld

Wenn Sie lieber eine Verbindung mit einem vorhandenen MySQLserverherstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Fügen Sie eine MySQL-Ressource mit einem Datenvolumen hinzu.

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 Datenvolume 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 und wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie unter -Docker-Dokumentation: Volumes.

Warnung

Das Kennwort wird im Datenvolume gespeichert. Wenn Sie ein Datenvolumen verwenden und sich das Kennwort ändert, wird es nicht funktionieren, bis Sie das Volumen löschen.

Hinzufügen einer MySQL Ressource mit einer Datenbindungseinbindung

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

Wichtig

Daten--Bind-Mounts bieten eingeschränkte Funktionalität im Vergleich zu -Volumes, die bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie für Produktionsumgebungen besser geeignet sind. Bind-Mounts ermöglichen jedoch den direkten Zugriff und die Modifikation von Dateien auf dem Hostsystem, ideal für Entwicklung und Tests, bei denen Änderungen in Echtzeit erforderlich sind.

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

Füge die Ressource MySQL mit Parametern hinzu

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 Link zum Endpunkt aus, um phpMyAdmin in einem neuen Browser-Tab anzuzeigen.

Hosten von Integritätsprüfungen für Integration

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 Hostingintegration basiert auf den 📦 AspNetCore.HealthChecks und demMySql NuGet-Paket.

Client-Integration

Um mit der .NET AspireMySQL-Datenbankintegration zu beginnen, installieren Sie das 📦Aspire.MySqlConnector NuGet-Paket im client-verbrauchenden Projekt, bei dem es sich um das Projekt für die Anwendung handelt, die die MySQLclientnutzt. Die MySQLclient-Integration registriert eine MySqlConnector.MySqlDataSource Instanz, mit der Sie mit dem MySQLserverinteragieren können.

.NET CLI

dotnet add package Aspire.MySqlConnector

PackageReference

<PackageReference Include="Aspire.MySqlConnector"
                  Version="*" />

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

Fügen Sie eine MySQL-Datenquelle hinzu

Rufen Sie in der Program.cs-Datei Ihres Projekts, das clientverbraucht, die Erweiterungsmethode AddMySqlDataSource auf, um ein MySqlDataSource für die Verwendung über den Dependency Injection Container zu registrieren. Die Methode verwendet einen connectionName-Parameter.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der MySQL-Datenbankressource im App-Hostprojekt verwendet wird. Anders ausgedrückt: Wenn Sie AddDatabase aufrufen und einen Namen für mysqldb angeben, sollte dieser Name auch beim Aufrufen von AddMySqlDataSourceverwendet werden. Weitere Informationen finden Sie unter Hinzufügen MySQLserver Ressourcen und Datenbankressourcen.

Anschließend können Sie die MySqlConnector.MySqlDataSource Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Datenquelle aus einem Beispieldienst ab:

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

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

Hinzufügen einer zielgerichteten MySQL-Datenquelle

Es kann Situationen geben, in denen Sie mehrere MySqlDataSource-Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Um schlüsselierte MySQL Datenquellen zu registrieren, rufen Sie die AddKeyedMySqlDataSource-Methode auf:

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

Wichtig

Bei der Verwendung von Schlüsselservices wird erwartet, dass Ihre Ressource MySQL zwei benannte Datenbanken konfiguriert hat, eine für die mainDb und eine für die loggingDb.

Anschließend können Sie die MySqlDatSource-Instanzen mithilfe von Dependency Injection abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: Keyed Services.

Konfiguration

Die .NET AspireMySQL Datenbankintegration bietet mehrere Optionen zum Konfigurieren der Verbindung 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 AddMySqlDataSource Methode den Namen der Verbindungszeichenfolge angeben:

builder.AddMySqlDataSource(connectionName: "mysql");

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

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

Weitere Informationen dazu, wie Sie diese Verbindungszeichenfolge formatieren, finden Sie in der MySqlConnector: Verbindungszeichenfolge-Dokumentation.

Konfigurationsanbieter verwenden

Die .NET AspireMySQL Datenbankintegration unterstützt Microsoft.Extensions.Configuration. Sie lädt die MySqlConnectorSettings mithilfe des Aspire:MySqlConnector Schlüssels aus der Konfiguration. Der folgende Codeausschnitt ist ein Beispiel für eine appsettings.json Datei, die einige der Optionen konfiguriert:

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

Für das vollständige MySQL Integrationsschema JSON siehe Aspire. MySqlConnector/ConfigurationSchema.json.

Verwenden von Inlinedelegatn

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

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

Client Gesundheitschecks der Integration

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

Die .NET AspireMySQL Datenbankintegration:

• Fügt die Gesundheitsprüfung hinzu, wenn MySqlConnectorSettings.DisableHealthChecksfalseist; dabei wird überprüft, ob eine Verbindung hergestellt werden kann und Befehle gegen die MySQL-Datenbank ausgeführt werden können.
• Integriert sich mit dem /health HTTP-Endpunkt, der angibt, dass alle registrierten Gesundheitschecks bestehen müssen, damit die App bereit ist, Datenverkehr zu akzeptieren.

Observability und Telemetrie

.NET .NET Aspire Integrationen konfigurieren automatisch die Protokollierung, das Tracing und die Metriken, die manchmal als "Säulen der Observability" bezeichnet werden. Weitere Informationen zur Integrationsobservability und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom Hintergrunddienst unterstützen einige Integrationen möglicherweise nur bestimmte dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefeatures können auch mithilfe der techniken deaktiviert werden, die im Abschnitt Configuration dargestellt werden.

Protokollierung

Die .NET AspireMySQL-Integration verwendet die folgenden Protokollkategorien:

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

Verfolgung

Die .NET AspireMySQL-Integration gibt diese folgenden Trackingaktivitäten mithilfe von OpenTelemetryaus.

• MySqlConnector

Metriken

Die .NET AspireMySQL Integration gibt die folgenden Metriken mithilfe von OpenTelemetryaus:

• 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
• .NET .NET Aspire Beispiel für Datenbankcontainer
• .NET .NET Aspire Integrationen
• .NET Aspire GitHub Repository-