Delen via

integratie van .NET AspireMySQL

  • Artikel

omvat:hosting-integratie en Client integratie

MySQL is een opensource Relational Database Management System (RDBMS) dat gebruikmaakt van Structured Query Language (SQL) voor het beheren en bewerken van gegevens. Het wordt gebruikt in een groot aantal verschillende omgevingen, van kleine projecten tot grootschalige bedrijfssystemen en het is een populaire keuze om gegevens te hosten die microservices in een cloudeigen toepassing ondersteunen. Met de .NET AspireMySQL-database-integratie kunt u verbinding maken met bestaande MySQL-databases of nieuwe exemplaren maken vanuit .NET met de mysql-containerimage.

Hostingintegratie

Het MySQL-hostingmodelleert de server als het MySqlServerResource-type en de database als het MySqlDatabaseResource-type. Als u toegang wilt krijgen tot deze typen en API's, voegt u het 📦Aspire.Hosting.MySql NuGet-pakket toe aan het app-hostproject.

dotnet add package Aspire.Hosting.MySql

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

MySQL server resource en databaseresource toevoegen

Roep in uw app-hostproject AddMySql aan om een builder voor MySQL-resources toe te voegen en terug te geven. Koppel een aanroep aan de geretourneerde resource builder naar AddDatabaseom een MySQL databaseresource toe te voegen.

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

Notitie

De SQL Server-container start traag op, dus is het het beste om een persistente-levensduur te gebruiken om onnodige herstarten te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de mysql-installatiekopie, wordt er een nieuw MySQL exemplaar op uw lokale computer gemaakt. Een verwijzing naar de MySQL resourcebouwer (de mysql variabele) wordt gebruikt om een database toe te voegen. De database heeft de naam mysqldb en wordt vervolgens toegevoegd aan de ExampleProject. De MySQL-resource bevat standaardreferenties met een username van root en een willekeurige password gegenereerd met behulp van de methode CreateDefaultPasswordParameter.

Wanneer de app-host wordt uitgevoerd, wordt het wachtwoord opgeslagen in de geheime opslag van de app-host. Deze wordt toegevoegd aan de sectie Parameters, bijvoorbeeld:

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

De naam van de parameter is mysql-password, maar eigenlijk is het alleen het opmaken van de resourcenaam met een -password achtervoegsel. Voor meer informatie, zie Veilige opslag van app-geheimen in ontwikkeling in ASP.NET Core en , en voeg MySQL resource toe met parameters.

De methode WithReference configureert een verbinding in de ExampleProject met de naam mysqldb.

Tip

Als u liever verbinding wilt maken met een bestaande MySQLserver, roept u in plaats daarvan AddConnectionString aan. Raadpleeg Bestaande bronnenvoor meer informatie.

Een MySQL-resource toevoegen met een gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de SQL Server-resource, roept u de methode WithDataVolume aan voor de SQL Server resource:

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

Het gegevensvolume wordt gebruikt om de MySQLserver gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/lib/mysql pad in de SQL Server container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Zie Docker docs: Volumesvoor meer informatie over gegevensvolumes en details over waarom ze de voorkeur hebben boven bindingskoppelingen.

Waarschuwing

Het wachtwoord wordt opgeslagen in het gegevensvolume. Wanneer u een gegevensvolume gebruikt en als het wachtwoord wordt gewijzigd, werkt het pas als u het volume verwijdert.

Voeg een MySQL-resource toe met een gegevensbindingskoppeling

Als u een koppeling voor gegevensbinding wilt toevoegen aan de MySQL-resource, roept u de WithDataBindMount methode aan:

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

Belangrijk

Gegevens koppelingen hebben beperkte functionaliteit ten opzichte van volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind mounts bieden echter directe toegang tot en aanpassing van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar realtime wijzigingen nodig zijn.

Gegevenskoppelingen maken gebruik van het bestandssysteem van de hostcomputer om MySQL-gegevens te behouden bij herstarten van de container. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\MySql\Data in Windows (of /MySql/Data op Unix) op de hostcomputer in de MySQL container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over bindingskoppelingen voor gegevens.

MySQL resource toevoegen met parameters

Wanneer u een hoofdwachtwoord MySQL expliciet wilt opgeven, kunt u dit doorgeven als parameter. Bekijk het volgende alternatieve voorbeeld:

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

Zie Externe parametersvoor meer informatie.

Een PhpMyAdmin-resource toevoegen

phpMyAdmin is een populair webbeheerprogramma voor MySQL. U kunt deze gebruiken om door MySQL objecten zoals databases, tabellen, weergaven en indexen te bladeren en te wijzigen. Als u phpMyAdmin in uw .NET.NET Aspire-oplossing wilt gebruiken, roept u de methode WithPhpMyAdmin aan. Met deze methode wordt een nieuwe containerresource toegevoegd aan de oplossing die phpMyAdmin host en deze verbindt met de 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...

Wanneer u de oplossing uitvoert, worden in het .NET.NET Aspire dashboard de phpMyAdmin-resources met een eindpunt weergegeven. Selecteer de koppeling naar het eindpunt om phpMyAdmin weer te geven in een nieuw browsertabblad.

Statuscontroles voor hostingintegratie

De MySQL hostingintegratie voegt automatisch een statuscontrole toe voor de MySQL resource. De gezondheidscontrole controleert of de MySQLserver actief is en of er een verbinding mee tot stand kan worden gebracht.

De hostingintegratie is afhankelijk van de 📦 AspNetCore.HealthChecks.MySql NuGet-pakket.

integratie van Client

Installeer de 📦Aspireom aan de slag te gaan met de .NET AspireMySQL-databaseintegratie. MySqlConnector NuGet-pakket in het client-verbruikende project, dat wil gezegd, het project voor de toepassing die gebruikmaakt van de MySQLclient. De MySQLclient-integratie registreert een MySqlConnector.MySqlDataSource exemplaar dat u kunt gebruiken om te communiceren met de MySQLserver.

dotnet add package Aspire.MySqlConnector

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Een MySQL-gegevensbron toevoegen

Roep in het Program.cs-bestand van uw client-gebruikende project de AddMySqlDataSource-extensiemethode aan om een MySqlDataSource te registreren voor gebruik met de afhankelijkheidsinjectiecontainer. De methode gebruikt een connectionName parameter.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Suggestie (if "Tip" refers to advice)

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de MySQL databaseresource in het app-hostproject. Met andere woorden, wanneer u AddDatabase aanroept en een naam opgeeft van mysqldb diezelfde naam moet worden gebruikt bij het aanroepen van AddMySqlDataSource. Voor meer informatie, zie voeg MySQLserver-resource en database resourcetoe.

Vervolgens kunt u het MySqlConnector.MySqlDataSource exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de gegevensbron wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Gesleutelde gegevensbron MySQL toevoegen

Er kunnen situaties zijn waarin u meerdere MySqlDataSource exemplaren met verschillende verbindingsnamen wilt registreren. Roep de methode AddKeyedMySqlDataSource aan om keyed MySQL gegevensbronnen te registreren.

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

Belangrijk

Wanneer u sleutelservices gebruikt, wordt verwacht dat uw MySQL resource twee benoemde databases heeft geconfigureerd, één voor de mainDb en één voor de loggingDb.

Vervolgens kunt u de MySqlDatSource exemplaren ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over sleutelservices, zie .NET afhankelijkheidsinjectie: Keyed Services.

Configuratie

De .NET AspireMySQL-databaseintegratie biedt meerdere opties voor het configureren van de verbinding op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van AddMySqlDataSource methode:

builder.AddMySqlDataSource(connectionName: "mysql");

Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie:

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

Zie MySqlConnector: ConnectionString-documentatievoor meer informatie over het opmaken van deze verbindingsreeks.

Configuratieproviders gebruiken

De integratie van de .NET AspireMySQL-database ondersteunt Microsoft.Extensions.Configuration. Het laadt de MySqlConnectorSettings uit de configuratie door gebruik te maken van de Aspire:MySqlConnector-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

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

Zie voor het volledige MySQL integratieschema JSON ook MySqlConnector/ConfigurationSchema. Aspirejson.

Inline gedelegeerden gebruiken

U kunt ook de Action<MySqlConnectorSettings> gedelegeerde doorgeven om sommige of alle opties inline in te stellen, bijvoorbeeld door gezondheidscontroles via code uit te schakelen:

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

Statuscontroles voor Client Integratie

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De .NET Aspire-MySQL-databaseintegratie:

  • Voegt de statuscontrole toe wanneer MySqlConnectorSettings.DisableHealthChecks is false, waarmee wordt gecontroleerd of er een verbinding kan worden gemaakt en opdrachten kunnen worden uitgevoerd op de MySQL-database.
  • Kan worden geïntegreerd met het /health HTTP-eindpunt, waarmee alle geregistreerde statuscontroles moeten worden doorgegeven zodat de app als gereed wordt beschouwd voor het accepteren van verkeer.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties zorgen voor het automatisch instellen van configuraties voor logging, tracing en metrics, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Registratie

De .NET AspireMySQL-integratie maakt gebruik van de volgende logboekcategorieën:

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

Tracering

De .NET AspireMySQL-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

  • MySqlConnector

Statistieken

De integratie van .NET AspireMySQL verzendt de volgende metrische gegevens met behulp van 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

Zie ook