Get started with the MySQL Pomelo Entity Framework Core integrations

MySQL is an open-source Relational Database Management System (RDBMS) that uses Structured Query Language (SQL) to manage and manipulate data. It’s employed in many different environments, from small projects to large-scale enterprise systems and it’s a popular choice to host data that underpins microservices in a cloud-native application. The Aspire Pomelo MySQL Entity Framework Core integration enables you to connect to existing MySQL databases or create new instances from .NET with the mysql container image. Entity Framework Core (EF Core) is an object-database mapper that simplifies data access by allowing developers to work with databases using .NET objects.

In this introduction, you’ll see how to install and use the Aspire MySQL Pomelo Entity Framework Core integrations in a simple configuration. If you already have this knowledge, see MySQL Hosting integration and MySQL Pomelo Entity Framework Core Client integration reference for full reference details.

Nota

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire MySQL Hosting integration in your Aspire AppHost project. This integration allows you to create and manage MySQL database instances from your Aspire hosting projects:

Aspire CLI

Aspire CLI — Adicionar pacote Aspire.Hosting.MySql

aspire add mysql

A Aspire CLI é interativa; escolha o resultado adequado quando solicitado:

Aspire CLI — Exemplo de saída

Select an integration to add:

> mysql (Aspire.Hosting.MySql)
> Other results listed as selectable options...

Nota

Se houver apenas um resultado ele será escolhido automaticamente. Confirme a versão mesmo assim.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.MySql@*

PackageReference (*.csproj)

XML — Adicionar referência de pacote Aspire.Hosting.MySql

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

Next, in the AppHost project, create instances of MySQL server and database resources, then pass the database to the consuming client projects:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql")
                   .WithLifetime(ContainerLifetime.Persistent);

var mysqldb = mysql.AddDatabase("mysqldb");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
                            .WaitFor(mysqldb)
                            .WithReference(mysqldb);

Dica

This is the simplest implementation of MySQL resources in the AppHost. There are many more options you can choose from to address your requirements. For full details, see MySQL Hosting integration.

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire MySQL Pomelo EF Core client integration:

.NET CLI

.NET CLI — Add Aspire.Pomelo.EntityFrameworkCore.MySql package

dotnet add package Aspire.Pomelo.EntityFrameworkCore.MySql

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Pomelo.EntityFrameworkCore.MySql@*

PackageReference (*.csproj)

XML — Add Aspire.Pomelo.EntityFrameworkCore.MySql package reference

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

In the Program.cs file of your client-consuming project, call the AddMySqlDbContext extension method on any IHostApplicationBuilder to register a DbContext for use through the dependency injection container. The method takes a connection name parameter.

C# — Program.cs

builder.AddMySqlDbContext<MyDbContext>("mysqldb");

Dica

The connectionName parameter must match the name used when adding the MySQL database resource in the AppHost project. For more information, see Set up hosting integration.

Use injected MySQL properties

In the AppHost, when you used the WithReference method to pass a MySQL database resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called mysqldb becomes MYSQLDB_URI.

Use the GetValue() method to obtain these environment variables in consuming projects:

C# - Obtain configuration properties

string connectionString = builder.Configuration.GetValue<string>("ConnectionStrings__mysqldb");
string host = builder.Configuration.GetValue<string>("MYSQLDB_HOST");
string databaseName = builder.Configuration.GetValue<string>("MYSQLDB_DATABASENAME");

Dica

The full set of properties that Aspire injects depends on the MySQL resource configuration. For more information, see Properties of the MySQL resources.

Use MySQL resources in client code

Now that you’ve added the DbContext to the builder in the consuming project, you can use the MySQL database. Get the DbContext instance using dependency injection. For example, to retrieve your data source object from an example service, define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

C# — ExampleService.cs

public class ExampleService(MyDbContext context)
{
    // Use MySQL DB Context...
}

Having obtained the data context, you can work with the MySQL database as you would in any other C# application using EF Core.

Next steps

Now that you have an Aspire app with MySQL Pomelo EF Core integrations up and running, you can use the following reference documents to learn how to configure and interact with the MySQL resources:

Understand the MySQL hosting integration Discover how to configure data volumes, phpMyAdmin, and more.

Understand the MySQL client integration Learn about the MySQL client integration, including connection strings and observability.