Compartilhar via

integração .NET AspireMySQL

  • Artigo

Inclui:integração de hospedagem e Client integração

MySQL é um RDBMS (Sistema de Gerenciamento de Banco de Dados Relacional) de software livre que usa SQL (Structured Query Language) para gerenciar e manipular dados. Ele é empregado em vários ambientes diferentes, desde pequenos projetos até sistemas empresariais em grande escala e é uma escolha popular hospedar dados que sustentam microsserviços em um aplicativo nativo de nuvem. A integração de banco de dados .NET AspireMySQL permite que você se conecte a bancos de dados MySQL existentes ou crie novas instâncias de .NET com a imagem de contêiner mysql.

Integração de hospedagem

O modelo de integração de hospedagem MySQL modela o server como o tipo MySqlServerResource e o banco de dados como o tipo MySqlDatabaseResource. Para acessar esses tipos e APIs, adicione o 📦Aspire.Hosting.MySql pacote NuGet para o projeto host do aplicativo .

dotnet add package Aspire.Hosting.MySql

Para obter mais informações, consulte dotnet adicionar pacote ou Gerenciar dependências de pacotes em aplicativos .NET.

Adicionar recurso MySQLserver e recurso de banco de dados

No projeto de host do aplicativo, chame AddMySql para adicionar e retornar um construtor de recursos MySQL. Encadear uma chamada ao construtor de recursos retornado para AddDatabasepara adicionar um recurso de banco de dados 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

O contêiner de é lento para começar, portanto, é melhor usar um tempo de vida persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Vida útil do recurso contêiner.

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem mysql, ele cria uma nova instância de MySQL em seu computador local. Uma referência ao construtor de recursos MySQL (a variável mysql) é usada para adicionar um banco de dados. O banco de dados é nomeado mysqldb e, em seguida, adicionado ao ExampleProject. O recurso MySQL inclui credenciais padrão com um username de root e um password aleatório gerado usando o método CreateDefaultPasswordParameter.

Quando o host do aplicativo é executado, a senha é armazenada no repositório secreto do host do aplicativo. Ele é adicionado à seção Parameters, por exemplo:

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

O nome do parâmetro é mysql-password, mas na verdade é apenas formatar o nome do recurso com um sufixo -password. Para obter mais informações, consulte Armazenamento seguro de segredos do aplicativo no desenvolvimento em ASP.NET Core e Adicionar MySQL recurso com parâmetros.

O método WithReference configura uma conexão no ExampleProject denominado mysqldb.

Dica

Se você preferir se conectar a um MySQLserverexistente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Recursos existentes.

Adicionar um recurso MySQL com um volume de dados

Para adicionar um volume de dados ao recurso SQL Server, chame o método WithDataVolume no recurso 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...

O volume de dados é usado para persistir os dados MySQLserver fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /var/lib/mysql no contêiner SQL Server e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de montagens vinculadas, consulte a Docker documentação: Volumes.

Aviso

A senha é armazenada no volume de dados. Ao usar um volume de dados e se a senha for alterada, ela não funcionará até que você exclua o volume.

Adicionar um recurso MySQL com uma montagem de associação de dados

Para adicionar uma montagem de vinculação de dados ao recurso MySQL, chame o método 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...

Importante

Os de dados associam montagens têm funcionalidade limitada em comparação com volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, os bind mounts permitem acesso direto e modificação de arquivos no sistema host, sendo ideal para desenvolvimento e teste onde são necessárias alterações em tempo real.

As montagens de dados vinculados dependem do sistema de arquivos da máquina host para manter os dados MySQL entre reinicializações do contêiner. A montagem de associação de dados é feita no caminho C:\MySql\Data no Windows (ou /MySql/Data no Unix) da máquina host no contêiner MySQL. Para obter mais informações sobre montagens bind de dados, consulte os documentos Docker: Montagens bind.

Adicionar MySQL recurso com parâmetros

Se você quiser fornecer explicitamente uma senha root MySQL, pode passá-la como um parâmetro. Considere o seguinte exemplo alternativo:

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

Para obter mais informações, consulte Parâmetros externos.

Adicionar um recurso phpMyAdmin

phpMyAdmin é uma ferramenta de administração popular baseada na Web para MySQL. Você pode usá-lo para navegar e modificar MySQL objetos, como bancos de dados, tabelas, exibições e índices. Para usar phpMyAdmin em sua solução de .NET.NET Aspire, chame o método WithPhpMyAdmin. Esse método adiciona um novo recurso de contêiner à solução que hospeda phpMyAdmin e o conecta ao contêiner 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...

Quando você executa a solução, o painel de controle .NET.NET Aspire exibe os recursos phpMyAdmin com um endpoint. Selecione o link para o endpoint para abrir o phpMyAdmin em uma nova guia do navegador.

Verificações de integridade de integração de hospedagem

A integração de hospedagem MySQL adiciona automaticamente uma verificação de integridade para o recurso de MySQL. A verificação de integridade confirma se o MySQLserver está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do pacote NuGet AspNetCore.HealthChecks 📦.MySql.

integração Client

Para começar a usar a integração de banco de dados .NET AspireMySQL, instale o pacote NuGet 📦Aspire.MySqlConnector no projeto que está consumindo o client, ou seja, o projeto do aplicativo que usa o MySQLclient. A integração MySQLclient registra uma instância de MySqlConnector.MySqlDataSource que você pode usar para interagir com o MySQLserver.

dotnet add package Aspire.MySqlConnector

Para obter mais informações, consulte dotnet adicionar pacote ou Gerenciar dependências de pacotes em aplicativos .NET.

Adicionar uma fonte de dados MySQL

No arquivo Program.cs do seu projeto consumidor de client, chame o método de extensão AddMySqlDataSource para registrar um MySqlDataSource para uso por meio do contêiner de injeção de dependências. O método usa um parâmetro connectionName.

builder.AddMySqlDataSource(connectionName: "mysqldb");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso de banco de dados MySQL no projeto de host do aplicativo. Em outras palavras, quando você chama AddDatabase e fornece um nome de mysqldb esse mesmo nome deve ser usado ao chamar AddMySqlDataSource. Para obter mais informações, consulte Adicionar MySQLrecursoserver e recurso de banco de dados.

Em seguida, você pode recuperar a instância de MySqlConnector.MySqlDataSource usando a injeção de dependência. Por exemplo, para recuperar a fonte de dados de um serviço de exemplo:

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

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar fonte de dados chave MySQL

Pode haver situações em que você deseja registrar várias instâncias de MySqlDataSource com nomes de conexão diferentes. Para registrar fontes de dados chaveadas MySQL, chame o método AddKeyedMySqlDataSource.

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

Importante

Ao usar serviços com chave, espera-se que seu recurso de MySQL configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Em seguida, você pode recuperar as instâncias de MySqlDatSource usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre serviços chaveados, consulte .NET injeção de dependência: serviços chaveados.

Configuração

A integração de banco de dados .NET AspireMySQL fornece várias opções para configurar a conexão com base nos requisitos e convenções do seu projeto.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar AddMySqlDataSource método:

builder.AddMySqlDataSource(connectionName: "mysql");

Em seguida, a cadeia de conexão é recuperada da seção de configuração ConnectionStrings:

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

Para mais informações sobre como formatar esta cadeia de conexão, consulte a documentação da cadeia de conexão do MySqlConnector .

Usar provedores de configuração

A integração de banco de dados .NET AspireMySQL dá suporte a Microsoft.Extensions.Configuration. Ele carrega a MySqlConnectorSettings da configuração usando a chave Aspire:MySqlConnector. O snippet a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

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

Para obter o esquema de integração completo MySQLJSON, consulte AspireMySqlConnector/ConfigurationSchema.json.

Usar delegados embutidos

Além disso, você pode passar o delegado Action<MySqlConnectorSettings> para configurar algumas ou todas as opções diretamente no código, por exemplo, para desabilitar verificações de integridade através do código.

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

Client verificações de integridade de integração

Por padrão, as integrações .NET.NET Aspire habilitam verificações de saúde para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

A integração do banco de dados .NET AspireMySQL:

  • Adiciona a verificação de integridade quando MySqlConnectorSettings.DisableHealthChecks é false, que verifica se uma conexão pode ser feita e os comandos podem ser executados no banco de dados MySQL.
  • Integra-se ao ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registradas devem passar para que o aplicativo seja considerado pronto para aceitar o tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro de Logs

A integração .NET AspireMySQL usa as seguintes categorias de log:

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

Rastreamento

A integração .NET AspireMySQL emite as seguintes atividades de rastreamento usando OpenTelemetry:

  • MySqlConnector

Métricas

A integração .NET AspireMySQL emitirá as seguintes métricas usando 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

Consulte também