Počáteční data v databázi pomocí .NET.NET Aspire

V tomto článku se dozvíte, jak nakonfigurovat .NET.NET Aspire projekty pro zasazení dat do databáze během spuštění aplikace. .NET Aspire vám umožňuje připravovat data pomocí databázových skriptů nebo Entity Framework Core pro běžné platformy, jako jsou SQL Server, PostgreSQL a MySQL.

Kdy zasít data

Předvyplňování dat předem naplní databázové tabulky řádky dat, aby byly připravené k testování prostřednictvím vaší aplikace. Můžete chtít počáteční data pro následující scénáře:

• Ruční vývoj a testování různých funkcí aplikace na základě smysluplné sady dat, jako je katalog produktů nebo seznam zákazníků.
• Spuštěním testovacích sad ověřte, že se funkce chovají určitým způsobem s danou sadou dat.

Ruční seedování dat je zdlouhavé a časově náročné, proto byste měli proces automatizovat, pokud je to možné. Objemy slouží ke spouštění databázových skriptů pro .NET.NET Aspire projekty při startu. Databázi můžete také nasadit pomocí nástrojů, jako je Entity Framework Core, které za vás řeší mnoho základních úloh.

Principy kontejnerizovaných databází

Integrace databází .NET.NET Aspire ve výchozím nastavení spoléhají na kontejnerizované databáze, které při pokusu o počáteční data vytvářejí následující výzvy:

• .NET .NET Aspire zničí a znovu vytvoří kontejnery pokaždé, když se aplikace restartuje, což znamená, že při každém restartování aplikace musíte databázi znovu restartovat.
• V závislosti na vybrané databázové technologii může nebo nemusí nová instance kontejneru vytvořit výchozí databázi, což znamená, že budete muset také vytvořit samotnou databázi.
• I když existuje výchozí databáze, pravděpodobně nebude mít požadovaný název nebo schéma pro vaši konkrétní aplikaci.

.NET .NET Aspire vám umožní tyto problémy vyřešit pomocí svazků a několika konfigurací efektivních počátečních dat.

Osazení dat pomocí svazků a skriptů SQL

Svazky jsou doporučovaným způsobem, jak při použití skriptů SQL automaticky nasazovat databáze v kontejnerech. Svazky můžou ukládat data pro více kontejnerů najednou, nabízejí vysoký výkon a snadno se zálohují nebo migrují. Pomocí .NET.NET Aspirenakonfigurujete svazek pro každý kontejner prostředků metodou ContainerResourceBuilderExtensions.WithBindMount, která přijímá tři parametry:

• Zdroj: Cesta pro připojení svazku, která označuje fyzické umístění na vašem hostitelském systému.
• Cílové: Cílová cesta v kontejneru dat, která chcete zachovat.

Vezměte v úvahu následující konfigurační kód svazku ze souboru Program.cs v ukázkovém projektu AppHost:

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

V tomto příkladu nakonfigurují parametry metody .WithBindMount následující:

• ../DatabaseContainers.ApiService/data/postgres nastaví cestu ke skriptu SQL v místním projektu, který chcete spustit v kontejneru na počáteční data.
• /docker-entrypoint-initdb.d nastaví cestu k vstupnímu bodu v kontejneru, aby se skript spustil během spouštění kontejneru.

Odkazovaný skript SQL umístěný v ../DatabaseContainers.ApiService/data/postgres vytvoří a naplní tabulku 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;

Skript se spustí při každém spuštění nové instance kontejneru.

Příklady zasetí databáze

Následující příklady ukazují, jak zavést počáteční data pomocí SQL skriptů a konfigurací aplikovaných metodou .WithBindMount pro různé databázové technologie.

Poznámka

Pokud chcete zobrazit úplný projekt a strukturu souborů pro každou možnost databáze, navštivte ukázkovou aplikaci kontejneru databáze.

SQL Server

Konfigurační kód v . AppHostProgram.cs soubor připojí požadované soubory a složky databáze a nakonfiguruje vstupní bod tak, aby běžely během spouštění.

// 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);

Skript entrypoint.sh se nachází ve složce připojeného projektu ./sqlserverconfig a spustí se při spuštění kontejneru. Skript spustí SQL Server a zkontroluje, že je spuštěný.

#!/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

Skript SQL init.sql, který se nachází v připojené složce projektu ../DatabaseContainers.ApiService/data/sqlserver, vytvoří databázi a tabulky.

-- 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

Konfigurační kód v projektu .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);

Odpovídající skript SQL zahrnutý v aplikaci:

-- 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

Kód konfigurace v .AppHost projektu:

// 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);

Odpovídající skript SQL zahrnutý v aplikaci:

-- 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)

Počáteční data pomocí Entity Framework Core

V .NET Aspire projektech můžete také naplnit data pomocí Entity Framework Core tím, že při spuštění explicitně provedete migrace. Entity Framework Core zpracovává podkladová připojení k databázi a vytváření schématu za vás, což eliminuje nutnost používat svazky nebo spouštět skripty SQL během spouštění kontejneru.

Důležitý

Tyto typy konfigurací by se měly provádět jenom během vývoje, proto nezapomeňte přidat podmínku, která kontroluje aktuální kontext prostředí.

Do souboru projektu služby API přidejte následující kód.

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();
    }
}

Další kroky

Počáteční nasazení databáze je užitečné v různých scénářích vývoje aplikací. Zkuste tyto techniky kombinovat s implementacemi prostředků, které jsou ukázané v následujících kurzech:

• Kurz : Připojení aplikace ASP.NET Core k SQL Server pomocí .NET Aspire a Entity Framework Core
• Kurz : Připojení aplikace ASP.NET Core k úložným integracím .NET Aspire
• .NET .NET Aspire Přehled orchestrace