интеграция .NET AspireMySQL

Статья
12/13/2024

Включает:интеграция хостинга и Client интеграции

MySQL — это система управления реляционными базами данных с открытым исходным кодом (RDBMS), использующая язык структурированных запросов (SQL) для управления данными и управления ими. Он используется в различных средах, от небольших проектов до крупномасштабных корпоративных систем, и это популярный выбор для размещения данных, которые лежат в основе микрослужб в облачном приложении. Интеграция базы данных .NET AspireMySQL дает возможность подключаться к существующим базам данных MySQL или создавать новые экземпляры из .NET с образом контейнера mysql.

Интеграция хостинга

MySQL интеграции моделируют server в качестве типа MySqlServerResource и базы данных в качестве типа MySqlDatabaseResource. Чтобы получить доступ к этим типам и API, добавьте пакет NuGet 📦Aspire.Хостинг.MySql в проект узла приложения .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MySql

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

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавление ресурса MySQLserver и ресурса базы данных

В проекте хоста вашего приложения вызовите AddMySql, чтобы добавить и вернуть построитель ресурсов MySQL. Свяжите вызов возвращаемого построителя ресурсов для AddDatabase, чтобы добавить ресурс базы данных 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...

Заметка

Контейнер SQL Server медленно запускается, поэтому рекомендуется использовать постоянное время существования, чтобы избежать ненужных перезапусков. Дополнительные сведения см. в времени существования ресурса контейнера.

Когда .NET.NET Aspire добавляет контейнерный образ в хост приложения, как показано в предыдущем примере с образом mysql, на вашем компьютере создается новый экземпляр MySQL. Ссылка на построитель ресурсов MySQL (переменная mysql) используется для добавления базы данных. База данных называется mysqldb, а затем добавляется в ExampleProject. Ресурс MySQL включает учетные данные по умолчанию с характеристикой username, значение которой равно root, и случайным password, созданным с использованием метода CreateDefaultPasswordParameter.

При запуске хоста приложения пароль сохраняется в хранилище секретов этого хоста. Он добавлен в раздел Parameters, например:

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

Имя параметра — mysql-password, но на самом деле это просто форматирование имени ресурса с -password суффиксом. Дополнительные сведения см. в разделе Безопасное хранение секретов приложений в разработке в ASP.NET Core и Добавление ресурса MySQL с параметрами.

Метод WithReference настраивает подключение в ExampleProject с именем mysqldb.

Совет

Если вы хотите подключиться к существующей MySQLserver, вызовите AddConnectionString вместо этого. Для получения дополнительной информации см. раздел "Существующие ресурсы".

Добавьте ресурс MySQL с томом данных

Чтобы добавить том данных в ресурс SQL Server, вызовите метод WithDataVolume в ресурсе 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...

Том данных используется для сохранения MySQLserver данных за пределами жизненного цикла контейнера. Том данных подключается по пути /var/lib/mysql в контейнере SQL Server и когда параметр name не указан, имя создается случайным образом. Дополнительные сведения о больших объемах данных и о том, почему они предпочтительнее, чем монтирование с привязкой , см. в документации Docker: Томы.

Предупреждение

Пароль хранится в томе данных. При использовании тома данных и при изменении пароля он не будет работать, пока не удалите том.

Добавление ресурса MySQL с подключением привязки данных

Чтобы добавить подключение привязки данных к ресурсу MySQL, вызовите метод 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...

Важный

Подключения привязки данных имеют ограниченные функциональные возможности по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для рабочих сред. Однако привязки каталогов позволяют напрямую получать доступ и изменять файлы в хост-системе, что идеально подходит для разработки и тестирования, когда требуются изменения в режиме реального времени.

Подключения к файловой системе данных зависят от файловой системы хост-компьютера для постоянного хранения данных MySQL при перезапусках контейнера. Подключение привязки данных подключено к C:\MySql\Data в Windows (или /MySql/Data на Unix) пути на хост-компьютере в контейнере MySQL. Дополнительные сведения о подключениях привязки данных см. в документации по Docker: привязка подключений.

Добавление ресурса MySQL с параметрами

Если вы хотите явно указать корневой MySQL пароль, его можно передать в качестве параметра. Рассмотрим следующий альтернативный пример:

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

Дополнительные сведения см. в разделе Внешние параметры.

Добавление ресурса PhpMyAdmin

phpMyAdmin — это популярное средство администрирования с веб-интерфейсом для MySQL. Его можно использовать для просмотра и изменения объектов MySQL, таких как базы данных, таблицы, представления и индексы. Чтобы использовать phpMyAdmin в решении .NET.NET Aspire, вызовите метод WithPhpMyAdmin. Этот метод добавляет новый ресурс контейнера в решение, на котором размещен phpMyAdmin, и подключает его к контейнеру 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...

При запуске решения панель мониторинга .NET.NET Aspire отображает ресурсы phpMyAdmin с конечной точкой. Выберите ссылку на конечную точку, чтобы просмотреть phpMyAdmin на новой вкладке браузера.

Проверка работоспособности хостинговой интеграции

Интеграция размещения MySQL автоматически добавляет проверку работоспособности ресурса MySQL. Проверка работоспособности проверяет, запущены ли MySQLserver и можно ли установить к ним подключение.

Интеграция размещения зависит от пакета NuGet AspNetCore.HealthChecks 📦.MySql.

интеграция Client

Чтобы приступить к интеграции .NET AspireMySQL базы данных, установите NuGet-пакет 📦Aspire.MySqlConnector в проект, использующий client, то есть в проект приложения, которое работает с MySQLclient. Интеграция MySQLclient регистрирует экземпляр MySqlConnector.MySqlDataSource, который можно использовать для взаимодействия с MySQLserver.

.NET интерфейс командной строки
PackageReference

dotnet add package Aspire.MySqlConnector

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

Дополнительные сведения см. в статьях dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавьте источник данных MySQL

В файле Program.cs вашего проекта, использующего client, вызовите метод расширения AddMySqlDataSource, чтобы зарегистрировать MySqlDataSource для использования через контейнер внедрения зависимостей. Метод принимает параметр connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Кончик

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса базы данных MySQL в проект узла приложения. Другими словами, при вызове AddDatabase и указании имени mysqldb то же имя следует использовать при вызове AddMySqlDataSource. Дополнительные сведения см. в разделе Добавление MySQLserver ресурсов и ресурсов базы данных.

Затем можно получить экземпляр MySqlConnector.MySqlDataSource методом внедрения зависимостей. Например, чтобы получить источник данных из примера службы:

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

Дополнительные сведения о внедрении зависимостей см. в .NET.

Добавьте источник данных с ключом MySQL

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров MySqlDataSource с различными именами подключений. Чтобы зарегистрировать ключи MySQL источников данных, вызовите метод AddKeyedMySqlDataSource:

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

Важный

При использовании ключевых служб ожидается, что ресурс MySQL настраивает две именованные базы данных, одну для mainDb и одну для loggingDb.

Затем вы можете получить экземпляры MySqlDatSource с помощью метода внедрения зависимостей. Например, чтобы получить подключение из примера службы:

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

Дополнительные сведения о ключевых службах см. раздел .NET внедрение зависимостей: ключевые службы.

Конфигурация

Интеграция .NET AspireMySQL базы данных предоставляет несколько вариантов настройки подключения на основе требований и соглашений проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове метода AddMySqlDataSource:

builder.AddMySqlDataSource(connectionName: "mysql");

Затем строка подключения извлекается из раздела конфигурации ConnectionStrings:

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

Дополнительные сведения о форматировании этой строки подключения см. в MySqlConnector: документация по ConnectionString.

Использование поставщиков конфигураций

Интеграция базы данных .NET AspireMySQL поддерживает Microsoft.Extensions.Configuration. Он загружает MySqlConnectorSettings из конфигурации, используя ключ Aspire:MySqlConnector. Следующий фрагмент кода является примером файла appsettings.json, который настраивает некоторые параметры:

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

Для полной схемы интеграции MySQLJSON смотрите в Aspire. MySqlConnector/ConfigurationSchema.json.

Использование встроенных делегатов

Кроме того, можно передать делегат Action<MySqlConnectorSettings>, чтобы настроить некоторые или все параметры встроенным образом, например, отключить проверки работоспособности прямо из кода.

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

Client проверки работоспособности интеграции

По умолчанию .NET.NET Aspire интеграции позволяют проверки работоспособности для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.

Интеграция базы данных .NET AspireMySQL:

Добавляет проверку работоспособности, когда MySqlConnectorSettings.DisableHealthChecksfalse, которая проверяет, можно ли выполнить подключение и выполнять команды в базе данных MySQL.
Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки работоспособности должны быть успешными, чтобы приложение считалось готовым принять трафик.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации журналирования, трассировки и метрик, которые иногда называются основами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireMySQL использует следующие категории журналов:

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

Отслеживание

Интеграция .NET AspireMySQL выдает следующие действия трассировки с помощью OpenTelemetry:

MySqlConnector

Метрика

Интеграция .NET AspireMySQL будет выдавать следующие метрики с помощью 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

См. также

MySQL база данных
пример контейнеров базы данных .NET.NET Aspire
интеграции .NET.NET Aspire
.NET Aspire GitHub репозиторий

Поделиться через