Données initiales dans une base de données à l’aide de .NET.NET Aspire

Dans cet article, vous allez apprendre à configurer les projets .NET.NET Aspire pour amorcer les données dans une base de données lors du démarrage de l'application. .NET Aspire vous permet d'amorcer des données à l'aide de scripts de base de données ou de Entity Framework Core pour des plateformes courantes telles que SQL Server, PostgreSQL et MySQL.

Quand faut-il amorcer les données

L’amorçage des données préremplifie les tables de base de données avec des lignes de données afin qu’elles soient prêtes à être testées via votre application. Vous pourriez vouloir préparer des données pour les scénarios suivants :

• Développez et testez manuellement différentes fonctionnalités de votre application par rapport à un ensemble significatif de données, comme un catalogue de produits ou une liste de clients.
• Exécutez des suites de test pour vérifier que les fonctionnalités se comportent de manière spécifique avec un jeu de données donné.

L’amorçage manuel des données est fastidieux et chronophage. Vous devez donc automatiser le processus lorsque cela est possible. Utilisez des volumes pour exécuter des scripts de base de données pour les projets .NET.NET Aspire au démarrage. Vous pouvez également peupler votre base de données à l’aide d’outils tels que Entity Framework Core, qui prennent en charge de nombreuses questions sous-jacentes pour vous.

Comprendre les bases de données conteneurisées

Par défaut, .NET.NET Aspire intégrations de bases de données reposent sur des bases de données conteneurisées, ce qui crée les défis suivants lors de la tentative d’amorçage des données :

• .NET .NET Aspire détruit et recrée des conteneurs chaque fois que l’application redémarre, ce qui signifie par défaut que vous devez recréer votre base de données chaque fois que l’application redémarre.
• Selon la technologie de votre base de données sélectionnée, la nouvelle instance de conteneur peut ou non créer une base de données par défaut, ce qui signifie que vous devrez peut-être également créer la base de données elle-même.
• Même si une base de données par défaut existe, il n’aura probablement pas le nom ou le schéma souhaités pour votre application spécifique.

.NET .NET Aspire vous permet de résoudre ces défis en utilisant des volumes et quelques configurations pour amorcer les données efficacement.

Données initiales à l’aide de volumes et de scripts SQL

Les volumes sont la méthode recommandée pour amorçage automatique des bases de données conteneurisées lors de l’utilisation de scripts SQL. Les volumes peuvent stocker des données pour plusieurs conteneurs à la fois, offrir des performances élevées et être faciles à sauvegarder ou migrer. Avec .NET.NET Aspire, vous configurez un volume pour chaque conteneur de ressources à l’aide de la méthode ContainerResourceBuilderExtensions.WithBindMount, qui accepte trois paramètres :

• source: le chemin source du montage de volume, qui est l’emplacement physique sur votre machine hôte.
• cible: chemin cible dans le conteneur des données que vous souhaitez conserver.

Considérez le code de configuration de volume suivant à partir d’un fichier dans le projet AppHost de l'exemple :

var todosDbName = "Todos";
var todosDb = builder.AddPostgres("postgres")
    .WithEnvironment("POSTGRES_DB", todosDbName)
    .WithBindMount(
        "../DatabaseContainers.ApiService/data/postgres",
        "/docker-entrypoint-initdb.d")
    .AddDatabase(todosDbName);

Dans cet exemple, les paramètres de méthode .WithBindMount configurent les éléments suivants :

• ../DatabaseContainers.ApiService/data/postgres définit un chemin d’accès au script SQL dans votre projet local que vous souhaitez exécuter dans le conteneur pour amorçage des données.
• /docker-entrypoint-initdb.d définit le chemin d’accès à un point d’entrée dans le conteneur afin que votre script soit exécuté au démarrage du conteneur.

Le script SQL référencé situé à ../DatabaseContainers.ApiService/data/postgres crée et génère une table Todos :

-- Postgres init script

-- Create the Todos table
CREATE TABLE IF NOT EXISTS Todos
(
    Id SERIAL PRIMARY KEY,
    Title text UNIQUE NOT NULL,
    IsComplete boolean NOT NULL DEFAULT false
);

-- Insert some sample data into the Todos table
INSERT INTO Todos (Title, IsComplete)
VALUES
    ('Give the dog a bath', false),
    ('Wash the dishes', false),
    ('Do the groceries', false)
ON CONFLICT DO NOTHING;

Le script s’exécute au démarrage chaque fois qu’une nouvelle instance de conteneur est créée.

Exemples d’amorçage de base de données

Les exemples suivants montrent comment amorcer les données à l’aide de scripts et de configurations SQL appliqués à l’aide de la méthode .WithBindMount pour différentes technologies de base de données.

Note

Visitez l'application de démonstration de conteneur de base de données pour afficher l'organisation complète du projet et des fichiers pour chaque option de base de données.

SQL Server

Code de configuration dans le fichier .AppHostProgram.cs monte les fichiers et dossiers de base de données requis et configure un point d’entrée pour qu’ils soient exécutés au démarrage.

// SQL Server container is configured with an auto-generated password by default
// but doesn't support any auto-creation of databases or running scripts on startup so we have to do it manually.
var sqlserver = builder.AddSqlServer("sqlserver")
    // Mount the init scripts directory into the container.
    .WithBindMount("./sqlserverconfig", "/usr/config")
    // Mount the SQL scripts directory into the container so that the init scripts run.
    .WithBindMount("../DatabaseContainers.ApiService/data/sqlserver", "/docker-entrypoint-initdb.d")
    // Run the custom entrypoint script on startup.
    .WithEntrypoint("/usr/config/entrypoint.sh")
    // Configure the container to store data in a volume so that it persists across instances.
    .WithDataVolume()
    // Keep the container running between app host sessions.
    .WithLifetime(ContainerLifetime.Persistent);

Le script entrypoint.sh réside dans le dossier de projet ./sqlserverconfig monté et s’exécute au démarrage du conteneur. Le script lance SQL Server et vérifie qu’il est en cours d’exécution.

#!/bin/bash

# Adapted from: https://github.com/microsoft/mssql-docker/blob/80e2a51d0eb1693f2de014fb26d4a414f5a5add5/linux/preview/examples/mssql-customize/entrypoint.sh

# Start the script to create the DB and user
/usr/config/configure-db.sh &

# Start SQL Server
/opt/mssql/bin/sqlservr

Le script SQL init.sql qui se trouve dans le dossier de projet ../DatabaseContainers.ApiService/data/sqlserver monté crée la base de données et les tables.

-- SQL Server init script

-- Create the AddressBook database
IF NOT EXISTS (SELECT * FROM sys.databases WHERE name = N'AddressBook')
BEGIN
  CREATE DATABASE AddressBook;
END;
GO

USE AddressBook;
GO

-- Create the Contacts table
IF OBJECT_ID(N'Contacts', N'U') IS NULL
BEGIN
    CREATE TABLE Contacts
    (
        Id        INT PRIMARY KEY IDENTITY(1,1) ,
        FirstName VARCHAR(255) NOT NULL,
        LastName  VARCHAR(255) NOT NULL,
        Email     VARCHAR(255) NULL,
        Phone     VARCHAR(255) NULL
    );
END;
GO

-- Ensure that either the Email or Phone column is populated
IF OBJECT_ID(N'chk_Contacts_Email_Phone', N'C') IS NULL
BEGIN
    ALTER TABLE Contacts
    ADD CONSTRAINT chk_Contacts_Email_Phone CHECK
    (
        Email IS NOT NULL OR Phone IS NOT NULL
    );
END;
GO

-- Insert some sample data into the Contacts table
IF (SELECT COUNT(*) FROM Contacts) = 0
BEGIN
    INSERT INTO Contacts (FirstName, LastName, Email, Phone)
    VALUES
        ('John', 'Doe', 'john.doe@example.com', '555-123-4567'),
        ('Jane', 'Doe', 'jane.doe@example.com', '555-234-5678');
END;
GO

PostgreSQL

Code de configuration dans le projet .AppHost :

// PostgreSQL container is configured with an auto-generated password by default
// and supports setting the default database name via an environment variable & running *.sql/*.sh scripts in a bind mount.
var todosDbName = "Todos";

var postgres = builder.AddPostgres("postgres")
    // Set the name of the default database to auto-create on container startup.
    .WithEnvironment("POSTGRES_DB", todosDbName)
    // Mount the SQL scripts directory into the container so that the init scripts run.
    .WithBindMount("../DatabaseContainers.ApiService/data/postgres", "/docker-entrypoint-initdb.d")
    // Configure the container to store data in a volume so that it persists across instances.
    .WithDataVolume()
    // Keep the container running between app host sessions.
    .WithLifetime(ContainerLifetime.Persistent);

Script SQL correspondant inclus dans l’application :

-- Postgres init script

-- Create the Todos table
CREATE TABLE IF NOT EXISTS Todos
(
    Id SERIAL PRIMARY KEY,
    Title text UNIQUE NOT NULL,
    IsComplete boolean NOT NULL DEFAULT false
);

-- Insert some sample data into the Todos table
INSERT INTO Todos (Title, IsComplete)
VALUES
    ('Give the dog a bath', false),
    ('Wash the dishes', false),
    ('Do the groceries', false)
ON CONFLICT DO NOTHING;

MySQL

Code de configuration dans le projet AppHost . :

// MySql container is configured with an auto-generated password by default
// and supports setting the default database name via an environment variable & running *.sql/*.sh scripts in a bind mount.
var catalogDbName = "catalog"; // MySql database & table names are case-sensitive on non-Windows.

var mysql = builder.AddMySql("mysql")
    // Set the name of the database to auto-create on container startup.
    .WithEnvironment("MYSQL_DATABASE", catalogDbName)
    // Mount the SQL scripts directory into the container so that the init scripts run.
    .WithBindMount("../DatabaseContainers.ApiService/data/mysql", "/docker-entrypoint-initdb.d")
    // Configure the container to store data in a volume so that it persists across instances.
    .WithDataVolume()
    // Keep the container running between app host sessions.
    .WithLifetime(ContainerLifetime.Persistent);

Script SQL correspondant inclus dans l’application :

-- MySql init script

-- NOTE: MySql database and table names are case-sensitive on non-Windows platforms!
--       Column names are always case-insensitive.

-- Create the Catalog table
CREATE TABLE IF NOT EXISTS `catalog`
(
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `name` varchar(255) NOT NULL,
    `description` varchar(255) NOT NULL,
    `price` DECIMAL(18,2) NOT NULL,
    PRIMARY KEY (`id`)
);

-- Insert some sample data into the Catalog table only if the table is empty
INSERT INTO catalog (name, description, price)
SELECT *
FROM (
        SELECT '.NET Bot Black Hoodie', 'This hoodie will keep you warm while looking cool and representing .NET!', 19.5 UNION ALL
        SELECT '.NET Black & White Mug', 'The perfect place to keep your favorite beverage while you code.', 8.5 UNION ALL
        SELECT 'Prism White T-Shirt', "It's a t-shirt, it's white, and it can be yours.", 12
    ) data
-- This clause ensures the rows are only inserted if the table is empty
WHERE NOT EXISTS (SELECT NULL FROM catalog)

Données initiales à l’aide de Entity Framework Core

Vous pouvez également amorcer des données dans des projets .NET Aspire en utilisant Entity Framework Core en exécutant explicitement des migrations au démarrage. Entity Framework Core gère les connexions de base de données sous-jacentes et la création de schémas pour vous, ce qui élimine la nécessité d’utiliser des volumes ou d’exécuter des scripts SQL au démarrage du conteneur.

Important

Ces types de configurations doivent être effectués uniquement pendant le développement. Veillez donc à ajouter une condition qui vérifie votre contexte d’environnement actuel.

Ajoutez le code suivant au fichier Program.cs de votre projet de service d’API .

SQL Server

// Register DbContext class
builder.AddSqlServerDbContext<TicketContext>("sqldata");

var app = builder.Build();

app.MapDefaultEndpoints();

if (app.Environment.IsDevelopment())
{
    // Retrieve an instance of the DbContext class and manually run migrations during startup
    using (var scope = app.Services.CreateScope())
    {
        var context = scope.ServiceProvider.GetRequiredService<TicketContext>();
        context.Database.Migrate();
    }
}

PostgreSQL

// Register DbContext class
builder.AddNpgsqlDbContext<TicketContext>("sqldata");

var app = builder.Build();

app.MapDefaultEndpoints();

if (app.Environment.IsDevelopment())
{
    // Retrieve an instance of the DbContext class and manually run migrations during startup
    using (var scope = app.Services.CreateScope())
    {
        var context = scope.ServiceProvider.GetRequiredService<TicketContext>();
        context.Database.Migrate();
    }
}

MySQL

// Register DbContext class
builder.AddMySqlDataSource<TicketContext>("sqldata");

var app = builder.Build();

app.MapDefaultEndpoints();

if (app.Environment.IsDevelopment())
{
    // Retrieve an instance of the DbContext class and manually run migrations during startup
    using (var scope = app.Services.CreateScope())
    {
        var context = scope.ServiceProvider.GetRequiredService<TicketContext>();
        context.Database.Migrate();
    }
}

Étapes suivantes

L’amorçage de base de données est utile dans divers scénarios de développement d’applications. Essayez de combiner ces techniques avec les implémentations de ressources illustrées dans les didacticiels suivants :

• Tutoriel : Connecter une application ASP.NET Core à SQL Server à l’aide de .NET Aspire et de Entity Framework Core
• Tutoriel : Connecter une application ASP.NET Core aux intégrations de stockage .NET Aspire
• Vue d’ensemble de l’orchestration .NET.NET Aspire