Udostępnij za pośrednictwem

integracja .NET AspireMySQL

  • Artykuł

obejmuje: integracja hostingu i Client

MySQL to system zarządzania relacyjnymi bazami danych typu open source (RDBMS), który używa języka Structured Query Language (SQL) do zarządzania danymi i manipulowania nimi. Jest ona stosowana w wielu różnych środowiskach, od małych projektów po systemy przedsiębiorstwa na dużą skalę i jest popularnym wyborem do hostowania danych, które stanowią podstawę mikrousług w aplikacji natywnej dla chmury. Integracja bazy danych .NET AspireMySQL umożliwia łączenie się z istniejącymi bazami danych MySQL lub tworzenie nowych wystąpień z .NET przy użyciu obrazu kontenera mysql.

Integracja hostingu

Integracja hostowania MySQL modeluje server jako typ MySqlServerResource, a bazę danych jako typ MySqlDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.MySql w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.MySql

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w aplikacjach .NET.

Dodawanie zasobu MySQLserver i zasobu bazy danych

W projekcie hosta aplikacji wywołaj AddMySql, aby dodać konstruktor zasobów MySQL i go zwrócić. Połącz wywołanie zwróconego konstruktora zasobów z AddDatabase, aby dodać zasób bazy danych MySQL.

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

Notatka

Kontener SQL Server działa wolno, więc najlepiej użyć trwałego okresu istnienia, aby uniknąć niepotrzebnych ponownych uruchomień. Aby uzyskać więcej informacji, zobacz okres istnienia zasobu kontenera.

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano we wcześniejszym przykładzie z obrazem mysql, tworzy nową instancję MySQL na komputerze lokalnym. Odwołanie do zmiennej mysql w konstruktorze zasobów MySQL służy do dodawania bazy danych. Baza danych nosi nazwę mysqldb, a następnie jest dodawana do ExampleProject. Zasób MySQL zawiera poświadczenia domyślne z usernameroot i losową password wygenerowaną przy użyciu metody CreateDefaultPasswordParameter.

Po uruchomieniu hosta aplikacji hasło jest przechowywane w magazynie tajnym hosta aplikacji. Jest on dodawany do sekcji Parameters, na przykład:

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

Nazwa parametru jest mysql-password, ale naprawdę wystarczy sformatować nazwę zasobu z sufiksem -password. Aby uzyskać więcej informacji, zobacz Bezpieczne przechowywanie tajemnic aplikacji w środowisku deweloperskim w ASP.NET Core i Dodaj zasób MySQL z parametrami.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie mysqldb.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym MySQLserver, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, zobacz Referencje istniejących zasobów.

Dodawanie zasobu MySQL z woluminem danych

Aby dodać wolumin danych do zasobu SQL Server, wywołaj metodę WithDataVolume w zasobie 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...

Wolumen danych służy do zapisywania MySQLserver danych poza cyklem życia jego kontenera. Wolumin danych jest instalowany w ścieżce /var/lib/mysql w kontenerze SQL Server, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat woluminów danych i dlaczego są one preferowane zamiast montowania wiązań , zobacz dokumentację Docker: woluminy.

Ostrzeżenie

Hasło jest przechowywane w woluminie danych. W przypadku korzystania z woluminu danych i zmiany hasła nie będzie działać, dopóki wolumin nie zostanie usunięty.

Dodawanie zasobu MySQL z instalacją powiązania danych

Aby dodać powiązanie danych do zasobu MySQL, wywołaj metodę 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...

Ważny

Instalacje powiązane danych mają ograniczoną funkcjonalność w porównaniu z woluminami , co zapewnia lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednakże montowanie katalogów umożliwia bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do programowania i testowania, gdzie potrzebne są zmiany w czasie rzeczywistym.

Instalacje powiązania danych polegają na systemie plików maszyny hosta w celu utrwalania MySQL danych między ponownymi uruchomieniami kontenera. Powiązanie danych jest montowane w ścieżce C:\MySql\Data w systemie Windows (lub /MySql/Data w Unix) na maszynie hosta przez kontener MySQL. Aby uzyskać więcej informacji na temat powiązań danych (bind mounts), zobacz dokumentację: Docker Bind mounts.

Dodawanie zasobu MySQL z parametrami

Jeśli chcesz jawnie podać hasło głównego MySQL, możesz przekazać je jako parametr. Rozważmy następujący przykład alternatywny:

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

Aby uzyskać więcej informacji, zobacz Parametry zewnętrzne.

Dodawanie zasobu PhpMyAdmin

phpMyAdmin to popularne internetowe narzędzie administracyjne do MySQL. Służy do przeglądania i modyfikowania obiektów MySQL, takich jak bazy danych, tabele, widoki i indeksy. Aby użyć narzędzia phpMyAdmin w rozwiązaniu .NET.NET Aspire, wywołaj metodę WithPhpMyAdmin. Ta metoda dodaje nowy zasób kontenera do rozwiązania, które hostuje phpMyAdmin i łączy go z kontenerem 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...

Po uruchomieniu rozwiązania, pulpit nawigacyjny .NET.NET Aspire wyświetla zasoby phpMyAdmin wraz z punktem końcowym. Wybierz link do punktu końcowego, aby wyświetlić plik phpMyAdmin na nowej karcie przeglądarki.

Hostowanie kontroli kondycji integracji

Integracja hostowania MySQL automatycznie dodaje kontrolę kondycji zasobu MySQL. Sprawdzenie kondycji weryfikuje, czy MySQLserver działa i czy można nawiązać połączenie z nim.

Integracja hostingu opiera się na pakiecie 📦 AspNetCore.HealthChecks.MySql NuGet.

integracja Client

Aby rozpocząć pracę z integracją bazy danych .NET AspireMySQL, zainstaluj 📦Aspire.MySqlConnector pakiet NuGet w projekcie korzystającym z client, czyli projektu dla aplikacji korzystającej z MySQLclient. Integracja MySQLclient rejestruje wystąpienie MySqlConnector.MySqlDataSource, którego można użyć do interakcji z MySQLserver.

dotnet add package Aspire.MySqlConnector

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w aplikacjach .NET.

Dodaj źródło danych MySQL

W pliku Program.cs w projekcie, który używa client, wywołaj metodę rozszerzenia AddMySqlDataSource, aby zarejestrować MySqlDataSource do użycia przez kontener wstrzykiwania zależności. Metoda przyjmuje parametr connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu bazy danych MySQL w projekcie hosta aplikacji. Innymi słowy, podczas wywoływania AddDatabase i podając nazwę mysqldb, należy użyć tej samej nazwy podczas wywoływania AddMySqlDataSource. Aby uzyskać więcej informacji, zobacz Dodawanie zasobu MySQLserver i zasobu bazy danych.

Następnie można pobrać wystąpienie MySqlConnector.MySqlDataSource przy użyciu wstrzykiwania zależności. Aby na przykład pobrać źródło danych z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET wstrzykiwanie zależności.

Dodaj kluczowany MySQL źródła danych

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień MySqlDataSource z różnymi nazwami połączeń. Aby zarejestrować kluczowe źródła danych MySQL, wywołaj metodę AddKeyedMySqlDataSource:

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

Ważny

W przypadku korzystania z usług z kluczami oczekuje się, że zasób MySQL skonfigurował dwie nazwane bazy danych, jedną dla mainDb i jedną dla loggingDb.

Następnie można pobrać wystąpienia MySqlDatSource za pomocą wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług o kluczu, patrz .NET wstrzykiwanie zależności: usługi o kluczu.

Konfiguracja

Integracja z bazą danych .NET AspireMySQL udostępnia wiele opcji konfigurowania połączenia na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings podczas wywoływania metody AddMySqlDataSource można podać nazwę parametrów połączenia:

builder.AddMySqlDataSource(connectionName: "mysql");

Następnie parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

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

Aby uzyskać więcej informacji na temat formatowania tych parametrów połączenia, zobacz MySqlConnector: ConnectionString documentation.

Korzystanie z dostawców konfiguracji

Integracja bazy danych .NET AspireMySQL obsługuje Microsoft.Extensions.Configuration. Ładuje MySqlConnectorSettings z konfiguracji, używając klucza Aspire:MySqlConnector. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny schemat integracji MySQLJSON, zobacz Aspire.MySqlConnector/ConfigurationSchema.json.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<MySqlConnectorSettings>, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu wyłączenia kontroli kondycji z kodu:

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

Client kontrole zdrowia integracji

Domyślnie integracje .NET.NET Aspire umożliwiają kontrole kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja bazy danych .NET AspireMySQL:

  • Dodaje kontrolę kondycji, gdy MySqlConnectorSettings.DisableHealthChecks jest false, co sprawdza, czy można nawiązać połączenie, a polecenia mogą być uruchamiane względem bazy danych MySQL.
  • Integruje się z punktem końcowym HTTP /health, który wymaga zaliczenia wszystkich zarejestrowanych kontroli kondycji, aby aplikację uznać za gotową do przyjmowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują rejestrowanie, śledzenie i metryki, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Wyrąb

Integracja .NET AspireMySQL używa następujących kategorii dzienników:

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

Śledzenie

Integracja .NET AspireMySQL emituje następujące działania śledzenia przy użyciu OpenTelemetry:

  • MySqlConnector

Metryki

Integracja .NET AspireMySQL będzie emitować następujące metryki przy użyciu 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

Zobacz też