跳到主要内容
版本：Next

插件部署流程详细文档

概述​

本文档详细介绍了CMS插件MyPluginName的完整部署流程，重点阐述了自动化发布脚本的使用方法、参数配置、输出目录设置以及多项目发布机制。同时涵盖了开发环境清理的最佳实践，包括如何使用批处理脚本批量删除bin和obj文件夹以避免编译冲突。

项目结构分析​

该项目采用标准的CMS插件架构，包含多个层次的模块化设计：

自动化发布脚本详解​

publish.ps1脚本功能概述​

publish.ps1是一个PowerShell脚本，专门用于自动化.NET Core应用程序的发布流程。该脚本提供了完整的构建、恢复依赖和发布功能。

脚本核心参数配置​

# 发布文件夹路径（可选参数）
$publishFolder = $args[0]

# 根目录路径
$rootFolder = (Get-Item -Path "./" -Verbose).FullName

# 输出目录配置
if ([String]::IsNullOrEmpty($publishFolder)) {
    $publishFolder = Join-Path $rootFolder "output/publish"
    $hasPath = Test-Path($publishFolder)
    if (-Not $hasPath) {
        new-item -path $rootFolder -name "output/publish" -type directory
    }
}

多项目发布机制​

脚本支持单个项目发布，当前配置仅针对主插件项目：

# 项目列表配置
$projects = (
    "src/CMS.Plugin.MyPluginName"
)

dotnet restore命令执行逻辑​

脚本首先执行依赖恢复操作：

# 恢复NuGet包依赖
dotnet restore -s https://nexus.sycdev.com/repository/nuget-hosted/ --runtime win-x64

关键参数说明：

  • -s: 指定NuGet包源地址
  • --runtime win-x64: 指定目标运行时为Windows x64平台

dotnet publish命令执行逻辑​

对于每个项目，脚本执行发布命令：

& dotnet publish ($projectName + ".csproj ") --configuration Release --output (Join-Path $publishFolder ("/" + $projectName.ToLower())) --nologo --verbosity quiet --no-restore --runtime win-x64

发布参数详解：

  • --configuration Release: 指定发布配置为Release模式

  • --output: 指定输出目录，按项目名称小写存储

  • --nologo: 禁用启动标志显示

  • --verbosity quiet: 设置日志级别为静默模式

  • --no-restore: 跳过依赖恢复步骤（因为前面已经执行）

  • --runtime win-x64: 指定目标运行时

  • publish.ps1

开发环境清理工具​

delete-bin-obj-folders.bat功能概述​

该批处理脚本专门用于清理开发环境中的编译输出文件夹，避免编译冲突和磁盘空间浪费。

清理逻辑实现​

@ECHO off
cls

ECHO Deleting all BIN and OBJ folders...
ECHO.

FOR /d /r . %%d in (bin,obj) DO (
    IF EXIST "%%d" (         
        ECHO %%d | FIND /I "\node_modules\" > Nul && ( 
            ECHO.Skipping: %%d
        ) || (
            ECHO.Deleting: %%d
            rd /s/q "%%d"
        )
    )
)

清理策略详解​

  1. 递归遍历: 使用/r参数递归遍历当前目录及其子目录
  2. 目标文件夹过滤: 只处理名为bin和obj的文件夹
  3. 智能跳过: 特别跳过node_modules目录下的bin/obj文件夹
  4. 安全删除: 使用rd /s/q命令强制删除文件夹及其内容

使用场景​

  • 编译前清理: 在重新构建项目前清理旧的编译输出

  • 磁盘空间管理: 定期清理不必要的编译文件

  • 解决编译冲突: 当遇到编译错误时清理可能的缓存问题

  • delete-bin-obj-folders.bat

插件入口点分析​

CMSPluginEntry类的核心作用​

CMSPluginEntry是整个插件系统的核心入口点，负责插件的初始化、配置和服务注册。

注册阶段（Register方法）​

在插件注册阶段，主要完成以下工作：

  1. 外部API配置：
context.Services
    .AddHttpApi<IMyPluginNameExternalApi>()
    .ConfigureHttpApi(configuration.GetSection(nameof(IMyPluginNameExternalApi)));
  1. 服务注册：
context.Services.TryAddMyPluginName();
context.Services.AddScoped<IProjectRuntimeMigrator, CMSPluginRuntimeMigrator>();
context.Services.AddSingleton<IProjectService, MyPluginNameProjectService>();
  1. 数据库适配器配置：
context.Services.AddScoped<IEFDataProvider>(p =>
{
    var cfg = p.GetRequiredService<IDataRuntimeConfig>();
    return new DefaultEFDataProvider(...);
});
  1. 模块配置： 根据数据库类型动态添加相应的模块源：
  • MySQL: typeof(MySQL.CMSPluginMySQLModule)
  • SQL Server: typeof(SqlServer.CMSPluginSqlServerModule)
  • PostgreSQL: typeof(PostgreSql.CMSPluginPostgreSqlModule)

容器配置阶段（ConfigureContainer方法）​

该方法负责将服务集合转换为Autofac容器：

builder.Populate(_service);

就绪阶段（ReadyAsync方法）​

在应用就绪阶段，执行以下初始化操作：

  1. 应用初始化：
var app = context.Features.GetApplicationBuilder();
await app.InitializeApplicationAsync();
  1. 后台工作者注册：
await context.GetRequiredService<IBackgroundWorkerManager>().AddAsync(context.GetRequiredService<MyPluginNameWorker>());

部署流程详解​

完整部署流程图​

部署步骤详解​

第一步：环境准备​

  1. 清理编译缓存：运行delete-bin-obj-folders.bat清理所有bin和obj文件夹
  2. 检查磁盘空间：确保有足够的空间存放发布文件
  3. 验证权限：确认对输出目录有写入权限

第二步：参数处理​

  1. 解析命令行参数：从第一个参数获取自定义输出目录
  2. 设置默认值：如果未提供参数，默认使用output/publish
  3. 创建输出目录：如果不存在则自动创建

第三步：依赖恢复​

  1. 执行dotnet restore：恢复所有NuGet包依赖
  2. 指定运行时：明确指定win-x64运行时
  3. 配置包源：使用企业内部的NuGet包源地址

第四步：项目发布​

  1. 定位项目：进入项目根目录
  2. 执行发布命令：使用预设的发布参数
  3. 输出结果：按照项目名称的小写形式组织输出

第五步：后处理​

  1. 返回根目录：保持工作目录一致性
  2. 验证输出：检查发布文件是否正确生成
  3. 清理临时文件：可选的临时文件清理

发布文件结构​

发布完成后，文件将按照以下结构组织：

output/publish/
└── cms.plugin.mypluginname/
    ├── CMS.Plugin.MyPluginName.dll
    ├── CMS.Plugin.MyPluginName.deps.json
    ├── CMS.Plugin.MyPluginName.runtimeconfig.json
    ├── appsettings.json
    ├── lib/
    └── plugins/

最佳实践建议​

开发环境管理​

  1. 定期清理：建议每周运行一次delete-bin-obj-folders.bat
  2. 版本控制：确保.gitignore中包含bin/和obj/目录
  3. IDE配置：在Visual Studio中配置自动清理选项

发布流程优化​

  1. 并行发布：对于多项目结构，可以考虑并行执行发布命令
  2. 增量发布：只发布变更的项目，减少发布时间
  3. 缓存利用：合理利用NuGet包缓存机制

配置管理​

  1. 外部配置：将敏感配置移至/host/appsettings.json
  2. 环境变量：使用环境变量替代硬编码配置
  3. 配置验证：在发布前验证配置文件的有效性

监控和日志​

  1. 发布监控：记录每次发布的详细信息
  2. 错误追踪：建立完善的错误报告机制
  3. 性能监控：监控发布过程的性能指标

故障排除指南​

常见问题及解决方案​

1. 依赖恢复失败​

症状：dotnet restore命令执行失败 原因：网络连接问题或NuGet包源不可用 解决方案：

  • 检查网络连接
  • 验证NuGet包源地址
  • 使用本地缓存包

2. 编译冲突​

症状：出现重复定义或类型冲突错误 解决方案：

  • 运行delete-bin-obj-folders.bat清理
  • 删除packages目录
  • 重启IDE

3. 权限不足​

症状：无法创建输出目录或写入文件 解决方案：

  • 以管理员权限运行脚本
  • 检查目录权限设置
  • 更改输出目录位置

4. 发布文件缺失​

症状：发布完成后缺少某些文件 解决方案：

  • 检查项目文件配置
  • 验证文件包含规则
  • 重新执行发布命令

调试技巧​

  1. 启用详细日志：修改publish.ps1中的--verbosity参数
  2. 分步执行：将脚本拆分为多个独立的命令
  3. 环境检查：验证.NET SDK版本和运行时状态
  4. 依赖检查：使用dotnet list package检查依赖关系

性能优化​

  1. 并行处理：对于多项目结构，考虑并行发布
  2. 缓存策略：合理利用NuGet包缓存
  3. 网络优化：使用本地镜像或代理服务器
  4. 资源监控：监控CPU和内存使用情况

通过遵循这些最佳实践和故障排除指南，可以确保CMS插件的部署过程顺利进行，并提高整体开发效率。