Nabs.Launchpad.Core.Migrations 10.0.214

Nabs Launchpad Core Migrations Library

A .NET 10 library providing interfaces and abstractions for database migration and seeding operations in the Nabs Launchpad framework.

Overview

The Nabs.Launchpad.Core.Migrations library defines core interfaces and implementations for managing database initialization tasks including:

• Database schema migrations using Entity Framework Core
• Test data generation and seeding
• Development environment data setup

This library provides a streamlined API using C# 13 extension types to configure SQL Server database migrations with minimal boilerplate.

Key Features

• Migration Processing: Built-in IMigrationsProcessor implementation that automatically applies pending EF Core migrations
• Seed Data Processing: ISeedDataProcessor interface for populating databases with initial or test data
• Extension Types: Modern C# 13 extension type syntax for fluent configuration
• Pooled DbContext Factory: Uses AddPooledDbContextFactory for efficient database context management
• Async Support: All operations support cancellation tokens and async patterns
• Framework Integration: Designed to work seamlessly with dependency injection and hosted services

Core Interfaces and Components

ISeedDataProcessor

Defines a contract for processing seed data operations:

public interface ISeedDataProcessor
{
    Task ProcessAsync(CancellationToken stoppingToken);
}

Use this interface to implement classes that populate your database with:

• Initial application data
• Test data for development environments
• Sample data for demonstrations

IMigrationsProcessor

Defines a contract for handling database migrations:

public interface IMigrationsProcessor
{
    Task MigrateAsync(CancellationToken stoppingToken);
}

The library provides a built-in implementation (MigrationsProcessor<TDbContext>) that:

• Checks for pending migrations
• Applies migrations only when needed
• Uses IDbContextFactory<TDbContext> for efficient context management

Extension Methods

AddSqlMigrations

The AddSqlMigrations extension method configures SQL Server database migrations with a pooled DbContext factory:

builder.AddSqlMigrations<MyDbContext, MySeedDataProcessor>("MyDatabase");

This method:

• Registers a pooled IDbContextFactory<TDbContext> with SQL Server configuration
• Configures the migrations assembly from the seed data processor's assembly
• Registers IMigrationsProcessor as a singleton
• Registers ISeedDataProcessor as a singleton with automatic factory injection

Dependencies

• .NET 10: Target framework
• Microsoft.EntityFrameworkCore: Core EF abstractions
• Microsoft.EntityFrameworkCore.SqlServer: SQL Server provider
• Bogus: Fake data generation library for creating realistic test data
• Azure.Data.AppConfiguration: Azure App Configuration client
• Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration: Aspire integration for Azure App Configuration

Usage Examples

Implementing ISeedDataProcessor

public class UserSeedDataProcessor : ISeedDataProcessor
{
    private readonly IDbContextFactory<ApplicationDbContext> _dbContextFactory;
    private readonly Faker<User> _userFaker;

    public UserSeedDataProcessor(IDbContextFactory<ApplicationDbContext> dbContextFactory)
    {
        _dbContextFactory = dbContextFactory;
        _userFaker = new Faker<User>()
            .RuleFor(u => u.FirstName, f => f.Name.FirstName())
            .RuleFor(u => u.LastName, f => f.Name.LastName())
            .RuleFor(u => u.Email, f => f.Internet.Email());
    }

    public async Task ProcessAsync(CancellationToken stoppingToken)
    {
        using var dbContext = _dbContextFactory.CreateDbContext();
        
        if (await dbContext.Users.AnyAsync(stoppingToken))
            return; // Data already exists

        var users = _userFaker.Generate(100);
        await dbContext.Users.AddRangeAsync(users, stoppingToken);
        await dbContext.SaveChangesAsync(stoppingToken);
    }
}

Configuring Migrations in Program.cs

var builder = WebApplication.CreateBuilder(args);

// Configure SQL migrations with your DbContext and seed data processor
builder.AddSqlMigrations<ApplicationDbContext, UserSeedDataProcessor>("ApplicationDb");

var app = builder.Build();

Using in Hosted Service

public class DatabaseInitializationService : IHostedService
{
    private readonly IMigrationsProcessor _migrationsProcessor;
    private readonly ISeedDataProcessor _seedDataProcessor;

    public DatabaseInitializationService(
        IMigrationsProcessor migrationsProcessor,
        ISeedDataProcessor seedDataProcessor)
    {
        _migrationsProcessor = migrationsProcessor;
        _seedDataProcessor = seedDataProcessor;
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        await _migrationsProcessor.MigrateAsync(cancellationToken);
        await _seedDataProcessor.ProcessAsync(cancellationToken);
    }

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

Connection String Configuration

The AddSqlMigrations method reads connection strings from configuration. If no connection string is found, it defaults to a local SQL Server instance:

{
  "ConnectionStrings": {
    "ApplicationDb": "Server=myserver;Database=MyApp;..."
  }
}

Default fallback: Server=.;Database={name};Integrated Security=True;TrustServerCertificate=True;

Integration with Launchpad

This library is part of the larger Nabs Launchpad framework and integrates with:

• Core.Testing.Silos: Provides test data for Orleans silo testing
• Core.Persistence: Works with Entity Framework contexts for data operations
• Core.Context: Integrates with application database contexts

Best Practices

1. Environment-Specific Data: Only seed data appropriate for the current environment
2. Idempotent Operations: Ensure seed operations can be run multiple times safely
3. Performance Considerations: Use bulk operations for large datasets
4. Error Handling: Implement proper error handling and logging
5. Cancellation Support: Always respect cancellation tokens for graceful shutdowns
6. Constructor Pattern: Seed data processors should accept IDbContextFactory<TDbContext> as their first constructor parameter

Testing

The library includes comprehensive unit tests in the Launchpad.Core.SeedData.UnitTests project to ensure reliability and correctness of the interfaces and any shared implementations.

Contributing

This library follows the Nabs Launchpad coding standards:

• Use C# 13 features and latest language constructs
• Follow nullable reference types conventions
• Implement proper async/await patterns
• Include comprehensive unit tests

License

Copyright © Net Advantage Business Solutions