Bagikan melalui

integrasi .NET Aspire Pomelo MySQLEntity Framework Core

Termasuk:Integrasi hosting dimasukkan integrasi hosting —dan— Client integrasi dimasukkanClient integrasi

MySQL adalah Sistem Manajemen Database Relasional (RDBMS) sumber terbuka yang menggunakan Structured Query Language (SQL) untuk mengelola dan memanipulasi data. Ini digunakan di berbagai lingkungan, dari proyek kecil hingga sistem perusahaan skala besar dan merupakan pilihan populer untuk menghosting data yang mendasar layanan mikro dalam aplikasi cloud-native. Integrasi .NET Aspire Pomelo MySQLEntity Framework Core memungkinkan Anda terhubung ke database MySQL yang ada atau membuat instans baru dari .NET dengan gambar kontainer mysql.

Integrasi hosting

Integrasi hosting MySQL memodelkan server sebagai jenis MySqlServerResource dan database sebagai jenis MySqlDatabaseResource. Untuk mengakses jenis dan API ini, tambahkan paket NuGet 📦Aspire.Hosting.MySql pada proyek host aplikasi .

dotnet add package Aspire.Hosting.MySql

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket di aplikasi .NET.

Menambahkan sumber daya server MySQL dan sumber daya database

Di proyek host aplikasi Anda, panggil AddMySql untuk menambahkan dan mengembalikan pembangun sumber daya MySQL. Rantai panggilan ke pembangun sumber daya yang dikembalikan ke AddDatabase, untuk menambahkan sumber daya database 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...

Nota

Kontainer SQL Server lambat dimulai, jadi yang terbaik adalah menggunakan masa pakai persisten yang tahan lama untuk menghindari memulai ulang yang tidak perlu. Untuk informasi selengkapnya, lihat masa pakai sumber daya kontainer.

Saat .NET.NET Aspire menambahkan gambar kontainer ke host aplikasi, seperti yang ditunjukkan dalam contoh sebelumnya dengan gambar mysql, gambar tersebut membuat instans MySQL baru di komputer lokal Anda. Referensi ke penyusun sumber daya MySQL Anda (variabel mysql) digunakan untuk menambahkan database. Database diberi nama mysqldb lalu ditambahkan ke ExampleProject. Sumber daya MySQL mencakup kredensial default dengan username berupa root dan password acak yang dihasilkan menggunakan metode CreateDefaultPasswordParameter.

Saat host aplikasi berjalan, kata sandi disimpan di penyimpanan rahasia host aplikasi. Ditambahkan ke bagian Parameters, misalnya contohnya:

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

Nama parameter adalah mysql-password, tetapi sebenarnya itu hanya memformat nama sumber daya dengan akhiran -password. Untuk informasi selengkapnya, lihat penyimpanan rahasia aplikasi yang aman pada dalam pengembangan di ASP.NET Core dan Tambahkan sumber daya MySQL dengan parameter.

Metode WithReference mengonfigurasi koneksi di ExampleProject bernama mysqldb.

Saran

Jika Anda lebih suka menyambungkan ke server MySQL yang sudah ada, panggil AddConnectionString sebagai gantinya. Untuk informasi selengkapnya, lihat referensi dari sumber daya yang ada.

Tambahkan satu sumber daya MySQL dengan besaran data.

Untuk menambahkan volume data ke sumber daya SQL Server, panggil metode WithDataVolume pada sumber daya 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...

Volume data digunakan untuk mempertahankan data server MySQL di luar siklus hidup kontainernya. Volume data dipasang di jalur /var/lib/mysql di kontainer SQL Server dan ketika parameter name tidak disediakan, nama dihasilkan secara acak. Untuk informasi lebih lanjut tentang volume data dan alasan mengapa mereka lebih disukai dibandingkan bind mount , lihat dokumen Docker: Volume.

Peringatan

Kata sandi disimpan dalam volume data. Saat menggunakan volume data dan jika kata sandi berubah, itu tidak akan berfungsi sampai Anda menghapus volume.

Penting

Beberapa integrasi database, termasuk .NET AspireMySQL integrasi, tidak dapat berhasil menggunakan volume data setelah penyebaran ke Azure Container Apps (ACA). Ini karena ACA menggunakan Server Blok Pesan (SMB) untuk menyambungkan kontainer ke volume data, dan beberapa sistem tidak dapat menggunakan koneksi ini. Aspire Di Dasbor, database yang terpengaruh oleh masalah ini memiliki status Aktivasi atau Aktivasi Gagal tetapi tidak pernah tercantum sebagai Berjalan.

Anda dapat mengatasi masalah dengan menyebarkan ke Kubernetes kluster, seperti AzureKubernetes Services (AKS). Untuk informasi selengkapnya, lihat penyebaran .NET.NET Aspire.

Menambahkan sumber daya MySQL dengan pemasangan ikatan data

Untuk menambahkan pemasangan ikatan data ke sumber daya MySQL, panggil metode 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...

Penting

Pemasangan ikat data memiliki fungsionalitas terbatas dibandingkan dengan volume , yang menawarkan performa, portabilitas, dan keamanan yang lebih baik, membuatnya lebih cocok untuk lingkungan produksi. Namun, bind mounts memungkinkan akses langsung dan modifikasi file pada sistem host, ideal untuk pengembangan dan pengujian yang memerlukan perubahan secara real-time.

Mount ikatan data mengandalkan sistem file komputer host untuk mempertahankan data MySQL saat kontainer di-restart. Pemasangan ikatan data dipasang di C:\MySql\Data pada jalur Windows (atau /MySql/Data pada Unix) pada komputer host di kontainer MySQL. Untuk informasi selengkapnya tentang pemasangan ikatan data, lihat dokumen Docker: Pemasangan ikatan.

Menambah sumber daya MySQL dengan parameter

Ketika Anda ingin secara eksplisit memberikan kata sandi root MySQL, Anda dapat meneruskannya sebagai parameter. Pertimbangkan contoh alternatif berikut:

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

Untuk informasi selengkapnya, lihat Parameter eksternal.

Menambahkan sumber daya PhpMyAdmin

phpMyAdmin adalah alat administrasi berbasis web populer untuk MySQL. Anda dapat menggunakannya untuk menelusuri dan memodifikasi objek MySQL seperti database, tabel, tampilan, dan indeks. Untuk menggunakan phpMyAdmin dalam solusi .NET.NET Aspire Anda, panggil metode WithPhpMyAdmin. Metode ini menambahkan sumber daya kontainer baru ke solusi yang menghosting phpMyAdmin dan menghubungkannya ke kontainer 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...

Saat Anda menjalankan solusi, dasbor .NET.NET Aspire menampilkan sumber daya phpMyAdmin melalui sebuah endpoint. Pilih tautan ke titik akhir untuk melihat phpMyAdmin di tab browser baru.

Memastikan pemeriksaan kesehatan integrasi

Integrasi hosting MySQL secara otomatis menambahkan pemeriksaan kesehatan untuk sumber daya MySQL. Pemeriksaan kesehatan memverifikasi bahwa server MySQL sedang berjalan dan bahwa koneksi dapat dibuat untuknya.

Integrasi hosting bergantung pada paket 📦 AspNetCore.HealthChecks.MySql NuGet.

Client integrasi

Untuk mulai menggunakan integrasi .NET Aspire Pomelo MySQL Entity Framework, instal paket NuGet 📦Aspire.Pomelo.EntityFrameworkCore.MySql dalam proyek yang menggunakan klien, yaitu, proyek untuk aplikasi yang menggunakan klien MySQLEntity Framework Core.

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket di aplikasi .NET.

Tambahkan konteks basis data MySQL

Dalam file Program.cs dari proyek yang menggunakan klien Anda, panggil metode ekstensi AddMySqlDbContext pada IHostApplicationBuilder mana saja untuk mendaftarkan DbContext agar dapat digunakan melalui container injeksi dependensi. Metode ini mengambil parameter nama koneksi.

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

Saran

Parameter connectionName harus cocok dengan nama yang digunakan saat menambahkan sumber daya database SQL Server dalam proyek host aplikasi. Dengan kata lain, ketika Anda memanggil AddDatabase dan memberikan nama mysqldb nama yang sama harus digunakan saat memanggil AddMySqlDbContext. Untuk informasi selengkapnya, lihat Menambahkan sumber daya server MySQL dan sumber daya database.

Untuk mengambil objek ExampleDbContext dari layanan:

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

Untuk informasi selengkapnya tentang injeksi dependensi, lihat .NET injeksi dependensi.

Memperkaya konteks database MySQL

Anda mungkin lebih suka menggunakan metode Kerangka Kerja Entitas standar untuk mendapatkan konteks database dan menambahkannya ke kontainer injeksi dependensi:

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseMySql(builder.Configuration.GetConnectionString("mysqldb")
        ?? throw new InvalidOperationException("Connection string 'mysqldb' not found.")));

Nota

Nama string koneksi yang Anda teruskan ke metode GetConnectionString harus cocok dengan nama yang digunakan saat menambahkan sumber daya MySQL dalam proyek host aplikasi. Untuk informasi selengkapnya, lihat Menambahkan sumber daya server MySQL dan sumber daya database.

Anda memiliki lebih banyak fleksibilitas saat membuat konteks database dengan cara ini, misalnya:

  • Anda dapat menggunakan kembali kode konfigurasi yang ada untuk konteks database tanpa menulis ulang untuk .NET.NET Aspire.
  • Anda dapat menggunakan pencegat Entity Framework Core untuk mengubah operasi database.
  • Anda dapat memilih untuk tidak menggunakan pengumpulan konteks Entity Framework Core, yang mungkin berfungsi lebih baik dalam beberapa keadaan.

Jika Anda menggunakan metode ini, Anda dapat meningkatkan konteks database dengan percobaan ulang gaya .NET.NET Aspire, pemeriksaan kesehatan, pengelogan, dan fitur telemetri dengan memanggil metode EnrichMySqlDbContext:

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

Parameter settings adalah instans kelas PomeloEntityFrameworkCoreMySqlSettings.

Konfigurasi

Integrasi .NET Aspire Pomelo MySQLEntity Framework Core menyediakan beberapa opsi untuk mengonfigurasi koneksi database berdasarkan persyaratan dan konvensi proyek Anda.

Menggunakan string koneksi

Saat menggunakan string koneksi dari bagian konfigurasi ConnectionStrings, Anda dapat memberikan nama string koneksi saat memanggil builder.AddMySqlDatabaseDbContext<TContext>():

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

Dan kemudian string koneksi akan diambil dari bagian konfigurasi ConnectionStrings:

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

EnrichMySqlDbContext tidak akan menggunakan bagian konfigurasi ConnectionStrings karena mengharapkan DbContext didaftarkan pada saat dipanggil.

Untuk informasi selengkapnya, lihat dokumentasi MySqlConnector: ConnectionString.

Menggunakan penyedia konfigurasi

Integrasi .NET Aspire Pomelo MySQLEntity Framework Core mendukung Microsoft.Extensions.Configuration. Ini memuat PomeloEntityFrameworkCoreMySqlSettings dari file konfigurasi seperti appsettings.json dengan menggunakan kunci Aspire:Pomelo:EntityFrameworkCore:MySql.

Contoh berikut menunjukkan appsettings.json yang mengonfigurasi beberapa opsi yang tersedia:

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

Untuk skema integrasi MySQLJSON lengkap, lihat Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Gunakan delegasi sebaris

Anda juga dapat mengoper delegate Action<PomeloEntityFrameworkCoreMySqlSettings> untuk mengatur beberapa atau semua opsi secara sebaris, misalnya untuk menonaktifkan pemeriksaan kesehatan dari kode:

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

atau

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

Client pemeriksaan kesehatan integrasi

Secara default, integrasi klien .NET.NET Aspire memiliki pemeriksaan kesehatan yang diaktifkan untuk semua layanan. Demikian pula, banyak integrasi hosting .NET.NET Aspire juga mengaktifkan titik akhir pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat:

Integrasi .NET Aspire Pomelo MySQLEntity Framework Core:

Pengamatan dan telemetri

.NET .NET Aspire integrasi secara otomatis menyiapkan konfigurasi Pengelogan, Pelacakan, dan Metrik, yang terkadang dikenal sebagai pilar pengamatan. Untuk informasi selengkapnya tentang pengamatan integrasi dan telemetri, lihat gambaran umum integrasi .NET.NET Aspire. Bergantung pada layanan pendukung, beberapa integrasi mungkin hanya mendukung beberapa fitur ini. Misalnya, beberapa integrasi mendukung pengelogan dan pelacakan, tetapi bukan metrik. Fitur telemetri juga dapat dinonaktifkan menggunakan teknik yang disajikan di bagian Konfigurasi .

Pencatatan

Integrasi .NET Aspire Pomelo MySQLEntity Framework Core menggunakan kategori log berikut:

  • 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

Menelusuri

Integrasi .NET Aspire Pomelo MySQLEntity Framework Core akan memancarkan aktivitas pelacakan berikut menggunakan OpenTelemetry:

  • MySqlConnector

Metrik

Integrasi .NET Aspire Pomelo MySQLEntity Framework Core saat ini mendukung metrik berikut:

  • 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

Lihat juga