Partilhar via

.NET Aspire MySQL integração

Inclui:Integração de hospedagem incluída Integração de hospedagem —&— Client integração incluídaClient integração

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 base de dados .NET AspireMySQL permite ligar-se a bases de dados existentes MySQL ou criar novas instâncias a partir da imagem do .NET.

Integração de hospedagem

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

dotnet add package Aspire.Hosting.MySql

Para obter mais informações, consulte dotnet add package ou .NET.

Adicionar MySQL recurso de servidor e recurso 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 do 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 ASP.NET Core e Adicionar MySQL recurso com parâmetros.

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

Dica

Se você preferir se conectar a um servidor MySQL existente, 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 é usado para manter os dados do servidor MySQL 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 relação às montagens de ligação, consulte Docker docs: 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.

Importante

Algumas integrações de banco de dados, incluindo a integração .NET AspireMySQL, não podem usar volumes de dados com êxito após a implantação no Azure Container Apps (ACA). Isso ocorre porque o ACA usa Server o Message Block (SMB) para conectar contêineres a volumes de dados e alguns sistemas não podem usar essa conexão. No Painel Aspire, uma base de dados afetada por este problema tem um estado de Ativação ou Falha na ativação, mas nunca é listada como Em execução.

Você pode resolver o problema implantando em um Kubernetes cluster, como AzureKubernetes Serviços (AKS). Para obter mais informações, consulte .NET.NET Aspire implementações.

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

As montagens de ligação de dados têm funcionalidade limitada em comparação com os 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 Docker docs: 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 verifica se o servidor MySQL 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 .

Client integração

Para começar a integração da base de dados .NET AspireMySQL, instale o pacote NuGet 📦Aspire.MySqlConnector no projeto que consome o cliente, ou seja, o projeto para a aplicação que usa o cliente MySQL. A integração do cliente MySQL registra uma instância MySqlConnector.MySqlDataSource que você pode usar para interagir com o servidor MySQL.

dotnet add package Aspire.MySqlConnector

Para obter mais informações, consulte dotnet add package ou .NET.

Adicionar uma fonte de dados MySQL

No arquivo de Program.cs do seu projeto que consome cliente, chame o método de extensão AddMySqlDataSource para registrar um MySqlDataSource para uso por meio do contêiner de injeção de dependência. 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 MySQL recurso de servidor 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 obter mais informações sobre 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 com chave, consulte .NET injeção de dependência: serviços com 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 conexã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 obter o esquema de integração MySQL completoJSON, 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 As integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte .NET.NET Aspire Visão geral de integrações. 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. As funcionalidades de telemetria também podem ser desativadas usando as técnicas apresentadas na secçã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