integrace .NET AspireMySQL

Článek
12/13/2024

cs-CZ: zahrnuje:integraci hostování a Client integraci

MySQL je opensourcový systém pro správu relačních databází (RDBMS), který ke správě a manipulaci s daty používá jazyk SQL (Structured Query Language). Používá se v mnoha různých prostředích, od malých projektů po rozsáhlé podnikové systémy a je oblíbenou volbou pro hostování dat, která jsou základem mikroslužeb v nativní cloudové aplikaci. Integrace databáze .NET AspireMySQL umožňuje připojit se k existujícím databázím MySQL nebo vytvářet nové instance z .NET pomocí obrazového kontejneru mysql.

Integrace hostování

MySQL hostování integračních modelů server jako typ MySqlServerResource a databáze jako typ MySqlDatabaseResource. Pokud chcete získat přístup k těmto typům a rozhraním API, přidejte 📦Aspire.Hosting.MySql balíček NuGet v projektu hostitele aplikace .

rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.MySql

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

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v aplikacích .NET.

Přidejte prostředky MySQLserver a databázový prostředek

V projektu hostitele aplikace zavolejte AddMySql a přidejte a vraťte návrháře zdrojů MySQL. Zřetězte volání na vrácený builder prostředků k AddDatabasea přidejte MySQL jako databázový prostředek.

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

Poznámka

Kontejner SQL Server se spouští pomalu, takže je nejlepší použít trvalou životnost pro, aby se předešlo zbytečným restartům. Další informace najdete v tématu Životnost kontejnerových prostředků.

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí mysql, vytvoří na místním počítači novou instanci MySQL. K přidání databáze se používá odkaz na tvůrce prostředků MySQL (proměnná mysql). Databáze se jmenuje mysqldb a pak se přidá do ExampleProject. Prostředek MySQL zahrnuje výchozí přihlašovací údaje s username ve formě root a náhodně vygenerovaným password pomocí metody CreateDefaultPasswordParameter.

Když se hostitel aplikace spustí, heslo se uloží do tajného úložiště hostitele aplikace. Přidáváme to do oddílu Parameters, například:

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

Název parametru je mysql-password, ale ve skutečnosti pouze formátuje název prostředku s příponou -password. Další informace najdete v tématu Bezpečné ukládání tajných kódů aplikací při vývoji v ASP.NET Core a Přidání prostředku MySQL s parametry.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem mysqldb.

Spropitné

Pokud byste se raději připojili k existujícímu MySQLserver, volejte místo toho AddConnectionString. Další informace naleznete v tématu Odkaz na dostupné zdroje.

Přidání MySQL prostředku s datovým svazkem

Pokud chcete do prostředku SQL Server přidat datový svazek, zavolejte metodu WithDataVolume prostředku SQL Server:

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

Objem dat se používá k zachování MySQLserver dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /var/lib/mysql v kontejneru SQL Server a když není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před připojení vazby, najdete v dokumentaci Docker: Svazky.

Varování

Heslo je uloženo v datovém svazku. Pokud používáte datový svazek a změní se heslo, nebude fungovat, dokud svazek neodstraníte.

Přidejte zdroj MySQL s připojením svazku dat

Pokud chcete přidat připojení vazby dat k prostředku MySQL, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají omezené funkce ve srovnání se svazky, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je činí vhodnějšími pro produkční prostředí. Připojení typu bind mount však umožňují přímý přístup a úpravu souborů v hostitelském systému, což je ideální pro vývoj a testování, kde jsou potřebné okamžité změny.

Datové vazby využívají systém souborů hostitelského počítače pro zachování dat MySQL během restartování kontejneru. Datový bind mont je připojen na cestu C:\MySql\Data ve Windows (nebo /MySql/Data na Unix) na hostitelském počítači v kontejneru MySQL. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidání prostředku MySQL s parametry

Pokud chcete zadat kořenové MySQL heslo explicitně, můžete ho předat jako parametr. Podívejte se na následující alternativní příklad:

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

Další informace naleznete v tématu Externí parametry.

Přidejte prostředek PhpMyAdmin

phpMyAdmin je oblíbeným webovým nástrojem pro správu pro MySQL. Můžete ho použít k procházení a úpravě MySQL objektů, jako jsou databáze, tabulky, zobrazení a indexy. Pokud chcete v řešení .NET.NET Aspire použít phpMyAdmin, zavolejte metodu WithPhpMyAdmin. Tato metoda přidá nový prostředek kontejneru do řešení, které hostuje phpMyAdmin a připojí ho k kontejneru 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...

Při spuštění řešení se na řídicím panelu .NET.NET Aspire zobrazí prostředky phpMyAdmin s koncovým bodem. Výběrem odkazu na koncový bod zobrazíte phpMyAdmin na nové kartě prohlížeče.

Hostování kontrol stavu integrace

Integrace hostování MySQL automaticky přidá kontrolu stavu prostředku MySQL. Kontrola stavu ověřuje, že jsou MySQLserver spuštěné a že k nim lze navázat připojení.

Integrace hostování spoléhá na 📦 AspNetCore.HealthChecks.MySql balíček NuGet.

integrace Client

Pokud chcete začít s integrací databáze .NET AspireMySQL, nainstalujte balíček NuGet 📦Aspire.MySqlConnector v projektu client, tj. v projektu pro aplikaci, která používá MySQLclient. Integrace MySQLclient registruje instanci MySqlConnector.MySqlDataSource, kterou můžete použít k interakci s MySQLserver.

rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.MySqlConnector

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

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v aplikacích .NET.

Přidat zdroj dat MySQL

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddMySqlDataSource, která zaregistruje MySqlDataSource pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku databáze MySQL do hostitelského projektu aplikace. Jinými slovy, když voláte AddDatabase a zadáte jméno mysqldb, toto stejné jméno by mělo být použito při volání AddMySqlDataSource. Další informace najdete v tématu Přidání prostředku MySQLserver a databázového prostředku.

Potom můžete načíst instanci MySqlConnector.MySqlDataSource pomocí dependency injection. Pokud například chcete načíst zdroj dat z ukázkové služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání klíčeného MySQL zdroje dat

Mohou nastat situace, kdy chcete zaregistrovat více instancí MySqlDataSource s různými názvy připojení. Pokud chcete zaregistrovat klíčované MySQL zdroje dat, zavolejte metodu AddKeyedMySqlDataSource:

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

Důležitý

Při použití služeb s klíči se očekává, že váš prostředek MySQL nakonfiguroval dvě pojmenované databáze, jednu pro mainDb a druhou pro loggingDb.

Potom můžete načíst instance MySqlDatSource pomocí dependency injection. Pokud například chcete načíst připojení z ukázkové služby:

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

Další informace o označených službách najdete v sekci .NET injektáž závislostí: Označené služby.

Konfigurace

Integrace databáze .NET AspireMySQL poskytuje několik možností konfigurace připojení na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání metody AddMySqlDataSource zadat název připojovacího řetězce:

builder.AddMySqlDataSource(connectionName: "mysql");

Připojovací řetězec se pak načte z oddílu konfigurace ConnectionStrings:

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

Další informace o formátování tohoto připojovacího řetězce najdete v tématu MySqlConnector: Dokumentace ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace databáze .NET AspireMySQL podporuje Microsoft.Extensions.Configuration. Načte MySqlConnectorSettings z konfigurace pomocí klíče Aspire:MySqlConnector. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace MySQLJSON najdete v tématu Aspire. MySqlConnector/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<MySqlConnectorSettings> a nastavit některé nebo všechny možnosti přímo v kódu, například zakázat kontrolu dostupnosti systémů přímo z kódu.

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

Client kontroly stavu integrace

Integrace .NET.NET Aspire umožňují ve výchozím nastavení kontrolu stavu pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

Integrace databáze .NET AspireMySQL:

Přidá kontrolu stavu, když je MySqlConnectorSettings.DisableHealthChecksfalse, která ověřuje, že je možné vytvořit připojení a příkazy lze spouštět proti databázi MySQL.
Integruje se s koncovým bodem /health HTTP, který určuje, že všechny registrované zdravotní kontroly musí být úspěšné, aby byla aplikace považována za připravenou přijímat provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireMySQL používá následující kategorie protokolů:

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

Trasování

Integrace .NET AspireMySQL generuje následující aktivity trasování pomocí OpenTelemetry:

MySqlConnector

Metriky

Integrace .NET AspireMySQL pomocí OpenTelemetryvygeneruje následující metriky:

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

Viz také

MySQL databáze
ukázka kontejnerů databáze .NET.NET Aspire
integrace .NET.NET Aspire
.NET Aspire GitHub úložiště

Sdílet prostřednictvím