Stocker des données dans des bases de données compatibles SQL
La pile .NET Aspire est conçue pour accroître votre productivité et vous permettre de créer des applications web robustes, évolutives et sécurisées. Ajouter l’un des composants Aspire pris en charge vous permet de stocker rapidement des données relationnelles structurées.
À l’heure actuelle, les composants de base de données compatibles SQL sont les suivants :
- Bases de données PostgreSQL
- Bases de données SQL
- Bases de données Oracle
- Bases de données MySQL
Remarque
De plus, Microsoft peut intégrer la prise en charge d’autres systèmes de base de données et de systèmes tiers pour compléter cette liste.
Dans cette leçon, découvrez trois de ces composants, quelles sont les bases de données prenant en charge Entity Framework Core, et comment les utiliser pour stocker et récupérer des données.
Ajouter un composant de base de données à votre projet
Quelle que soit la base de données choisie, l’approche permettant d’ajouter un composant de base de données Aspire .NET à votre projet reste la même.
Dans le projet d’hôte d’application :
- Installez le composant d’hébergement .NET Aspire sur le projet d’hôte d’application.
- Enregistrez une base de données et créez un conteneur dédié dans l’hôte d’application de la solution.
- Transmettez une référence aux projets devant accéder au conteneur créé qui héberge la base de données.
Dans les projets qui utilisent la base de données :
- Ajoutez le composant Aspire .NET avec un package NuGet aux projets devant accéder aux données. Le cas échéant et si vous le souhaitez, vous pouvez utiliser un composant .NET Core Entity Framework (EF) à la place.
- Enregistrez la source de données ou le contexte de base de données pour EF dans le fichier Program.cs du projet.
- Utilisez l’injection de dépendances pour injecter la source de données dans vos services.
Examinons les spécificités de la procédure pour chacune des bases de données prises en charge.
Utiliser les composants PostgreSQL .NET Aspire
Les composants PostgreSQL .NET Aspire doivent être modifiés dans le projet d’hôte d’application et tous les microservices qui utilisent les bases de données.
Configurer l’hôte d’application
Commencez par installer le composant d’hébergement qui convient sur l’hôte d’application :
dotnet add package Aspire.Hosting.PostgreSQL --prerelease
Ensuite, pour enregistrer la base de données et créer un conteneur, ajoutez ce code au fichier Program.cs de l’hôte d’application :
var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");
Vous devez également transmettre une référence au service de base de données pour tous les projets qui la consomment :
var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
.WithReference(postgresdb);
Configurer les projets consommateurs
Pour installer le composant PostgreSQL .NET Aspire, utilisez une commande semblable à celle-ci dans vos projets .NET Aspire :
dotnet add package Aspire.Npgsql --prerelease
Sinon, pour utiliser le composant PostgreSQL .NET Aspire Entity Framework Core, utilisez cette commande :
dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL --prerelease
Vous pouvez également utiliser le raccourci Ajouter > Composant Aspire .NET dans Visual Studio pour installer le composant à partir du gestionnaire de package NuGet :
Le code dans le fichier Program.cs du projet *.AppHost crée la base de données et la transmet aux projets qui souhaitent l’utiliser :
var postgres = builder.AddPostgres("pg")
.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.SampleProject>()
.WithReference(postgres);
Certains composants de base de données .NET Aspire vous permettent aussi de créer un conteneur pour les outils de gestion de bases de données. Pour ajouter PgAdmin à votre solution et gérer la base de données PostgreSQL, utilisez le code suivant :
var postgresdb = builder.AddPostgres("pg")
.AddDatabase("postgresdb")
.WithPgAdmin();
Si vous laissez .NET Aspire créer le conteneur, vous n’avez plus besoin d’effectuer de configuration pour connecter PgAdmin à la base de données PostgreSQL. Tout est automatique.
Utiliser une base de données PostgreSQL
Vous devez ajouter une source de données pour représenter la connexion à PostgreSQL dans tout projet avec lequel utiliser la base de données. Dans le fichier Program.cs, le code suivant enregistre la base de données :
builder.AddNpgsqlDataSource("postgresdb");
Sinon, pour utiliser le composant Entity Framework Core, enregistrez le contexte de base de données :
builder.AddNpgsqlDbContext<YourDbContext>("postgresdb");
Une fois la base de données enregistrée dans le projet consommateur, vous pouvez interagir avec la source de données chaque fois que vous en avez besoin en utilisant l’injection de dépendances :
public class YourService(NpgsqlDataSource dataSource)
{
public async Task<IEnumerable<Catalog>> GetCatalog()
{
const string query = "SELECT * FROM catalog";
using var dbConnection = dataSource.OpenConnection();
var results = await dbConnection.QueryAsync<Catalog>(command);
return queryResult.ToArray();
}
}
Vous pouvez aussi récupérer le contexte de base de données YourDbContext pour interagir avec la base de données :
public class YourService(YourDbContext context)
{
public async Task<IEnumerable<Catalog>> GetCatalog()
{
var items = await context.ObjectItems;
if (item is null)
{
return Results.NotFound();
}
else
{
return items;
}
}
}
Configurer le composant PostgreSQL
La pile .NET Aspire tente de réduire le volume de configuration nécessaire. L’injection de dépendances et la découverte de services vous permettent d’accéder à la base de données sans configurer les chaînes de connexion dans vos projets.
Utiliser le projet hôte d’application pour créer le conteneur de base de données et le transmettre en tant que référence aux projets permet aux projets de réception d’accéder à l’emplacement de la base de données, aux chaînes de connexion et aux ports. Il n’est pas nécessaire de gérer des variables d’environnement ou des fichiers appsettings.json.
Toutefois, si vous le souhaitez ou si vous devez disposer d’un contrôle approfondi sur la configuration de la base de données, d’autres options s’offrent à vous.
A l'aide d'une chaîne de connexion
Dans le projet nécessitant la base de données, utilisez une chaîne de connexion pour vous connecter à la base de données. Cette approche est utile lorsque vous devez vous connecter à une base de données qui n’est pas enregistrée dans l’hôte d’application.
builder.AddNpgsqlDataSource("NpgsqlConnectionString");
Vous pouvez ensuite ajouter la chaîne de connexion au fichier de configuration :
{
"ConnectionStrings": {
"NpgsqlConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword"
}
}
Utiliser des fournisseurs de configuration
.NET Aspire intègre une fonctionnalité de composants permettant de prendre en charge Microsoft.Extensions.Configuration. Le composant PostgreSQL prend en charge cette fonctionnalité et recherche par défaut des paramètres avec la clé Aspire:Npgsql. Pour les projets utilisant appsettings.json, la configuration peut ressembler à l’exemple suivant :
{
"Aspire": {
"Npgsql": {
"ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
"HealthChecks": true,
"Tracing": true,
"Metrics": true
}
}
}
La configuration précédente définit la chaîne de connexion, ce qui active les vérifications d’intégrité, le suivi et la mesure pour le composant PostgreSQL. Vous n’avez plus besoin de spécifier la chaîne de connexion dans le code. Il vous suffit d’utiliser builder.AddNpgsqlDataSource();.
Si vous utilisez le composant PostgreSQL Entity Framework Core, vous pouvez utiliser la clé Aspire:Npgsql:EntityFrameworkCore:PostgreSQL pour configurer le contexte de base de données :
{
"Aspire": {
"Npgsql": {
"EntityFrameworkCore": {
"PostgreSQL": {
"ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
"MaxRetryCount": 0,
"HealthChecks": false,
"Tracing": false
}
}
}
}
}
Pour plus d’informations sur les options de configuration Entity Framework, consultez la documentation .NET Aspire.
Utiliser des délégués inline
La dernière option consiste à transmettre un délégué inline configureSettings à la méthode AddNpgsqlDataSource. Ce délégué vous permet de configurer les paramètres du composant de base de données directement avec du code :
builder.AddNpgsqlDataSource(
"postgresdb", static settings => settings.HealthChecks = false);
Utiliser des composants SQL Database .NET Aspire
Le modèle précédent est le même pour le composant SQL Database. Modifiez le projet d’hôte d’application et les microservices qui consomment le service de base de données.
Configurer l’hôte d’application
Pour installer le composant d’hébergement de base de données SQL, utilisez cette commande :
dotnet add package Aspire.Hosting.SqlServer --prerelease
Pour enregistrer le conteneur et la base de données, ajoutez ce code au fichier Program.cs de l’hôte d’application :
var sql = builder.AddSqlServer("sql");
var sqldb = sql.AddDatabase("sqldb");
Ensuite, transmettez une référence au service de base de données pour tous les projets qui la consomment :
var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
.WithReference(sqldb);
Configurer les projets consommateurs
Pour installer le composant SQL Database .NET Aspire, utilisez une commande semblable à celle-ci dans vos projets .NET Aspire :
dotnet add package Aspire.Microsoft.Data.SqlClient --prerelease
Sinon, pour utiliser le composant SQL Server .NET Aspire Entity Framework Core, utilisez cette commande :
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer --prerelease
Vous pouvez aussi ajouter ces packages NuGet en utilisant le raccourci Ajouter > Composant Aspire .NET dans Visual Studio.
Le code du fichier Program.cs du projet *.AppHost permettant d’accéder à la base de données est similaire à l’exemple PostgreSQL :
var sqlServer = builder.AddSqlServer("sql")
.AddDatabase("sqldata");
var myService = builder.AddProject<Projects.MyService>()
.WithReference(sqlServer);
Utiliser une base de données SQL Server
Pour les projets devant disposer d’un accès SQL, ce code dans le fichier Program.cs enregistre le contexte de base de données Entity Framework :
builder.AddSqlServerDbContext<YourDbContext>("sqldata");
Une fois la base de données enregistrée dans le projet consommateur, vous pouvez interagir avec le contexte de base de données YourDbContext en utilisant l’injection de dépendances. Cet exemple de code récupère les prévisions météorologiques d’une base de données et en sélectionne une au hasard à retourner :
app.MapGet("/weatherforecast", async (YourDbContext context) =>
{
var rng = new Random();
var forecasts = await context.Forecasts.ToListAsync();
var forecast = forecasts[rng.Next(forecasts.Count)];
return forecast;
});
Configurer le composant SQL Server
Comme précédemment, si vous utilisez le même nom de base de données dans l’hôte d’application et le projet consommateur, vous n’avez pas besoin de configurer la connexion entre la base de données SQL Server et les projets. Le composant SQL Server .NET Aspire prend également en charge d’autres modes de configuration du composant.
Utiliser des fournisseurs de configuration
Le composant SQL Server prend également en charge Microsoft.Extensions.Configuration. Par défaut, il recherche les paramètres avec la clé Aspire:SqlServer:SqlClient. Pour les projets utilisant appsettings.json, la configuration peut ressembler à l’exemple suivant :
{
"Aspire": {
"SqlServer": {
"SqlClient": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"HealthChecks": true,
"Tracing": false,
"Metrics": false
}
}
}
}
Utiliser des configurations inline
Lorsque vous ajoutez le composant SQL Server, vous pouvez transmettre un délégué inline configureSettings à la méthode AddSqlServerClient. Ce délégué vous permet de configurer les paramètres du composant de base de données directement avec du code :
builder.AddSqlServerClient("sqldata", static settings => settings.HealthChecks = false);
Vous pouvez transmettre l’une des options prises en charge :
ConnectionString: chaîne de connexion de la base de données SQL ServerHealthChecks: valeur booléenne qui indique si la vérification de l’intégrité de la base de données est activéeTracing: valeur booléenne qui indique si le suivi OpenTelemetry est activéMetrics: valeur booléenne qui indique si la mesure OpenTelemetry est activée
Se connecter à plusieurs bases de données
Le composant SQL Server prend en charge plusieurs connexions via des instances nommées. Par exemple, vous pouvez vous connecter à deux bases de données SQL Server différentes dans un même projet :
{
"Aspire": {
"SqlServer": {
"SqlClient": {
"INSTANCE_1": {
"ServiceUri": "YOUR_URI",
"HealthChecks": false
},
"INSTANCE_2": {
"ServiceUri": "YOUR_URI",
"HealthChecks": false
}
}
}
}
}
Cette configuration vous permet de vous connecter à deux bases de données distinctes d’un même projet :
builder.AddSqlServerClient("INSTANCE_1");
builder.AddSqlServerClient("INSTANCE_2");
Utiliser le composant MySQL
Pour installer le composant MySQL .NET Aspire, utilisez une commande semblable à celle-ci dans vos projets .NET Aspire devant accéder aux données :
dotnet add package Aspire.MySqlConnector --prerelease
Vous pouvez aussi utiliser le raccourci Ajouter > Composant Aspire .NET dans Visual Studio pour installer le composant à partir du gestionnaire de package NuGet.
Le code du fichier Program.cs du projet *.AppHost permettant d’accéder à la base de données est similaire à l’exemple PostgreSQL :
var mysqldb = builder.AddMySql("mysql")
.AddDatabase("mysqldb")
.WithPhpMyAdmin();
var myService = builder.AddProject<Projects.MyService>()
.WithReference(mysqldb);
Comme le composant PostgreSQL, le composant MySQL permet également de créer un conteneur pour les outils de gestion de bases de données. L’exemple précédent ajoute PhpMyAdmin à la solution.
Utiliser une base de données MySQL
Le modèle est le même pour les projets devant disposer d’un accès MySQL. Dans le fichier Program.cs, le code suivant enregistre la base de données :
builder.AddMySqlDataSource("mysqldb");
Une fois la base de données enregistrée dans le projet consommateur, vous pouvez interagir avec la source de données chaque fois que vous en avez besoin en utilisant l’injection de dépendances :
app.MapGet("/catalog", async (MySqlConnection db) =>
{
const string sql = """
SELECT Id, Name, Description, Price
FROM catalog
""";
// the db object is a connection to the MySQL database registered with AddMySqlDataSource
return await db.QueryAsync<CatalogItem>(sql);
});
Configurer le composant MySQL
Le composant MySQL prend en charge les trois mêmes options pour gérer la configuration.
Chaînes de connexion
Le fichier appsettings.json peut contenir la chaîne de connexion de la base de données MySQL :
{
"ConnectionStrings": {
"MySqConnection": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword"
}
}
Ensuite, dans votre projet, vous pouvez vous connecter à la base de données avec la chaîne de connexion en utilisant un code similaire au suivant :
builder.AddMySqlDataSource("MySqConnection");
Fournisseurs de configuration
La clé Aspire:MySqlConnector est utilisée pour configurer le composant MySQL.
{
"Aspire": {
"MySqlConnector": {
"ConnectionString": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword",
"HealthChecks": true,
"Tracing": false,
"Metrics": false
}
}
}
Configurations inline
builder.AddMySqlDataSource("mysqldb", static settings => settings.HealthChecks = false);
Alimenter votre base de données
La pile .NET Aspire utilise des conteneurs, ce qui permet de profiter d’environnements cohérents et de déploiements faciles. En revanche, les conteneurs sont sans état. Toutes les données ou schémas ajoutés à une base de données sont perdus lorsque le conteneur est détruit. .NET Aspire permet d’alimenter vos bases de données avec des données lorsqu’il crée leurs conteneurs.
Utiliser des volumes et des scripts
Pour alimenter votre base de données, le plus simple consiste à utiliser des volumes et des scripts SQL. Les volumes permettent de stocker des données pour plusieurs conteneurs simultanément, offrent de hautes performances, et sont faciles à sauvegarder ou migrer. Les scripts stockés dans ces volumes s’exécutent lorsqu’un conteneur est créé et remplissent la base de données avec des données. Le script peut être un fichier SQL contenant les données et le schéma à utiliser pour la base de données.
Par exemple, vous disposez de ce script SQL, stocké dans un fichier nommé postgres-backup.sql, dans le dossier Service.API/Seed :
CREATE TABLE catalog (
Id INT PRIMARY KEY,
Name VARCHAR(50),
Description VARCHAR(255),
Price DECIMAL(18, 2)
);
INSERT INTO catalog (Id, Name, Description, Price)
VALUES (1, 'Item 1', 'Description of item 1', 10.99),
(2, 'Item 2', 'Description of item 2', 20.99),
(3, 'Item 3', 'Description of item 3', 30.99);
Dans l’hôte d’application de la solution, vous pouvez lier le dossier Service.API/Seed au dossier /docker-entrypoint-initdb.d du conteneur. Il s’agit d’un dossier spécial du conteneur PostgreSQL qui exécute tous les scripts SQL qu’il trouve lors de la création du conteneur :
var catalogDB = builder.AddPostgres("postgres")
.WithPgAdmin()
.WithEnvironment("POSTGRES_DB", "backendDB")
.WithBindMount("../Service.API/Seed", "/docker-entrypoint-initdb.d")
.AddDatabase("backendDB");
Vous pouvez même fractionner les scripts SQL en scripts de création de schémas et d’alimentation de données. Si tous se trouvent dans le dossier Service.API/Seed, ils s’exécutent lorsque .NET Aspire crée la base de données.
Alimenter les données avec Entity Framework Core
Pour les composants prenant en charge Entity Framework Core, vous pouvez alimenter votre base de données à l’aide de la classe DbContext et des migrations Entity Framework Core. Cette méthode utilise un code C# pour alimenter la base de données. Toutefois, cette alimentation doit uniquement s’effectuer pendant le développement ou le test, et non lors de la production.
// Register DbContext class
builder.AddNpgsqlDbContext<CatalogContext>("sqldata");
var app = builder.Build();
app.MapDefaultEndpoints();
if (app.Environment.IsDevelopment())
{
// Retrieve an instance of the DbContext class and manually run migrations during development
using (var scope = app.Services.CreateScope())
{
var context = scope.ServiceProvider.GetRequiredService<CatalogContext>();
context.Database.EnsureCreated();
}
}
Le code ci-dessus vérifie l’état de l’environnement d’application. S’il est en cours de développement, le code récupère la classe CatalogContext et exécute la méthode EnsureCreated. Cette méthode crée la base de données et exécute toutes les migrations en attente.
Pour plus d’informations sur comment alimenter les différents composants de base de données, consultez la documentation .NET Aspire.