abp-module

ABP Module Solution Template

Docs: https://abp.io/docs/latest/solution-templates/application-module

This template is for developing reusable ABP modules. Key requirement: extensibility - consumers must be able to override and customize module behavior.

Solution Structure

MyModule/
├── src/
│   ├── MyModule.Domain.Shared/      # Constants, enums, localization
│   ├── MyModule.Domain/             # Entities, repository interfaces, domain services
│   ├── MyModule.Application.Contracts/ # DTOs, service interfaces
│   ├── MyModule.Application/        # Service implementations
│   ├── MyModule.EntityFrameworkCore/ # EF Core implementation
│   ├── MyModule.MongoDB/            # MongoDB implementation
│   ├── MyModule.HttpApi/            # REST controllers
│   ├── MyModule.HttpApi.Client/     # Client proxies
│   ├── MyModule.Web/                # MVC/Razor Pages UI
│   └── MyModule.Blazor/             # Blazor UI
├── test/
│   └── MyModule.Tests/
└── host/
    └── MyModule.HttpApi.Host/       # Test host application

Database Independence

Support both EF Core and MongoDB:

Repository Interface (Domain)

public interface IBookRepository : IRepository<Book, Guid>
{
    Task<Book> FindByNameAsync(string name);
    Task<List<Book>> GetListByAuthorAsync(Guid authorId);
}

EF Core Implementation

public class BookRepository : EfCoreRepository<MyModuleDbContext, Book, Guid>, IBookRepository
{
    public async Task<Book> FindByNameAsync(string name)
    {
        var dbSet = await GetDbSetAsync();
        return await dbSet.FirstOrDefaultAsync(b => b.Name == name);
    }
}

MongoDB Implementation

public class BookRepository : MongoDbRepository<MyModuleMongoDbContext, Book, Guid>, IBookRepository
{
    public async Task<Book> FindByNameAsync(string name)
    {
        var queryable = await GetQueryableAsync();
        return await queryable.FirstOrDefaultAsync(b => b.Name == name);
    }
}

Table/Collection Prefix

Allow customization to avoid naming conflicts:

// Domain.Shared
public static class MyModuleDbProperties
{
    public static string DbTablePrefix { get; set; } = "MyModule";
    public static string DbSchema { get; set; } = null;

    public const string ConnectionStringName = "MyModule";
}

Usage:

builder.Entity<Book>(b =>
{
    b.ToTable(MyModuleDbProperties.DbTablePrefix + "Books", MyModuleDbProperties.DbSchema);
});

Module Options

Provide configuration options:

// Domain
public class MyModuleOptions
{
    public bool EnableFeatureX { get; set; } = true;
    public int MaxItemCount { get; set; } = 100;
}

Usage in module:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    Configure<MyModuleOptions>(options =>
    {
        options.EnableFeatureX = true;
    });
}

Usage in service:

public class MyService : ITransientDependency
{
    private readonly MyModuleOptions _options;

    public MyService(IOptions<MyModuleOptions> options)
    {
        _options = options.Value;
    }
}

Extensibility Points

Virtual Methods (Critical for Modules!)

When developing a reusable module, all public and protected methods must be virtual to allow consumers to override behavior:

public class BookAppService : ApplicationService, IBookAppService
{
    // ✅ Public methods MUST be virtual
    public virtual async Task<BookDto> CreateAsync(CreateBookDto input)
    {
        var book = await CreateBookEntityAsync(input);
        await _bookRepository.InsertAsync(book);
        return _bookMapper.MapToDto(book);
    }

    // ✅ Use protected virtual for helper methods (not private)
    protected virtual Task<Book> CreateBookEntityAsync(CreateBookDto input)
    {
        return Task.FromResult(new Book(
            GuidGenerator.Create(),
            input.Name,
            input.Price
        ));
    }

    // ❌ WRONG for modules - private methods cannot be overridden
    // private Book CreateBook(CreateBookDto input) { ... }
}

This allows module consumers to:

• Override specific methods without copying entire class
• Extend functionality while preserving base behavior
• Customize module behavior for their needs

Entity Extension

Support object extension system:

public class MyModuleModuleExtensionConfigurator
{
    public static void Configure()
    {
        OneTimeRunner.Run(() =>
        {
            ObjectExtensionManager.Instance.Modules()
                .ConfigureMyModule(module =>
                {
                    module.ConfigureBook(book =>
                    {
                        book.AddOrUpdateProperty<string>("CustomProperty");
                    });
                });
        });
    }
}

Localization

// Domain.Shared
[LocalizationResourceName("MyModule")]
public class MyModuleResource
{
}

// Module configuration
Configure<AbpLocalizationOptions>(options =>
{
    options.Resources
        .Add<MyModuleResource>("en")
        .AddVirtualJson("/Localization/MyModule");
});

Permission Definition

public class MyModulePermissionDefinitionProvider : PermissionDefinitionProvider
{
    public override void Define(IPermissionDefinitionContext context)
    {
        var myGroup = context.AddGroup(
            MyModulePermissions.GroupName,
            L("Permission:MyModule"));

        myGroup.AddPermission(
            MyModulePermissions.Books.Default,
            L("Permission:Books"));
    }
}

Best Practices

1. Virtual methods - All public/protected methods must be virtual for extensibility
2. Protected virtual helpers - Use protected virtual instead of private for helper methods
3. Database agnostic - Support both EF Core and MongoDB
4. Configurable - Use options pattern for customization
5. Localizable - Use localization for all user-facing text
6. Table prefix - Allow customization to avoid conflicts
7. Separate connection string - Support dedicated database
8. No dependencies on host - Module should be self-contained
9. Test with host app - Include a host application for testing