Veritabanına ön verileri .NET.NET Aspire kullanarak yükleme.

Makale
12/15/2024

Bu makalede, uygulama başlarken bir veritabanına veri eklemek için .NET.NET Aspire projelerini nasıl yapılandıracağınızı öğreneceksiniz. .NET Aspire, SQL Server, PostgreSQL ve MySQLgibi yaygın platformlar için veritabanı betiklerini veya Entity Framework Core kullanarak veri tohumu oluşturmanızı sağlar.

Veri ne zaman dağıtılır?

Verilerin tohumlanması, veritabanı tablolarını veri satırlarıyla önceden doldurur, böylece bunlar uygulamanız aracılığıyla test için hazır olur. Aşağıdaki senaryolar için verileri tohumlamak isteyebilirsiniz:

Uygulamanızın ürün kataloğu veya müşteri listesi gibi anlamlı bir veri kümesine göre farklı özelliklerini el ile geliştirin ve test edin.
Özelliklerin belirli bir veri kümesiyle belirli bir şekilde davrandığını doğrulamak için test paketlerini çalıştırın.

Verileri el ile tohumlama zahmetli ve zaman alıcıdır, bu nedenle mümkün olduğunda işlemi otomatikleştirmeniz gerekir. Başlatma sırasında .NET.NET Aspire projeleri için veritabanı betiklerini çalıştırmak için birimleri kullanın. Ayrıca, Entity Framework Coregibi araçları kullanarak veritabanınızın tohumlarını da oluşturabilirsiniz. Bu araçlar sizin için birçok temel sorunu ele alır.

Kapsayıcılı veritabanlarını anlama

Varsayılan olarak, .NET.NET Aspire veritabanı tümleştirmeleri kapsayıcılı veritabanlarını kullanır ve bu da verileri tohumlamaya çalışırken aşağıdaki zorlukları oluşturur:

.NET .NET Aspire, uygulama her yeniden başlatıldığında kapsayıcıları yok eder ve yeniden oluşturur, yani varsayılan olarak uygulama her yeniden başlatıldığında veritabanınızı yeniden görmeniz gerekir.
Seçtiğiniz veritabanı teknolojisine bağlı olarak, yeni kapsayıcı örneği varsayılan bir veritabanı oluşturabilir veya oluşturmayabilir. Bu, veritabanının kendisini de oluşturmanız gerekebileceği anlamına gelir.
Varsayılan bir veritabanı olsa bile, büyük olasılıkla belirli bir uygulama için istenen ada veya şemaya sahip olmayacaktır.

.NET .NET Aspire, verileri etkili bir şekilde yüklemek için hacimler ve birkaç yapılandırma kullanarak bu zorlukları çözmenizi sağlar.

Birimleri ve SQL betiklerini kullanarak verileri tohumlama

SQL betiklerini kullanırken kapsayıcı veritabanlarını otomatik olarak başlatmanın önerilen yolu, birimlerdir. Birimler aynı anda birden çok kapsayıcının verilerini depolayabilir, yüksek performans sunabilir ve kolayca yedeklenebilir veya geçirilebilir. .NET .NET Aspireile, üç parametre kabul eden ContainerResourceBuilderExtensions.WithBindMount yöntemini kullanarak her kaynak kapsayıcısı için bir birim yapılandırırsınız:

Kaynak: Konağınızdaki fiziksel konum olan birim bağlama noktasının kaynak yolu.
Hedef: Kalıcı hale getirmek istediğiniz verilerin kapsayıcısında hedef yol.

AppHost projesinin örnek bir dosyasından aşağıdaki birim yapılandırma kodunu göz önünde bulundurun:

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

Bu örnekte, .WithBindMount yöntemi parametreleri aşağıdakileri yapılandırıyor:

../DatabaseContainers.ApiService/data/postgres, verileri yüklemek amacıyla kapsayıcıda çalıştırmak istediğiniz SQL betiğinin yerel projenizdeki yolunu ayarlar.
/docker-entrypoint-initdb.d, komut dosyanızın kapsayıcı başlatıldığında çalıştırılması için kapsayıcıda bir giriş noktasına yol ayarlar.

../DatabaseContainers.ApiService/data/postgres konumunda bulunan atıfta bulunulan SQL betiği, bir Todos tablosu oluşturur ve verileri ekler.

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

Betik, her yeni kapsayıcı örneği oluşturulduğunda başlatma sırasında çalışır.

Veritabanı tohumlama örnekleri

Aşağıdaki örneklerde, farklı veritabanı teknolojileri için .WithBindMount yöntemi kullanılarak uygulanan SQL betikleri ve yapılandırmaları kullanılarak verilerin nasıl dağıtıldığı gösterilmektedir:

Not

Her veritabanı seçeneğinin proje ve dosya yapısının tamamını görüntülemek için Veritabanı Kapsayıcı Örneği Uygulaması ziyaret edin.

dosyasındaki .AppHostProgram.cs yapılandırma kodu, gerekli veritabanı dosyalarını ve klasörlerini bağlar ve bu dosyaların başlangıç sırasında çalışması için bir giriş noktası yapılandırır.

// 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 betiği, bağlı ./sqlserverconfig proje klasöründe bulunur ve kapsayıcı başlatıldığında çalışır. Betik SQL Server'ı başlatır ve çalıştığını kontrol eder.

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

Bağlı ../DatabaseContainers.ApiService/data/sqlserver proje klasöründe bulunan init.sql SQL betiği, veritabanını ve tabloları oluşturur.

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

.AppHost projesindeki yapılandırma kodu:

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

Uygulamaya dahil edilen ilgili SQL betiği:

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

.AppHost projesindeki yapılandırma kodu:

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

Uygulamaya dahil edilen ilgili SQL betiği:

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

Entity Framework Core kullanarak veri ekimi

Başlangıç sırasında geçişleri açıkça çalıştırarak Entity Framework Core kullanarak .NET Aspire projelerindeki verileri de tohumlayabilirsiniz. Entity Framework Core, kapsayıcı başlatma sırasında veri hacimlerini kullanma veya SQL betiklerini çalıştırma gereksinimini ortadan kaldırarak sizin için temel veritabanı bağlantılarını ve şema oluşturmayı yönetir.

Önemli

Bu tür yapılandırmalar yalnızca geliştirme sırasında yapılmalıdır, bu nedenle geçerli ortam bağlamınızı denetleen bir koşullu eklemeyi unutmayın.

API Service projenizin Program.cs dosyasına aşağıdaki kodu ekleyin.

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

Sonraki adımlar

Veritabanı tohumlama, çeşitli uygulama geliştirme senaryolarında kullanışlıdır. Bu teknikleri aşağıdaki öğreticilerde gösterildiği gibi kaynak uygulamalarıyla birleştirmeyi deneyin:

Öğreticisi: .NET Aspire ve Entity Framework Core kullanarak bir ASP.NET Core uygulamasını SQL Server bağlama
Öğretici: ASP.NET Core uygulamasını .NET Aspire depolama entegrasyonları ile bağlama
.NET .NET Aspire orkestrasyona genel bakış

Aracılığıyla paylaş