mirror of https://github.com/abpframework/abp.git
enisn
1 year ago
1 changed files with 221 additions and 0 deletions
@ -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. |
||||
Loading…
Reference in new issue