Frödatat i en databas med .NET.NET Aspire

I den här artikeln får du lära dig hur du konfigurerar .NET.NET Aspire projekt för att skapa data i en databas när appen startas. .NET Aspire gör att du kan hämta data med hjälp av databasskript eller Entity Framework Core för vanliga plattformar som SQL Server, PostgreSQL och MySQL.

När data ska initieras

Genom att fylla i data förfylls databastabellerna med rader så att de är redo för testning genom din app. Du kanske vill sätta in data för följande scenarier:

• Utveckla och testa olika funktioner i din app manuellt mot en meningsfull uppsättning data, till exempel en produktkatalog eller en lista över kunder.
• Kör testpaket för att kontrollera att funktionerna fungerar på ett visst sätt med en viss uppsättning data.

Att manuellt såda data är omständligt och tidskrävande, så du bör automatisera processen när det är möjligt. Använd volymer för att köra databasskript för .NET.NET Aspire projekt under starten. Du kan också fylla din databas med data med hjälp av verktyg som Entity Framework Core, som hanterar många underliggande frågor åt dig.

Förstå containerbaserade databaser

Som standard förlitar sig .NET.NET Aspire databasintegreringar på containerbaserade databaser, vilket skapar följande utmaningar när du försöker hämta data:

• .NET .NET Aspire förstör och återskapar containrar varje gång appen startas om, vilket innebär att du som standardinställning måste återställa databasen varje gång appen startas om.
• Beroende på den valda databastekniken kan den nya containerinstansen skapa eller inte skapa en standarddatabas, vilket betyder att du kanske också måste skapa själva databasen.
• Även om det finns en standarddatabas har den förmodligen inte önskat namn eller schema för din specifika app.

.NET .NET Aspire möjliggör för dig att lösa dessa utmaningar med hjälp av volymer och några konfigurationer för att effektivt initiera data.

Initiera data med hjälp av volymer och SQL-skript

Volymer är det rekommenderade sättet att automatiskt seeda containerbaserade databaser när du använder SQL-skript. Volymer kan lagra data för flera containrar åt gången, erbjuda höga prestanda och är enkla att säkerhetskopiera eller migrera. Med .NET.NET Aspirekonfigurerar du en volym för varje resurscontainer med hjälp av metoden ContainerResourceBuilderExtensions.WithBindMount, som accepterar tre parametrar:

• Source: Källsökvägen för volymmonteringen, som är den fysiska platsen på din värd.
• Target: Målsökvägen i containern för datan du vill spara.

Överväg följande volymkonfigurationskod från en Program.cs-fil i ett exempel AppHost- projekt:

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

I det här exemplet konfigurerar .WithBindMount-metodparametrarna följande:

• ../DatabaseContainers.ApiService/data/postgres anger en sökväg till SQL-skriptet i ditt lokala projekt som du vill köra i containern för att hämta data.
• /docker-entrypoint-initdb.d anger sökvägen till en startpunkt i containern så att skriptet körs under containerstarten.

Det refererade SQL-skriptet som finns på ../DatabaseContainers.ApiService/data/postgres skapar och fyller en Todos tabell:

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

Skriptet körs under start varje gång en ny containerinstans skapas.

Exempel på databassådd

Följande exempel visar hur du seedar data med hjälp av SQL-skript och konfigurationer som tillämpas med metoden .WithBindMount för olika databastekniker.

Not

Besök Database Container Sample App för att visa hela projektet och filstrukturen för varje databasalternativ.

SQL Server

Konfigurationskoden i . AppHostProgram.cs-filen monterar de databasfiler och mappar som krävs och konfigurerar en startpunkt så att de körs under starten.

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

entrypoint.sh-skriptet finns i den monterade ./sqlserverconfig projektmappen och körs när containern startar. Skriptet startar SQL Server och kontrollerar att det körs.

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

Det init.sql SQL-skript som finns i den monterade ../DatabaseContainers.ApiService/data/sqlserver projektmappen skapar databasen och tabellerna.

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

Konfigurationskod i . AppHost projekt:

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

Motsvarande SQL-skript som ingår i appen:

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

Konfigurationskod i . AppHost projekt:

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

Motsvarande SQL-skript som ingår i appen:

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

Initieringsdata med hjälp av Entity Framework Core

Du kan också så data i .NET Aspire projekt med hjälp av Entity Framework Core genom att uttryckligen köra migreringar vid uppstart. Entity Framework Core hanterar underliggande databasanslutningar och schemaskapande åt dig, vilket eliminerar behovet av att använda volymer eller köra SQL-skript när containern startas.

Viktig

De här typerna av konfigurationer bör endast utföras under utvecklingen, så se till att lägga till ett villkor som kontrollerar din aktuella miljökontext.

Lägg till följande kod i Program.cs-filen för ditt API Service- projekt.

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

Nästa steg

Databassådd är användbart i en mängd olika scenarier för apputveckling. Prova att kombinera dessa tekniker med de resursimplementeringar som demonstreras i följande handledningar.

• Självstudie: Ansluta en ASP.NET Core app till SQL Server med hjälp av .NET Aspire och Entity Framework Core
• Självstudie: Anslutning av en ASP.NET Core applikation till .NET Aspire lagringsintegrationer
• översikt över orkestrering .NET.NET Aspire