.NET Aspire MySQL integrering

omfattar:Hostingintegration och Client integration

MySQL är ett RDBMS (Relational Database Management System) med öppen källkod som använder SQL (Structured Query Language) för att hantera och manipulera data. Det används i många olika miljöer, från små projekt till storskaliga företagssystem och det är ett populärt val att vara värd för data som ligger till grund för mikrotjänster i ett molnbaserat program. Med .NET AspireMySQL databasintegrering kan du ansluta till befintliga MySQL databaser eller skapa nya instanser från .NET med mysql containeravbildningen.

Värdintegrering

MySQL som är värd för integrering modellerar server som MySqlServerResource typ och databas som MySqlDatabaseResource typ. Om du vill komma åt dessa typer och API:er lägger du till 📦Aspire.Hosting.MySql NuGet-paket i appvärdsprojektet.

.NET CLI

dotnet add package Aspire.Hosting.MySql

PackageReference

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

För mer information, se dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägg till MySQLserver resurser och databasresurs

I värdprojektet för appen anropar du AddMySql för att lägga till och returnera en MySQL resursskapare. Länka ett anrop till den returnerade resursbyggaren till AddDatabaseför att lägga till en MySQL databasresurs.

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

Not

Det går långsamt att starta den SQL Server containern, så det är bäst att använda en beständig livslängd för att undvika onödiga omstarter. För mer information, se containerresursens livslängd.

När .NET.NET Aspire lägger till en containerbild till applikationsvärden, vilket visas i föregående exempel med mysql-bilden, skapar den en ny MySQL-instans på den lokala datorn. En referens till din MySQL resursbyggare (variabeln mysql) används för att lägga till en databas. Databasen heter mysqldb och läggs sedan till i ExampleProject. Den MySQL resursen innehåller standardautentiseringsuppgifter med en username av root och en slumpmässig password som genereras med hjälp av metoden CreateDefaultPasswordParameter.

När app-värden körs lagras lösenordet i app-värdens hemliga arkiv. Det läggs till i avsnittet Parameters, till exempel:

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

Namnet på parametern är mysql-password, men egentligen är det bara att formatera resursnamnet med ett -password suffix. Mer information finns i Säker lagring av apphemligheter under utveckling i ASP.NET Core och Lägg till MySQL resurs med parametrar.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet mysqldb.

Tips

Om du hellre vill ansluta till en befintlig MySQLserveranropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägga till en MySQL resurs med en datavolym

Om du vill lägga till en datavolym i resursen SQL Server anropar du metoden WithDataVolume på den SQL Server resursen:

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

Datavolymen används för att bevara MySQLserver data utanför containerns livscykel. Datavolymen monteras på sökvägen /var/lib/mysql i containern SQL Server och när name parameter inte anges genereras namnet slumpmässigt. Mer information om datavolymer och varför de föredras framför bind-mountsfinns i Docker dokument: Volymer.

Varning

Lösenordet lagras i datavolymen. När du använder en datavolym och om lösenordet ändras fungerar det inte förrän du tar bort volymen.

Lägga till en MySQL resurs med en databindningsmontering

Om du vill lägga till en databindning till resursen MySQL, anropar du metoden 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...

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara MySQL data mellan omstarter av containrar. Databindningen monteras på sökvägen C:\MySql\Data i Windows (eller /MySql/Data på Unix) på värddatorn i MySQL-containern. Mer information om data-bindningsmonteringar finns i Docker dokumentation: Bindningsmonteringar.

Lägga till MySQL resurs med parametrar

När du uttryckligen vill ange ett rotlösenord MySQL kan du skicka det som en parameter. Tänk dig följande alternativa exempel:

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

Mer information finns i externa parametrar.

Lägga till en PhpMyAdmin-resurs

phpMyAdmin är ett populärt webbaserat administrationsverktyg för MySQL. Du kan använda den för att bläddra och ändra MySQL objekt som databaser, tabeller, vyer och index. Om du vill använda phpMyAdmin i din .NET.NET Aspire-lösning anropar du metoden WithPhpMyAdmin. Den här metoden lägger till en ny containerresurs i lösningen som är värd för phpMyAdmin och ansluter den till containern 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...

När du kör lösningen visar instrumentpanelen .NET.NET Aspire phpMyAdmin-resurser med en slutpunkt. Välj länken till slutpunkten för att visa phpMyAdmin på en ny webbläsarflik.

Hälsokontroller för värdintegrering

MySQL värdintegrering lägger automatiskt till en hälsokontroll för den MySQL resursen. Hälsokontrollen verifierar att MySQLserver körs och att en anslutning kan upprättas till den.

Värdintegreringen baseras på 📦 AspNetCore.HealthChecks.MySql NuGet-paket.

Client integration

Kom igång med .NET AspireMySQL databasintegrering genom att installera 📦Aspire.MySqlConnector NuGet-paketet i det projekt som konsumerar client, dvs. projektet för det program som använder MySQLclient. MySQL client-integreringen registrerar en MySqlConnector.MySqlDataSource instans som du kan använda för att interagera med MySQLserver.

.NET CLI

dotnet add package Aspire.MySqlConnector

PackageReference

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

För mer information, se dotnet add package eller Hantera paketberoenden i .NET-appar.

Lägga till en MySQL datakälla

I Program.cs-filen för ditt projekt som förbrukar client, anropar du AddMySqlDataSource-tilläggsmetoden för att registrera en MySqlDataSource för användning via beroendeinjektionscontainern. Metoden tar ett parameter av typen connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till MySQL-databasresursen i appvärdprojektet. Med andra ord, när du anropar AddDatabase och anger ett namn på mysqldb ska samma namn användas när du anropar AddMySqlDataSource. För mer information, se Lägg till MySQLresurs och databasresursserver.

Du kan sedan hämta instansen av MySqlConnector.MySqlDataSource med hjälp av beroendeinjektion. Om du till exempel vill hämta datakällan från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nycklad MySQL-datakälla

Det kan finnas situationer där du vill registrera flera MySqlDataSource instanser med olika anslutningsnamn. Om du vill registrera nyckelade MySQL datakällor anropar du metoden AddKeyedMySqlDataSource:

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

Viktig

När du använder nyckelade tjänster förväntas din MySQL resurs ha konfigurerat två namngivna databaser, en för mainDb och en för loggingDb.

Sedan kan du hämta MySqlDatSource instanser med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinjektion: Nyckelade tjänster.

Konfiguration

.NET Aspire MySQL-databasintegrering innehåller flera alternativ för att konfigurera anslutningen baserat på kraven och konventionerna i projektet.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar AddMySqlDataSource-metoden:

builder.AddMySqlDataSource(connectionName: "mysql");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information om hur du formaterar den här anslutningssträngen finns i MySqlConnector: ConnectionString-dokumentation.

Använda konfigurationsprovidrar

.NET Aspire MySQL-databasintegrering stöder Microsoft.Extensions.Configuration. Den läser in MySqlConnectorSettings från konfigurationen med hjälp av nyckeln Aspire:MySqlConnector. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

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

Det fullständiga MySQL integrationsschemat JSON finns i Aspire. MySqlConnector/ConfigurationSchema.json.

Använd inline-delegerare

Du kan också skicka Action<MySqlConnectorSettings> delegering för att konfigurera vissa eller alla alternativ direkt, till exempel för att inaktivera hälsokontroll från kod:

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

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

.NET Aspire MySQL databasintegrering

• Lägger till hälsokontrollen när MySqlConnectorSettings.DisableHealthChecks är false, vilket verifierar att en anslutning kan göras och att kommandon kan köras mot MySQL-databasen.
• Integrerar med HTTP-slutpunkten /health, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska betraktas som redo att ta emot trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire MySQL-integreringen använder följande loggkategorier:

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

Spårning

.NET Aspire MySQL-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• MySqlConnector

Mätvärden

Integreringen .NET AspireMySQL genererar följande mått med hjälp av 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

Se även

• MySQL databas
• .NET .NET Aspire exempel på databascontainrar
• .NET .NET Aspire integreringar
• .NET Aspire GitHub lagringsplats