Create installer-projects.md

7 months ago · 536152aae7
1 changed files with 221 additions and 0 deletions
--- a/docs/en/framework/architecture/modularity/installer-projects.md
+++ 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<AbpVirtualFileSystemOptions>(options =>
+        {
+            options.FileSets.AddEmbedded<AbpAccountInstallerModule>();
+        });
+    }
+}
+```
+
+### Project Configuration
+
+The `.csproj` file embeds module metadata as content:
+
+```xml
+<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:
+
+```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<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:
+
+```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.