Madoka.Framework.EntityFrameworkCore 1.0.0-preview.3

Madoka.Framework

English | 简体中文

A multi-tenant, layered framework built on ABP Framework (.NET 10 / ABP 10.5). It integrates commonly used ABP modules out of the box and ships with a custom Tailwind-based Razor Pages admin UI.

Features

• Integrates Identity, Tenant Management, Feature Management, Setting Management, Audit Logging, Background Jobs, Blob Storing, OpenIddict and more
• A unified DbContext base class - consumers simply inherit it to get all entities and configuration
• Built-in admin UI (Users / Roles / Tenants / Feature Management / Audit Logs / Settings / Background Jobs pages) with collapsible sidebar and language switching
• Database migration tool pattern (DbMigrator) that creates the database, applies migrations and seeds data automatically
• Conventional API controllers and Swagger

Requirements

• .NET 10 SDK
• A supported database (e.g. SQL Server, SQLite, PostgreSQL or MySQL) - the framework is database-provider agnostic
• (Optional) Node.js - only needed to rebuild Tailwind styles

Installation

Reference the packages you need from NuGet (prefer the latest preview version):

Domain.Shared / Domain are the required foundation; add EntityFrameworkCore for persistence, HttpApi for APIs, and Web for the admin UI.

Quick Start

The steps below create a layered solution named MyApp. A complete runnable example is available in the sample/ directory of this repository.

1. Define your own DbContext

The framework requires consumers to register their own DbContext. Create an EF Core project (e.g. MyApp.EntityFrameworkCore), reference Madoka.Framework.EntityFrameworkCore, and inherit the generic base class:

using Madoka.Framework.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

namespace MyApp;

public class MyAppDbContext : MadokaFrameworkDbContext<MyAppDbContext>
{
    public MyAppDbContext(DbContextOptions<MyAppDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder); // Required: includes all ABP module entity configuration

        // Add your own entity configuration here
        //builder.Entity<YourEntity>(b =>
        //{
        //    b.ToTable("YourEntities");
        //});
    }
}

2. Configure the EF Core module

Register the DbContext in your EF Core module and point the migrations assembly to your own project (migrations are maintained by the consumer):

using Madoka.Framework.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.EntityFrameworkCore;
using Volo.Abp.EntityFrameworkCore.SqlServer;
using Volo.Abp.Modularity;

[DependsOn(typeof(MyAppDomainModule), typeof(MadokaFrameworkEntityFrameworkCoreModule))]
public class MyAppEntityFrameworkCoreModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.AddAbpDbContext<MyAppDbContext>(options =>
        {
            options.AddDefaultRepositories(includeAllEntities: true);
        });

        Configure<AbpDbContextOptions>(options =>
        {
            options.UseSqlServer(b => b.MigrationsAssembly("MyApp.EntityFrameworkCore"));
        });
    }
}

The example above uses SQL Server. The framework itself is database-provider agnostic: reference the provider package you need (e.g. Volo.Abp.EntityFrameworkCore.SqlServer, Volo.Abp.EntityFrameworkCore.Sqlite, Volo.Abp.EntityFrameworkCore.Npgsql or Volo.Abp.EntityFrameworkCore.MySql) and call the matching Use... extension in your module.

3. Create the initial migration

Add a design-time factory in MyApp.EntityFrameworkCore (recommended):

using Madoka.Framework.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
using Microsoft.Extensions.Configuration;

public class MyAppDbContextFactory : IDesignTimeDbContextFactory<MyAppDbContext>
{
    public MyAppDbContext CreateDbContext(string[] args)
    {
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Path.Combine(Directory.GetCurrentDirectory(), "../MyApp.Web/"))
            .AddJsonFile("appsettings.json", optional: false)
            .Build();

        return new MyAppDbContext(
            new DbContextOptionsBuilder<MyAppDbContext>()
                .UseSqlServer(configuration.GetConnectionString("Default"),
                    b => b.MigrationsAssembly("MyApp.EntityFrameworkCore"))
                .Options);
    }
}

Then generate the migration:

dotnet ef migrations add Initial --context MyAppDbContext \
  --project MyApp.EntityFrameworkCore --startup-project MyApp.EntityFrameworkCore

4. Create the DbMigrator

Create a console project (e.g. MyApp.DbMigrator) referencing MyApp.EntityFrameworkCore and Madoka.Framework.Application.Contracts, and call the framework's migration service from a hosted service:

public class DbMigratorHostedService : IHostedService
{
    private readonly MadokaFrameworkDbMigrationService _migrationService;

    public DbMigratorHostedService(MadokaFrameworkDbMigrationService migrationService)
        => _migrationService = migrationService;

    public async Task StartAsync(CancellationToken cancellationToken)
        => await _migrationService.MigrateAsync(); // Creates the database, migrates and seeds (admin user, OpenIddict clients, etc.)

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

Module declaration:

[DependsOn(
    typeof(AbpAutofacModule),
    typeof(MyAppEntityFrameworkCoreModule),
    typeof(MadokaFrameworkApplicationContractsModule)
)]
public class MyAppDbMigratorModule : AbpModule { }

Configure the connection string and OpenIddict clients (created during seeding) in appsettings.json:

{
  "ConnectionStrings": {
    "Default": "Server=localhost,1433;Database=MyApp;User Id=sa;Password=YourPassword;TrustServerCertificate=true"
  },
  "OpenIddict": {
    "Applications": {
      "MyApp_App": { "ClientId": "MyApp_App", "RootUrl": "https://localhost:44300" },
      "MyApp_Swagger": { "ClientId": "MyApp_Swagger", "RootUrl": "https://localhost:44300/" }
    }
  }
}

Run it to create the database:

dotnet run --project MyApp.DbMigrator

5. Create the web host

Create a web project (e.g. MyApp.Web) referencing MyApp.EntityFrameworkCore and Madoka.Framework.Web. Host module:

[DependsOn(
    typeof(MadokaFrameworkWebModule),
    typeof(MyAppApplicationModule),
    typeof(MyAppEntityFrameworkCoreModule),
    typeof(AbpAutofacModule)
)]
public class MyAppWebModule : AbpModule { }

Program.cs:

var builder = WebApplication.CreateBuilder(args);
builder.Host
    .AddAppSettingsSecretsJson()
    .UseAutofac()
    .UseSerilog((context, services, config) =>
        config.ReadFrom.Configuration(context.Configuration).ReadFrom.Services(services));

await builder.AddApplicationAsync<MyAppWebModule>();
var app = builder.Build();
await app.InitializeApplicationAsync();
await app.RunAsync();

Key appsettings.json settings:

{
  "App": {
    "SelfUrl": "https://localhost:44300",
    "HealthCheckUrl": "/health-status"
  },
  "ConnectionStrings": {
    "Default": "Server=localhost,1433;Database=MyApp;User Id=sa;Password=YourPassword;TrustServerCertificate=true"
  },
  "AuthServer": {
    "Authority": "https://localhost:44300",
    "RequireHttpsMetadata": true,
    "CertificatePassPhrase": "Your certificate passphrase"
  },
  "StringEncryption": {
    "DefaultPassPhrase": "Your encryption passphrase (16+ chars)"
  }
}

Start the app and browse to https://localhost:44300, then sign in with the seeded administrator account (default admin@abp.io / 1q2w3E*).

Configuration Reference

Custom Localization

The framework ships with localized texts for 20 languages. To add your own texts, follow these steps:

1. Define a resource class in your Domain.Shared project:

   [LocalizationResourceName("MyApp")]
   public class MyAppResource { }
   

2. Add language files Localization/MyApp/en.json, zh-Hans.json, etc. (format: { "Culture": "en", "Texts": { "Key": "Value" } }).
3. Register it in your module:

   Configure<AbpVirtualFileSystemOptions>(o => o.FileSets.AddEmbedded<MyAppDomainSharedModule>());
   Configure<AbpLocalizationOptions>(o =>
       o.Resources.Add<MyAppResource>("zh-Hans").AddVirtualJson("/Localization/MyApp"));
   

4. Make sure MyApp.Domain.Shared.csproj includes:
   • <EmbeddedResource Include="Localization\MyApp\*.json" />
   • <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
   • A reference to the Microsoft.Extensions.FileProviders.Embedded package

Use it in pages with @inject IHtmlLocalizer<MyAppResource> L and @L["Key"]. The language switcher is provided by the framework UI.

Using the Integrated Modules

• Background Jobs: implement AsyncBackgroundJob<TArgs> in the domain layer and enqueue with IBackgroundJobManager.EnqueueAsync(...); the Background Jobs page provides list / detail / retry / delete.
• Blob Storing: use IBlobContainer<TContainer> for database-backed blob storage (the default container is enabled).
• Audit Logging: implement audit interfaces such as IHasCreationTime or annotate entities with [Audited]; the Audit Logs page lets you browse records.
• Setting Management: define a SettingDefinitionProvider to add settings, edit them from the Settings page, and read them with ISettingProvider.GetOrNullAsync(...).

Sample Project

The sample/ directory of this repository contains a complete runnable example (Sample.Web + Sample.DbMigrator) demonstrating the standard integration, including a custom DbContext, migrations and localization.

FAQ

Q: Why do I have to register my own DbContext?

The framework no longer registers a default DbContext so that every consumer fully controls its own entities, migrations and database. Inheriting MadokaFrameworkDbContext<TDbContext> gives you all module entities without duplicating work.

Q: How do I customize the UI styles?

The framework UI uses Tailwind CSS (built on demand). To modify framework pages, rebuild wwwroot/css/tailwind.css under src/Madoka.Framework.Web (input tailwind.src.css, output tailwind.css, --minify). Consumers normally don't need to rebuild unless they fork the framework pages.

Q: Migrations report "no migrations found"?

Make sure your EF Core module configures UseSqlServer(b => b.MigrationsAssembly("Your.EntityFrameworkCore.Assembly")) and that migrations are generated in the consumer project.

Q: Permission errors after login?

Run the DbMigrator first to complete seeding; if you changed permission definitions, check that dynamic permission storage is enabled in PermissionManagement.