abp/docs/en/framework/architecture/modularity/installer-projects.md

Module Installer Projects

Each ABP module includes an .Installer project (e.g., Volo.Abp.Account.Installer) that serves as a Virtual File System container for module installation and resource management. These projects are essential for the ABP CLI to understand and install modules properly.

Purpose of Installer Projects

Installer projects have three main purposes:

1. Virtual File System Integration: Register the module's embedded resources with ABP's Virtual File System
2. Resource Packaging: Package module metadata files (.abpmdl and .abppkg) as embedded resources
3. CLI Integration: Enable the ABP CLI to understand module structure and install modules automatically

Structure of Installer Projects

Project Files

• {ModuleName}.Installer.csproj: References Volo.Abp.VirtualFileSystem and embeds module metadata files
• InstallationNotes.md: Documentation for the module
• Volo/Abp/{ModuleName}/Abp{ModuleName}InstallerModule.cs: The core module class that registers embedded resources

Example Installer Module

using Volo.Abp.Modularity;
using Volo.Abp.VirtualFileSystem;

namespace Volo.Abp.Account;

[DependsOn(typeof(AbpVirtualFileSystemModule))]
public class AbpAccountInstallerModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpVirtualFileSystemOptions>(options =>
        {
            options.FileSets.AddEmbedded<AbpAccountInstallerModule>();
        });
    }
}

Project Configuration

The .csproj file embeds module metadata as content:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net9.0</TargetFramework>
        <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
        <RootNamespace />
    </PropertyGroup>

    <ItemGroup>
        <ProjectReference Include="..\..\..\..\framework\src\Volo.Abp.VirtualFileSystem\Volo.Abp.VirtualFileSystem.csproj" />
    </ItemGroup>

    <ItemGroup>
        <!-- Embed module definition file -->
        <Content Include="..\..\Volo.Abp.Account.abpmdl">
            <Pack>true</Pack>
            <PackagePath>content\</PackagePath>
        </Content>
        
        <!-- Embed package definition files -->
        <Content Include="..\..\**\*.abppkg*">
            <Pack>true</Pack>
            <PackagePath>content\</PackagePath>
        </Content>
    </ItemGroup>
</Project>

Module Metadata Files

.abpmdl (Module Definition)

The module definition file describes the module's structure and packages:

{
  "folders": {
    "items": {
      "src": {},
      "test": {}
    }
  },
  "packages": {
    "Volo.Abp.Account.Web": {
      "path": "src/Volo.Abp.Account.Web/Volo.Abp.Account.Web.abppkg",
      "folder": "src"
    },
    "Volo.Abp.Account.Application": {
      "path": "src/Volo.Abp.Account.Application/Volo.Abp.Account.Application.abppkg",
      "folder": "src"
    }
  }
}

.abppkg (Package Definition)

Each package has a definition file that specifies its role:

{
  "role": "lib.application"
}

Common roles:

• lib.application: Application layer package
• lib.mvc: MVC/Web layer package
• lib.domain: Domain layer package
• lib.domain-shared: Shared domain layer package
• lib.efcore: Entity Framework Core package

How Installer Projects Work

1. CLI Installation Process

When you run abp add-module Volo.Abp.Account:

1. Download Installer Package: CLI downloads Volo.Abp.Account.Installer from NuGet
2. Read Module Definition: CLI reads the embedded .abpmdl file to understand module structure
3. Read Package Definitions: CLI reads .abppkg files to understand package roles
4. Install Packages: CLI installs appropriate packages to correct project types based on roles
5. Add Dependencies: CLI adds module dependencies to project module classes

2. Virtual File System Integration

The InstallerModule registers itself with the Virtual File System:

options.FileSets.AddEmbedded<AbpAccountInstallerModule>();

This makes embedded resources available at runtime and enables:

• Access to module metadata
• Resource file management
• Module configuration

Creating Installer Projects for New Modules

Required Files

1. Project File: {ModuleName}.Installer.csproj
2. Module Class: Abp{ModuleName}InstallerModule.cs
3. Documentation: InstallationNotes.md
4. Module Definition: {ModuleName}.abpmdl (in module root)
5. Package Definitions: {PackageName}.abppkg (in each package)

Template Structure

modules/your-module/
├── src/
│   ├── Volo.Abp.YourModule.Installer/
│   │   ├── Volo.Abp.YourModule.Installer.csproj
│   │   ├── InstallationNotes.md
│   │   └── Volo/
│   │       └── Abp/
│   │           └── YourModule/
│   │               └── AbpYourModuleInstallerModule.cs
│   └── [other packages]/
├── Volo.Abp.YourModule.abpmdl
└── [other module files]

Package Definition Examples

For different package types:

// Application package
{ "role": "lib.application" }

// MVC package  
{ "role": "lib.mvc" }

// Domain package
{ "role": "lib.domain" }

// EF Core package
{ "role": "lib.efcore" }

Why Installer Projects Appear "Empty"

Installer projects appear minimal because their primary function is infrastructure, not business logic:

• No Business Logic: Business logic belongs in the actual module packages
• Pure Infrastructure: They only handle module installation and resource management
• CLI Integration: They enable automated module installation through the ABP CLI
• Resource Management: They package and distribute module metadata

Best Practices

1. Follow Naming Convention: Use {ModuleName}.Installer for the project name
2. Include Documentation: Always provide InstallationNotes.md with module information
3. Proper Dependencies: Only depend on Volo.Abp.VirtualFileSystem
4. Embed All Metadata: Include both .abpmdl and .abppkg files
5. Test Installation: Verify your installer works with abp add-module command

Troubleshooting

Common Issues

1. Missing .abpmdl file: Ensure the module definition file exists in the module root
2. Missing .abppkg files: Each package needs a definition file
3. Incorrect roles: Use appropriate roles for each package type
4. CLI not finding module: Verify the installer package is published to NuGet

Verification Steps

1. Build the installer project: dotnet build
2. Check embedded resources: Verify .abpmdl and .abppkg files are embedded
3. Test CLI installation: abp add-module YourModule
4. Verify dependencies: Check that module dependencies are added correctly

This installer system enables ABP's sophisticated module architecture, allowing for automated installation with proper dependency resolution and project type matching.