Partilhar via

.NET Aspire Pomelo MySQLEntity Framework Core integração

  • Artigo

Inclui:integração de Hosting e Client 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 .NET Aspire Pomelo MySQLEntity Framework Core 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 acessar esses tipos e APIs, adicione o 📦Aspire. Hospedagem.MySql pacote NuGet no aplicativo host projeto.

dotnet add package Aspire.Hosting.MySql

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

Adicionar os recursos de MySQL,server e de banco de dados.

No seu projeto host de aplicação, chame AddMySql para adicionar e retornar um construtor de recursos MySQL. Encadeie uma chamada para o construtor de recursos retornado para AddDatabase, para 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...

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 repositório 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 , onde pode adicionar o recurso MySQL com os 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 é usado para manter os dados MySQLserver fora do ciclo de vida do seu contenedor. 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 do tipo bind , consulte a documentação em 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 associaçã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...

Ao executar-se a solução, o painel .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 confirma se o MySQLserver está operacional e se uma conexão pode ser estabelecida com ele.

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

Client integração

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

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

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

Adicionar um novo contexto de banco de dados MySQL

No arquivo de Program.cs do seu projeto de consumo de client, chame o método de extensão de 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 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 o recurso MySQLserver e o recurso de base de dados.

Para recuperar o objeto ExampleDbContext a partir de um serviço:

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

Para mais informações sobre a injeção de dependência, veja .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 MySQLEntity Framework Core.NET Aspire Pomelo 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 cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração de ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddMySqlDatabaseDbContext<TContext>():

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

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

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

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

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

Usar provedores de configuração

A integração .NET Aspire Pomelo MySQLEntity Framework Core suporta 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 MySQL integração JSON, consulte Aspire. Pomelo.EntityFrameworkCore.MySql/ConfigurationSchema.json.

Usar delegados em linha

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

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

ou

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

Controlos sanitários

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

Observabilidade e telemetria

.NET .NET Aspire integrações regulam automaticamente o Registo, Rastreamento e Métricas, que às 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 Configuração.

Registo

A integração .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

Rastreio

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

  • MySqlConnector

Métricas

A integração .NET Aspire Pomelo MySQLEntity Framework Core suporta atualmente as 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

Ver também