Compartilhar via

.NET Aspire Pomelo MySQLEntity Framework Core integração

  • 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 .NET Aspire Pomelo MySQLEntity Framework Core 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

A integração de hospedagem do 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 no projeto de host do aplicativo no.

dotnet add package Aspire.Hosting.MySql

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

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. Encadeie uma chamada para o construtor de recursos retornado para AddDatabase, a fim de 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 SQL Server é lento para iniciar, portanto, é melhor usar um ciclo de vida persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Vida útil do recurso do 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 Referenciar 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 preferenciais em vez de associar montagens, consulte Docker documentos: 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 associaçã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, bind mounts (montagens de associação) permitem acesso direto e modificação de arquivos no sistema host, o que é ideal para desenvolvimento e teste, onde são necessárias alterações em tempo real.

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

Adicionar MySQL recurso com parâmetros

Quando você deseja fornecer explicitamente uma senha raiz 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 .NET.NET Aspire exibe os recursos do phpMyAdmin com um endereço. Selecione o link para o endpoint para exibir phpMyAdmin em uma nova aba do navegador.

Verificações de saúde da 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 verifica se o MySQLserver está em execução e se uma conexão pode ser estabelecida com ele.

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

integração Client

Para começar a usar a integração .NET Aspire Pomelo MySQL Entity Framework, instale o 📦Aspire. Pomelo.EntityFrameworkCore.MySql pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que usa o MySQLEntity Framework Coreclient.

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

Adicione um contexto de banco de dados MySQL

No arquivo Program.cs do seu projeto de consumo de client, chame o método de extensão AddMySqlDbContext em qualquer IHostApplicationBuilder para registrar um DbContext para uso por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddMySqlDbContext<ExampleDbContext>(connectionName: "mysqldb");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso de banco de dados SQL Server 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 AddMySqlDbContext. Para obter mais informações, consulte Adicionar MySQLserver e recurso de banco de dados.

Para recuperar o objeto ExampleDbContext de um serviço:

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

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

Adicionar um contexto de banco de dados MySQL com enriquecimento

Para enriquecer o DbContext com serviços adicionais, como repetições automáticas, verificações de integridade, registro em log e telemetria, chame o método EnrichMySqlDbContext:

builder.EnrichMySqlDbContext<ExampleDbContext>(
    connectionName: "mysqldb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

O parâmetro settings é uma instância da classe PomeloEntityFrameworkCoreMySqlSettings.

Configuração

A integração .NET Aspire Pomelo MySQLEntity Framework Core fornece várias opções para configurar a conexão de banco de dados 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 builder.AddMySqlDatabaseDbContext<TContext>():

builder.AddMySqlDatabaseDbContext<MyDbContext>("mysql");

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

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

O EnrichMySqlDbContext não usará a seção de configuração de ConnectionStrings, pois espera que um DbContext seja registrado no ponto em que é chamado.

Para obter mais informações, consulte a documentação MySqlConnector: ConnectionString.

Usar provedores de configuração

A integração do .NET Aspire Pomelo MySQLEntity Framework Core dá suporte a Microsoft.Extensions.Configuration. Ele carrega o PomeloEntityFrameworkCoreMySqlSettings de arquivos de configuração, como appsettings.json usando a chave Aspire:Pomelo:EntityFrameworkCore:MySql.

O exemplo a seguir mostra um appsettings.json que configura algumas das opções disponíveis:

{
  "Aspire": {
    "Pomelo": {
      "EntityFrameworkCore": {
        "MySql": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Para o esquema completo de integração MySQLJSON, consulte Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Usar delegados embutidos

Você também pode passar o delegado Action<PomeloEntityFrameworkCoreMySqlSettings> para configurar algumas ou todas as opções embutidas, por exemplo, para desabilitar verificações de integridade do código:

builder.AddMySqlDbContext<MyDbContext>(
    "mysqldb",
    static settings => settings.DisableHealthChecks = true);

ou

builder.EnrichMySqlDbContext<MyDbContext>(
    static settings => settings.DisableHealthChecks = true);

Verificações de saúde

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 .NET Aspire Pomelo MySQLEntity Framework Core:

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 Atividades

A integração do .NET Aspire Pomelo MySQLEntity Framework Core usa as seguintes categorias de log:

  • Microsoft.EntityFrameworkCore.ChangeTracking
  • Microsoft.EntityFrameworkCore.Database.Command
  • Microsoft.EntityFrameworkCore.Database.Connection
  • Microsoft.EntityFrameworkCore.Database.Transaction
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Migrations
  • Microsoft.EntityFrameworkCore.Model
  • Microsoft.EntityFrameworkCore.Model.Validation
  • Microsoft.EntityFrameworkCore.Query
  • Microsoft.EntityFrameworkCore.Update

Rastreamento

A integração do .NET Aspire Pomelo MySQLEntity Framework Core emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • MySqlConnector

Métricas

A integração do .NET Aspire Pomelo MySQLEntity Framework Core atualmente dá suporte às seguintes métricas:

  • 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