Udostępnij za pośrednictwem

integracja .NET AspireMySQLEntity Framework Core Pomelo

  • Artykuł

obejmuje:integracja hostingu i Client integracja

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 .NET Aspire Pomelo MySQLEntity Framework Core umożliwia łączenie się z istniejącymi bazami danych MySQL lub tworzenie nowych instancji z .NET przy użyciu obrazu mysql kontenera.

Integracja hostingu

Modelowanie hostingu MySQL przedstawia integrację server jako typ MySqlServerResource, a bazę danych jako typ MySqlDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj 📦Aspire.Hosting.MySql pakiet NuGet 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 .NET aplikacjach.

Dodawanie zasobu MySQLserver i zasobu bazy danych

W projekcie hosta aplikacji wywołaj AddMySql, aby dodać i zwrócić narzędzie do budowy zasobów MySQL. 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 wolno się uruchamia, więc najlepiej użyć trwałego cyklu życia , 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 w poprzednim przykładzie z obrazem mysql, tworzy nowe wystąpienie MySQL na komputerze lokalnym. Odwołanie do konstruktora zasobów MySQL (zmiennej 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 wartościami usernameroot i losową wartość 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 danych uwierzytelniających aplikacji w trakcie programowania w ASP.NET Core oraz 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 Odwołanie do 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 jest wykorzystywany do utrwalania MySQLserver danych poza cyklem życia 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 objętości danych i szczegółów na temat tego, dlaczego są preferowane nad wiązania, 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.

Dodaj zasób MySQL z zamontowaniem danych za pomocą powiązania

Aby doczepić punkt montowania 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 typu bind mount danych mają ograniczoną funkcjonalność w porównaniu z woluminami , które oferują lepszą wydajność, przenośność i bezpieczeństwo, czyniąc je bardziej odpowiednimi do środowisk produkcyjnych. Jednak montowanie wiązane umożliwia bezpośredni dostęp i modyfikację plików w systemie hosta, co jest idealne do opracowywania oprogramowania 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 montowane jest w ścieżce C:\MySql\Data w systemie Windows (lub /MySql/Data w ścieżce Unix) na maszynie hosta w kontenerze MySQL. Aby uzyskać więcej informacji na temat montowania powiązań danych, zobacz Docker dokumentację: 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 panel .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.

Obsługa testów kondycji integracji

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

Integracja hostingu zależy od pakietu 📦 AspNetCore.HealthChecks orazMySql Pakietu NuGet.

integracja Client

Aby rozpocząć pracę z integracją .NET Aspire Pomelo MySQL Entity Framework, zainstaluj 📦Aspire.Pomelo.EntityFrameworkCore.MySql pakiet NuGet w projekcie, który korzysta z client, czyli projektu dla aplikacji korzystającej z MySQLEntity Framework Coreclient.

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

Dodaj kontekst bazy danych MySQL

W pliku Program.cs używającego projektu clientwywołaj metodę rozszerzenia AddMySqlDbContext na dowolnym IHostApplicationBuilder, aby zarejestrować DbContext do użycia za pomocą kontenera do wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddMySqlDbContext<ExampleDbContext>(connectionName: "mysqldb");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu bazy danych SQL Server w projekcie hosta aplikacji. Innymi słowy, podczas wywoływania AddDatabase i podania nazwy mysqldb, tej samej nazwy należy użyć podczas wywoływania AddMySqlDbContext. Aby uzyskać więcej informacji, zobacz Dodaj zasób MySQLserver oraz zasób bazy danych.

Aby pobrać obiekt ExampleDbContext z usługi:

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

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

Dodaj kontekst bazy danych MySQL z wzbogacaniem

Aby wzbogacić DbContext o dodatkowe usługi, takie jak automatyczne ponawianie prób, kontrole kondycji, logowanie i telemetria, wywołaj metodę EnrichMySqlDbContext:

builder.EnrichMySqlDbContext<ExampleDbContext>(
    connectionName: "mysqldb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

Parametr settings jest wystąpieniem klasy PomeloEntityFrameworkCoreMySqlSettings.

Konfiguracja

Integracja .NET Aspire Pomelo MySQLEntity Framework Core udostępnia wiele opcji konfigurowania połączenia bazy danych na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania builder.AddMySqlDatabaseDbContext<TContext>():

builder.AddMySqlDatabaseDbContext<MyDbContext>("mysql");

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

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

EnrichMySqlDbContext nie będzie korzystać z sekcji konfiguracji ConnectionStrings, ponieważ oczekuje ona zarejestrowania DbContext w momencie jego wywołania.

Aby uzyskać więcej informacji, zobacz dokumentację MySqlConnector: ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET Aspire Pomelo MySQLEntity Framework Core obsługuje Microsoft.Extensions.Configuration. Ładuje PomeloEntityFrameworkCoreMySqlSettings z plików konfiguracji, takich jak appsettings.json przy użyciu klucza Aspire:Pomelo:EntityFrameworkCore:MySql.

W poniższym przykładzie przedstawiono appsettings.json, które konfiguruje niektóre z dostępnych opcji:

{
  "Aspire": {
    "Pomelo": {
      "EntityFrameworkCore": {
        "MySql": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Aby zobaczyć pełny schemat integracji MySQLJSON, zobacz Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Użyj delegatów wbudowanych

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

builder.AddMySqlDbContext<MyDbContext>(
    "mysqldb",
    static settings => settings.DisableHealthChecks = true);

lub

builder.EnrichMySqlDbContext<MyDbContext>(
    static settings => settings.DisableHealthChecks = true);

Kontrole kondycji

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

Integracja .NET Aspire Pomelo MySQLEntity Framework Core:

  • Dodaje sprawdzanie kondycji, gdy PomeloEntityFrameworkCoreMySqlSettings.DisableHealthChecks jest false, co wywołuje metodę CanConnectAsync należącą do EF Core.
  • Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane kontrole kondycji muszą przejść pomyślnie, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują konfiguracje rejestrowania, śledzenia i metryk, 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 Aspire Pomelo MySQLEntity Framework Core korzysta z następujących kategorii logów:

  • Microsoft.EntityFrameworkCore.ChangeTracking
  • Microsoft.EntityFrameworkCore.Database.Command
  • Microsoft.EntityFrameworkCore.Database.Connection
  • Microsoft.EntityFrameworkCore.Database.Transaction
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Migrations
  • Microsoft.EntityFrameworkCore.Model
  • Microsoft.EntityFrameworkCore.Model.Validation
  • Microsoft.EntityFrameworkCore.Query
  • Microsoft.EntityFrameworkCore.Update

Śledzenie

Integracja .NET Aspire Pomelo MySQLEntity Framework Core będzie emitować następujące działania śledzenia przy użyciu OpenTelemetry:

  • MySqlConnector

Metryki

Integracja .NET Aspire Pomelo MySQLEntity Framework Core obecnie obsługuje następujące metryki:

  • 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ż