diff --git a/docs/en/framework/architecture/modularity/installer-projects.md b/docs/en/framework/architecture/modularity/installer-projects.md new file mode 100644 index 0000000000..81c75ab015 --- /dev/null +++ b/docs/en/framework/architecture/modularity/installer-projects.md @@ -0,0 +1,221 @@ +# 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 + +```csharp +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(options => + { + options.FileSets.AddEmbedded(); + }); + } +} +``` + +### Project Configuration + +The `.csproj` file embeds module metadata as content: + +```xml + + + net9.0 + true + + + + + + + + + + + true + content\ + + + + + true + content\ + + + +``` + +## Module Metadata Files + +### `.abpmdl` (Module Definition) + +The module definition file describes the module's structure and packages: + +```json +{ + "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: + +```json +{ + "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: + +```csharp +options.FileSets.AddEmbedded(); +``` + +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: + +```json +// 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. \ No newline at end of file