.NET Aspire-IntegrationMySQL-Integration

2025-06-11

Enthält: Hosting-Integration —&— 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.

Integration von Hosting

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

.NET CLI
PaketReferenz

dotnet add package Aspire.Hosting.MySql

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

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

Hinzufügen Serverressource MySQL 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...

Hinweis

Es dauert lange, bis der SQL Server-Container startet. Daher ist es am besten, eine dauerhafte-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 den MySQL Ressourcen-Generator (die mysql Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank wird als mysqldb benannt und dann zu ExampleProjecthinzugefügt. Die MySQL-Ressource enthält Standardanmeldedaten mit einem username von root und einem zufälligen password, das mithilfe der CreateDefaultPasswordParameter-Methode generiert wurde.

Wenn der App-Host ausgeführt wird, wird das Kennwort in der geheimen Ablage 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 eigentlich wird der Ressourcenname nur mit dem Suffix -password formatiert. Weitere Informationen finden Sie unter sichere Speicherung von App-Geheimnissen in der Entwicklung in ASP.NET Core und Hinzufügen einer Ressource mit ParameternMySQL.

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

Tipp

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

Hinzufügen einer MySQL-Ressource mit einem Datenvolumen

Rufen Sie die SQL Server-Methode für die WithDataVolume-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 MySQL Serverdaten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolumen wird am Pfad /var/lib/mysql im Container SQL Server bereitgestellt, und wenn kein Parameter name angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Datenvolumes.

Warnung

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

Von Bedeutung

Einige Datenbankintegrationen, einschließlich der .NET AspireMySQL Integration, können Datenvolumes nach der Bereitstellung auf Azure Container Apps (ACA) nicht erfolgreich verwenden. Dies liegt daran, dass ACA Server Message Block (SMB) verwendet, um Container mit Datenvolumes zu verbinden, und einige Systeme können diese Verbindung nicht verwenden. Aspire Im Dashboard weist eine datenbank, die von diesem Problem betroffen ist, den Status "Aktivieren" oder "Aktivierung fehlgeschlagen" auf, wird aber nie als "Ausführen" aufgeführt.

Sie können das Problem beheben, indem Sie in einem Kubernetes-Cluster bereitstellen, wie AzureKubernetes Services (AKS). Weitere Informationen finden Sie unter .NET.NET Aspire Bereitstellungen.

Eine MySQL-Ressource mit einer Data-Bind-Einbindung hinzufügen

Rufen Sie die MySQL-Methode auf, um der WithDataBindMount-Ressource ein Datenbindungs-Mount 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...

Von Bedeutung

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

Datenbindungseinbindungen stützen sich auf das Dateisystem des Hostrechners, um die MySQL-Daten über Neustarts von Containern hinweg beizubehalten. Die Datenbindemontage wird unter Windows am Pfad C:\MySql\Data (oder am Pfad /MySql/Data auf Unix) auf dem Hostcomputer im Container MySQL montiert. Weitere Informationen zu Bind-Mounts für Daten finden Sie in der Docker Dokumentation: Bind-Mounts.

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

Durchführung von Integrationsgesundheitsprüfungen

Die MySQL Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die MySQL Ressource hinzu. Die Funktionsprüfung überprüft, ob der MySQL-Server läuft und ob eine Verbindung hergestellt werden kann.

Die Hostingintegration basiert auf dem 📦 AspNetCore.HealthChecks.MySql NuGet-Paket.

Client Anbindung

Um mit der .NET AspireMySQL Datenbankintegration zu beginnen, installieren Sie die 📦Aspire. MySqlConnector NuGet-Paket im clientverwendenden Projekt, d. h. das Projekt für die Anwendung, die den MySQL Client verwendet. Die MySQL Clientintegration registriert eine MySqlConnector.MySqlDataSource Instanz, die Sie für die Interaktion mit dem MySQL Server verwenden können.

.NET CLI
PaketReferenz

dotnet add package Aspire.MySqlConnector

<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

In der Program.cs-Datei Ihres Projekts, das den Client nutzt, rufen Sie die AddMySqlDataSource-Erweiterungsmethode auf, um ein MySqlDataSource zur Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen connectionName-Parameter.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Tipp

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 von mysqldb angeben, soll derselbe Name beim Aufrufen von AddMySqlDataSourceverwendet werden. Weitere Informationen finden Sie unter Hinzufügen von MySQL der Serverressource und der Datenbankressource.

Anschließend können Sie die Instanz MySqlConnector.MySqlDataSource mithilfe der Abhängigkeitsinjektion 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");

Von Bedeutung

Bei der Verwendung von schlüsselbasierten Diensten wird erwartet, dass Ihre MySQL Ressource 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 der Abhängigkeitsinjektion abrufen. Um die Verbindung von einem Beispieldienst abzurufen, gehen Sie wie folgt vor:

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: Dienste mit Schlüsseln.

Konfiguration

Die .NET AspireMySQL Datenbankintegration bietet mehrere Optionen zum Konfigurieren der Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden Sie eine 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");

Aus dem Konfigurationsabschnitt ConnectionStrings wird anschließend die Verbindungszeichenfolge 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 MySqlConnectorSettings mithilfe des Schlüssels Aspire:MySqlConnector aus der Konfiguration ein. 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
    }
  }
}

Das vollständige MySQL Integrationsschema JSON finden Sie unter Aspire. MySqlConnector/ConfigurationSchema.json.

Verwendung von Inline-Delegaten

Sie können auch den Action<MySqlConnectorSettings>-Delegaten verwenden, um einige oder alle Optionen inline einzurichten, z. B. um Gesundheitsprüfungen durch Code zu deaktivieren.

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

Client Integrationsgesundheitsprüfungen

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 in den /health HTTP-Endpunkt, der spezifiziert, dass alle registrierten Gesundheitsprüfungen erfolgreich sein müssen, damit die App bereit ist, Datenverkehr anzunehmen.

Beobachtbarkeit 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

Nachverfolgung

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

Freigeben über

.NET Aspire-IntegrationMySQL-Integration

Integration von Hosting

Hinzufügen Serverressource MySQL sowie Datenbankressource

Hinzufügen einer MySQL-Ressource mit einem Datenvolumen

Eine MySQL-Ressource mit einer Data-Bind-Einbindung hinzufügen

Ressource MySQL mit Parametern hinzufügen

Hinzufügen einer PhpMyAdmin-Ressource

Durchführung von Integrationsgesundheitsprüfungen

Client Anbindung

Fügen Sie eine MySQL-Datenquelle hinzu

Hinzufügen einer zielgerichteten MySQL-Datenquelle

Konfiguration

Verwenden Sie eine Verbindungszeichenfolge

Konfigurationsanbieter verwenden

Verwendung von Inline-Delegaten

Client Integrationsgesundheitsprüfungen

Beobachtbarkeit und Telemetrie

Protokollierung

Nachverfolgung

Metriken

Siehe auch

Zusätzliche Ressourcen