integrasi .NET AspireMySQL

Meliputi:integrasi hosting dan Client 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 database .NET AspireMySQL memungkinkan Anda menyambungkan 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

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

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. Lakukan panggilan berantai 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...

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 bernama root dan password acak yang dihasilkan menggunakan metode CreateDefaultPasswordParameter.

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

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

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

Metode WithReference mengonfigurasi koneksi di ExampleProject bernama mysqldb.

Menambahkan sumber daya MySQL dengan volume 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 selengkapnya tentang volume data dan alasan mengapa mereka lebih disukai daripada 'bind mounts' , lihat dokumen Docker: Volumes.

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

Pemasangan bind data bergantung pada sistem file mesin host untuk mempertahankan data MySQL selama peralihan ulang kontainer. 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.

Menambahkan sumber daya MySQL dengan parameter

Ketika Anda ingin memberikan password root MySQL secara eksplisit, Anda dapat menggunakannya 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 mengoperasikan solusi, dasbor .NET.NET Aspire menampilkan sumber daya phpMyAdmin dengan titik akhir. Pilih tautan ke titik akhir untuk melihat phpMyAdmin di tab browser baru.

Pemeriksaan kesehatan integrasi melalui hosting

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.

integrasi Client

Untuk mulai menggunakan integrasi database .NET AspireMySQL, instal paket NuGet 📦Aspire.MySqlConnector dalam proyek yang menggunakan klien, yaitu proyek untuk aplikasi yang menggunakan klien MySQL. Integrasi klien MySQL mendaftarkan instans MySqlConnector.MySqlDataSource yang dapat Anda gunakan untuk berinteraksi dengan server MySQL.

dotnet add package Aspire.MySqlConnector

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

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

Menambahkan sumber data MySQL

Dalam file Program.cs dari proyek yang menggunakan klien Anda, panggil metode ekstensi AddMySqlDataSource untuk mendaftarkan MySqlDataSource dengan menggunakan kontainer injeksi dependensi. Metode ini mengambil parameter connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Anda kemudian dapat mengambil kembali instans MySqlConnector.MySqlDataSource menggunakan injeksi dependensi. Misalnya, untuk mengambil sumber data dari layanan contoh:

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

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

Tambahkan sumber data berindeks MySQL

Mungkin ada situasi di mana Anda ingin mendaftarkan beberapa instans MySqlDataSource dengan nama koneksi yang berbeda. Untuk mendaftarkan sumber data MySQL kunci, panggil metode AddKeyedMySqlDataSource:

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

Kemudian Anda dapat mengambil instans MySqlDatSource dengan menggunakan injeksi ketergantungan. Misalnya, untuk mengambil koneksi dari layanan contoh:

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

Untuk informasi selengkapnya tentang layanan berkunci, lihat .NET injeksi dependensi: Layanan berkunci.

Konfigurasi

Integrasi database .NET AspireMySQL menyediakan beberapa opsi untuk mengonfigurasi koneksi 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 metode AddMySqlDataSource:

builder.AddMySqlDataSource(connectionName: "mysql");

Kemudian string koneksi diambil dari bagian konfigurasi ConnectionStrings:

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

Untuk informasi selengkapnya tentang cara memformat string koneksi ini, lihat dokumentasi MySqlConnector: ConnectionString.

Menggunakan penyedia konfigurasi

Integrasi database .NET AspireMySQL mendukung Microsoft.Extensions.Configuration. Ini memuat MySqlConnectorSettings dari konfigurasi dengan menggunakan kunci Aspire:MySqlConnector. Cuplikan berikut adalah contoh file appsettings.json yang mengonfigurasi beberapa opsi:

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

Untuk skema integrasi MySQLJSON lengkap, lihat Aspire. MySqlConnector/ConfigurationSchema.json.

Menggunakan delegasi sebaris

Anda juga dapat meneruskan delegasi Action<MySqlConnectorSettings> untuk menyiapkan beberapa atau semua opsi secara langsung, misalnya untuk menonaktifkan pemeriksaan kesehatan melalui kode:

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

Client pemeriksaan kesehatan integrasi

Secara default, integrasi .NET.NET Aspire memungkinkan pemeriksaan kesehatan untuk semua layanan. Untuk informasi selengkapnya, lihat gambaran umum integrasi .NET.NET Aspire.

Integrasi database .NET AspireMySQL:

• Menambahkan pemeriksaan kesehatan ketika MySqlConnectorSettings.DisableHealthChecks adalah false, yang memverifikasi bahwa koneksi dapat dibuat dan perintah dapat dijalankan terhadap database MySQL.
• Terintegrasi dengan titik akhir HTTP /health, yang menentukan semua pemeriksaan kesehatan terdaftar harus lulus agar aplikasi dianggap siap menerima lalu lintas.

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 AspireMySQL menggunakan kategori log berikut:

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

Menelusuri

Integrasi .NET AspireMySQL memancarkan aktivitas pelacakan berikut menggunakan OpenTelemetry:

• MySqlConnector

Metrik

Integrasi .NET AspireMySQL akan memancarkan metrik berikut menggunakan 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

Lihat juga

• MySQL database
• .NET .NET Aspire sampel kontainer database
• .NET .NET Aspire integrasi
• .NET Aspire GitHub repo