Menyisipkan data ke dalam basis data menggunakan .NET.NET Aspire

Artikel
12/12/2024

Dalam artikel ini, Anda mempelajari cara mengonfigurasi proyek .NET.NET Aspire untuk menyemai data dalam database selama pengaktifan aplikasi. .NET Aspire memungkinkan Anda untuk menyemai data menggunakan skrip database atau Entity Framework Core untuk platform umum seperti SQL Server, PostgreSQL dan MySQL.

Kapan harus menyemai data

Mengisi sebelumnya tabel database dengan baris data sehingga siap untuk diuji melalui aplikasi Anda. Anda mungkin ingin menyemai data untuk skenario berikut:

Mengembangkan dan menguji berbagai fitur aplikasi Anda secara manual terhadap sekumpulan data yang bermakna, seperti katalog produk atau daftar pelanggan.
Jalankan rangkaian pengujian untuk memverifikasi bahwa fitur berperilaku dengan cara tertentu dengan sekumpulan data tertentu.

Menyemai data secara manual melelahkan dan memakan waktu, jadi Anda harus mengotomatiskan proses jika memungkinkan. Gunakan volume untuk menjalankan skrip database untuk proyek .NET.NET Aspire selama startup. Anda juga dapat menyemai database Anda menggunakan alat seperti Entity Framework Core, yang menangani banyak kekhawatiran yang mendasar untuk Anda.

Memahami basis data terkontainer

Secara default, integrasi database .NET.NET Aspire mengandalkan database dalam kontainer, yang menciptakan tantangan berikut saat mencoba menyemai data:

.NET .NET Aspire menghancurkan dan membuat ulang kontainer setiap kali aplikasi dimulai ulang, yang berarti secara default Anda harus menyemai ulang database Anda setiap kali aplikasi dimulai ulang.
Bergantung pada teknologi database yang Anda pilih, instans kontainer baru mungkin atau mungkin tidak membuat database default, yang berarti Anda mungkin juga harus membuat database itu sendiri.
Bahkan jika database default ada, kemungkinan besar tidak akan memiliki nama atau skema yang diinginkan untuk aplikasi spesifik Anda.

.NET .NET Aspire memungkinkan Anda mengatasi tantangan ini menggunakan volume dan beberapa konfigurasi untuk menyemai data secara efektif.

Seed data menggunakan volume dan skrip SQL

Volume adalah cara yang disarankan untuk secara otomatis menyemai database dalam kontainer saat menggunakan skrip SQL. Volume dapat menyimpan data untuk beberapa kontainer sekaligus, menawarkan performa tinggi dan mudah dicadangkan atau dimigrasikan. Dengan .NET.NET Aspire, Anda mengonfigurasi volume untuk setiap kontainer sumber daya menggunakan metode ContainerResourceBuilderExtensions.WithBindMount, yang menerima tiga parameter:

Source: Jalur sumber pemasangan volume, yang merupakan lokasi fisik pada host Anda.
Target: Jalur target dalam kontainer data yang ingin Anda pertahankan.

Pertimbangkan kode konfigurasi volume berikut dari file dalam contoh proyek AppHost :

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

Dalam contoh ini, parameter metode .WithBindMount mengonfigurasi yang berikut:

../DatabaseContainers.ApiService/data/postgres menetapkan jalur ke skrip SQL di proyek lokal yang Anda ingin jalankan dalam kontainer untuk menginisialisasi data.
/docker-entrypoint-initdb.d mengatur jalur ke titik masuk dalam kontainer sehingga skrip Anda akan dijalankan selama startup kontainer.

Skrip SQL yang direferensikan yang terletak di ../DatabaseContainers.ApiService/data/postgres membuat dan menyemai tabel 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;

Skrip berjalan selama startup setiap kali instans kontainer baru dibuat.

Contoh pengisian database

Contoh berikut menunjukkan cara menyemai data menggunakan skrip dan konfigurasi SQL yang diterapkan menggunakan metode .WithBindMount untuk teknologi database yang berbeda:

Nota

Kunjungi Aplikasi Sampel Kontainer Database untuk melihat proyek lengkap dan struktur file untuk setiap opsi database.

Kode konfigurasi di .AppHostProgram.cs memasang file dan folder database yang diperlukan dan mengonfigurasi titik masuk sehingga file dan folder tersebut berjalan selama startup.

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

Skrip entrypoint.sh berada di folder proyek ./sqlserverconfig yang dipasang dan berjalan saat kontainer dimulai. Skrip meluncurkan SQL Server dan memeriksa apakah skrip berjalan.

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

Skrip SQL init.sql yang berada di folder proyek ../DatabaseContainers.ApiService/data/sqlserver yang dipasang membuat database dan tabel.

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

Kode konfigurasi di proyek .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);

Skrip SQL terkait yang disertakan dalam aplikasi:

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

Kode konfigurasi di proyek .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);

Skrip SQL terkait yang disertakan dalam aplikasi:

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

Inisialisasi data menggunakan Entity Framework Core

Anda juga dapat menyemai data dalam proyek .NET Aspire menggunakan Entity Framework Core dengan menjalankan migrasi secara eksplisit selama startup. Entity Framework Core menangani koneksi database dan pembuatan skema yang mendasarinya untuk Anda, yang menghilangkan kebutuhan untuk menggunakan volume atau menjalankan skrip SQL selama startup kontainer.

Penting

Jenis konfigurasi ini hanya boleh dilakukan selama pengembangan, jadi pastikan untuk menambahkan kondisional yang memeriksa konteks lingkungan Anda saat ini.

Tambahkan kode berikut ke file proyek Layanan API Anda.

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

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

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

Langkah berikutnya

Penyemaian database berguna dalam berbagai skenario pengembangan aplikasi. Cobalah menggabungkan teknik ini dengan implementasi sumber daya yang ditunjukkan dalam tutorial berikut:

Tutorial : Menyambungkan aplikasi ASP.NET Core ke SQL Server menggunakan .NET Aspire dan Entity Framework Core
Tutorial : Menyambungkan aplikasi ASP.NET Core ke integrasi penyimpanan .NET Aspire
gambaran umum orkestrasi

Bagikan melalui