.NET Aspire MySQL integração

Inclui: integraçãode alojamento e integraçãoClient

MySQL é um sistema de gerenciamento de banco de dados relacional (RDBMS) de código aberto que usa linguagem de consulta estruturada (SQL) para gerenciar e manipular dados. Ele é empregado em muitos ambientes diferentes, de pequenos projetos a sistemas corporativos de grande escala, e é uma escolha popular para hospedar dados que sustentam microsserviços em um aplicativo nativo da 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 a partir de .NET com a imagem de contêiner mysql.

Integração de hospedagem

A integração de hospedagem MySQL modela o server como o tipo MySqlServerResource e o banco de dados como o tipo MySqlDatabaseResource. Para aceder a esses tipos e APIs, adicione o 📦Aspire.Hosting.MySql pacote NuGet no aplicação host projeto.

.NET CLI

dotnet add package Aspire.Hosting.MySql

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

Para obter mais informações, consulte dotnet add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar recursos MySQLserver e de banco de dados.

No seu projeto anfitrião de aplicação, chame AddMySql para adicionar e retornar um criador de recursos MySQL. Encadeie uma chamada ao construtor de recursos devolvido em AddDatabasepara adicionar um recurso de base 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...

Observação

O contêiner SQL Server é lento para iniciar, por isso é melhor usar uma vida útil persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Tempo de vida do recurso de contêiner.

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, como mostrado no exemplo anterior com a imagem mysql, ele cria uma nova instância de MySQL em sua máquina local. Uma referência ao seu MySQL construtor de recursos (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 da aplicação é executado, a senha é armazenada no armazenamento secreto do host da aplicação. 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 de aplicativos em desenvolvimento no ASP.NET Core e Adicionar MySQL recurso com parâmetros.

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

Dica

Se preferir conectar-se a um MySQLserverexistente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a 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 é utilizado para persistir os dados MySQLserver fora do ciclo de vida do seu contentor. 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 relação a montagens de ligação bind , consulte a documentação Docker: Volumes.

Advertência

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 ligaçã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 suportes de ligação de de dados 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, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos da máquina host para manter os dados MySQL nas reinicializações do contêiner. A montagem de associação de dados é montada no caminho C:\MySql\Data no Windows (ou /MySql/Data no Unix) na máquina host no contêiner MySQL. Para obter mais informações sobre montagens de ligação de dados, consulte a documentação Docker: Bind mounts.

Adicionar MySQL recurso com parâmetros

Quando você quiser fornecer uma senha de MySQL root explicitamente, você 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 procurar e modificar objetos MySQL, como bancos de dados, tabelas, exibições e índices. Para usar o phpMyAdmin dentro de sua solução .NET.NET Aspire, chame o método WithPhpMyAdmin. Este método adiciona um novo recurso de contêiner à solução que hospeda o 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 se executa a solução, a interface .NET.NET Aspire exibe os recursos do phpMyAdmin com um endpoint. Selecione o link para o endpoint para visualizar o phpMyAdmin em uma nova guia do navegador.

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

A integração de hospedagem MySQL adiciona automaticamente uma verificação de integridade para o recurso MySQL. A verificação de integridade assegura que o MySQLserver esteja ativo e que uma conexão possa ser estabelecida com ele.

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

Client integração

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

.NET CLI

dotnet add package Aspire.MySqlConnector

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

Para obter mais informações, consulte dotnet add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar uma fonte de dados MySQL

No arquivo de Program.cs do seu projeto que consome client, chame o método de extensão AddMySqlDataSource para registar um MySqlDataSource para uso através do contentor 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 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 MySQLserver recurso e recurso de banco de dados.

Em seguida, você pode recuperar a instância 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 mais informações acerca da injeção de dependência, consulte .NET injeção de dependência.

Adicione fonte de dados de chave MySQL

Pode haver situações em que você queira registrar várias instâncias de MySqlDataSource com nomes de conexão diferentes. Para registrar fontes de dados MySQL chaveadas, 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 MySQL configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Em seguida, podes recuperar as instâncias MySqlDatSource utilizando 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 identificados por chave, consulte .NET injeção de dependência: Serviços identificados por chave.

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 cadeia de conexão

Ao usar uma cadeia de conexão da seção ConnectionStrings configuração, 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 obter mais informações sobre como formatar essa cadeia de ligação, consulte a documentação de MySqlConnector: ConnectionString.

Usar provedores de configuração

A integração de banco de dados .NET AspireMySQL suporta Microsoft.Extensions.Configuration. Ele carrega o MySqlConnectorSettings a partir da configuração usando a chave Aspire:MySqlConnector. O trecho 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 o esquema completo de MySQL integração JSON, consulte Aspire. MySqlConnector/ConfigurationSchema.json.

Usar delegados embutidos

Além disso, pode passar a delegação Action<MySqlConnectorSettings> para configurar algumas ou todas as opções embutidas, por exemplo, para desativar as verificações de integridade a partir do código.

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

Client verificações de saúde da integração

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

A integração de 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 com o ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registadas devem passar para que o aplicativo seja considerado pronto para receber tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente o Registo, Rastreamento e Métricas, que por vezes são conhecidos como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na seção de Configuração.

Registo

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

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

Rastreio

A integração .NET AspireMySQL emite as seguintes atividades de rastreio utilizando 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

Ver também

• MySQL base de dados
• .NET .NET Aspire amostra de contêineres de banco de dados
• .NET .NET Aspire integrações
• .NET Aspire GitHub repo