LMES 标准组件源码二开指南

本文档详细说明如何将 LMES 标准组件从 MesSuite 大解决方案中独立出来，实现独立编译和部署。适用于所有 LMES 标准组件，如 QualityManagement（质量管理）、ProductManagement（产品管理）、OrderManagement（工单管理）等。

开发环境准备

1. 环境要求

• .NET SDK：6.0 或更高版本

• IDE：Visual Studio 2022 / JetBrains Rider / VS Code

• 数据库（任选其一）：

  • MySQL 8.0.32+
  • PostgreSQL 12+
  • SQL Server 2016+

• Git：版本控制工具

2. 安装依赖

Windows PowerShell / CMD：

# 验证 .NET SDK 版本
dotnet --version

# 克隆项目（如果尚未克隆）
git clone [repository-url]

# 进入组件目录（以 QualityManagement 为例）
cd QualityManagement

# 还原 NuGet 包
dotnet restore

3. 配置 NuGet 包源

确保 NuGet.config 文件配置了正确的包源地址：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nexus" value="https://nexus.sycdev.com/repository/nuget-group/index.json" />
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

独立编译配置

配置原则

核心概念：将 LMES 标准组件从 MesSuite 大解决方案中独立出来，实现独立编译和部署。

适用组件：

• ✅ QualityManagement（质量管理）
• ✅ ProductManagement（产品管理）
• ✅ OrderManagement（工单管理）
• ✅ 其他所有 LMES 标准组件

识别规则：

• ✅ 需要修改：所有引用外部解决方案的 ProjectReference
• ✅ 判断标准：Include​ 路径包含 ..\..\..\..\src\ 或跨插件引用
• ❌ 保持不变：本解决方案内部的 ProjectReference

转换步骤

步骤 1：识别外部项目引用

检查所有 .csproj 文件，查找外部解决方案引用：

Windows PowerShell：

# 方式 1：使用 Select-String（推荐）
# 在组件根目录执行，查找所有外部引用
Get-ChildItem -Path src -Recurse -Filter *.csproj | Select-String -Pattern "ProjectReference.*\\\\\\\\"

# 方式 2：查找特定模式的外部引用
Get-ChildItem -Path src -Recurse -Filter *.csproj | Select-String -Pattern "ProjectReference.*src\\\\CMS.Plugin"

# 方式 3：输出到文件
Get-ChildItem -Path src -Recurse -Filter *.csproj | Select-String -Pattern "ProjectReference.*\\\\\\\\" > external-references.txt

Windows CMD：

:: 查找所有外部引用
findstr /S /C:"ProjectReference" src\*.csproj

:: 查找包含多层路径的引用
findstr /S /C:"..\\..\\..\\.." src\*.csproj

跨平台方式（Linux/macOS/Windows）：

# 使用 dotnet CLI 或文本编辑器的全局搜索功能
# Visual Studio: Ctrl+Shift+F
# VS Code: Ctrl+Shift+F
# Rider: Ctrl+Shift+F
# 搜索关键字：ProjectReference.*\..\..

步骤 2：应用转换规则

通用转换模板：

<!-- ❌ 转换前：外部解决方案的项目引用 -->
<ProjectReference Include="..\..\..\..\src\[项目名称]\[项目名称].csproj" />

<!-- ✅ 转换后：对应的包引用 -->
<PackageReference Include="[项目名称]" Version="$(LMESFrameworkPackageVersion)" />

转换规则说明：

1. 将 ProjectReference​ 改为 PackageReference

2. ​Include​ 值从文件路径改为包名称（去掉路径和 .csproj 后缀）

3. 添加 Version 属性，使用对应的版本变量：

   • LMES 组件：$(LMESFrameworkPackageVersion)
   • CMS 框架：$(CMSFrameworkPackageVersion)
   • ABP 框架：$(ABPPackageVersion)

步骤 3：实际修改示例

示例 1：修改 Application 层引用（以 QualityManagement 为例）

文件：src/CMS.Plugin.{组件名称}.Application/CMS.Plugin.{组件名称}.Application.csproj

实际示例：src/CMS.Plugin.QualityManagement.Application/CMS.Plugin.QualityManagement.Application.csproj

<!-- ❌ 修改前 -->
<ItemGroup>
  <!-- 外部解决方案引用 - 需要改为 PackageReference -->
  <ProjectReference Include="..\..\..\..\src\CMS.Plugin.MesSuite.Shared\CMS.Plugin.MesSuite.Shared.csproj" />
  
  <!-- 本解决方案内部引用 - 保持 ProjectReference -->
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.Application.Contracts\CMS.Plugin.QualityManagement.Application.Contracts.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.Domain\CMS.Plugin.QualityManagement.Domain.csproj" />
</ItemGroup>

<!-- ✅ 修改后 -->
<ItemGroup>
  <!-- 改为包引用 -->
  <PackageReference Include="CMS.Plugin.MesSuite.Shared" Version="$(LMESFrameworkPackageVersion)" />
  
  <!-- 本解决方案内部引用保持不变 -->
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.Application.Contracts\CMS.Plugin.QualityManagement.Application.Contracts.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.Domain\CMS.Plugin.QualityManagement.Domain.csproj" />
</ItemGroup>

示例 2：修改主组件项目引用（以 QualityManagement 为例）

文件：src/CMS.Plugin.{组件名称}/CMS.Plugin.{组件名称}.csproj

实际示例：src/CMS.Plugin.QualityManagement/CMS.Plugin.QualityManagement.csproj

<!-- ❌ 修改前 -->
<ItemGroup>
  <!-- 外部插件引用 - 需要改为 PackageReference -->
  <ProjectReference Include="..\..\..\ProductManagement\src\CMS.Plugin.ProductManagement.Abstractions\CMS.Plugin.ProductManagement.Abstractions.csproj" />
  
  <!-- 本解决方案内部引用 - 保持 ProjectReference -->
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.Application\CMS.Plugin.QualityManagement.Application.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.EntityFrameworkCore\CMS.Plugin.QualityManagement.EntityFrameworkCore.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.MySQL\CMS.Plugin.QualityManagement.MySQL.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.PostgreSql\CMS.Plugin.QualityManagement.PostgreSql.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.SqlServer\CMS.Plugin.QualityManagement.SqlServer.csproj" />
</ItemGroup>

<!-- ✅ 修改后 -->
<ItemGroup>
  <!-- 改为包引用 -->
  <PackageReference Include="CMS.Plugin.ProductManagement.Abstractions" Version="$(LMESFrameworkPackageVersion)" />
  
  <!-- 本解决方案内部引用保持不变 -->
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.Application\CMS.Plugin.QualityManagement.Application.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.EntityFrameworkCore\CMS.Plugin.QualityManagement.EntityFrameworkCore.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.MySQL\CMS.Plugin.QualityManagement.MySQL.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.PostgreSql\CMS.Plugin.QualityManagement.PostgreSql.csproj" />
  <ProjectReference Include="..\CMS.Plugin.QualityManagement.SqlServer\CMS.Plugin.QualityManagement.SqlServer.csproj" />
</ItemGroup>

步骤 4：版本号配置

版本号统一在 package.reference.props 文件中管理：

<Project>
  <PropertyGroup>
    <!-- Microsoft 包版本 -->
    <MicrosoftPackageVersion>6.0.0</MicrosoftPackageVersion>
    
    <!-- ABP 框架包版本 -->
    <ABPPackageVersion>6.0.0</ABPPackageVersion>
    
    <!-- CMS Abp 包版本 -->
    <CMSAbpPackageVersion>1.4.1</CMSAbpPackageVersion>
    
    <!-- CMS Framework 包版本 -->
    <CMSFrameworkPackageVersion>2.16.1</CMSFrameworkPackageVersion>
    
    <!-- LMES 框架包版本 - 需要与 common.props 中的版本保持一致 -->
    <LMESFrameworkPackageVersion>2.7.1.6</LMESFrameworkPackageVersion>
  </PropertyGroup>
</Project>

版本号使用说明：

• ​$(LMESFrameworkPackageVersion)：用于 LMES 相关包（如 MesSuite.Shared、ProductManagement.Abstractions 等）
• ​$(CMSFrameworkPackageVersion)：用于 CMS Framework 包
• ​$(CMSAbpPackageVersion)：用于 CMS ABP 扩展包
• ​$(ABPPackageVersion)：用于 ABP Framework 核心包

⚠️ 重要提示：版本一致性

在修改为 PackageReference 时，必须确保 LMESFrameworkPackageVersion 的版本号与当前源码的版本保持一致：

1. 查看当前源码版本：查看 common.props 文件

   # 打开组件根目录下的 common.props 文件
   notepad common.props
   
   # 或使用 PowerShell 查看版本信息
   Select-String -Path common.props -Pattern "VersionPrefix"

   在 common.props 文件中查找版本定义：

   <PropertyGroup>
     <VersionMajor>2</VersionMajor>
     <VersionMinor>7</VersionMinor>
     <VersionPatch>1</VersionPatch>
     <VersionCode>6</VersionCode>
     <VersionPrefix>$(VersionMajor).$(VersionMinor).$(VersionPatch).$(VersionCode)</VersionPrefix>
     <!-- 完整版本号为：2.7.1.6 -->
   </PropertyGroup>

2. 确认 NuGet 包版本：

   # 在 NuGet 包源中查询可用版本
   dotnet list package --include-transitive | Select-String "CMS.Plugin.MesSuite.Shared"
   
   # 或访问 NuGet 包源网站查看已发布的版本

3. 版本匹配原则：

   • ✅ 推荐：使用与当前源码相同的版本号（如 common.props​ 中定义的 2.7.1.6）
   • ✅ 兼容：使用已发布的稳定版本（查询 NuGet 包源确认）
   • ❌ 避免：使用未发布的版本号（会导致 dotnet restore 失败）
   • ❌ 避免：版本号过低（可能缺少必要的 API 或功能）

4. 版本不匹配的表现：

   • ​dotnet restore 失败，提示找不到包
   • 编译通过但运行时出现 FileNotFoundException
   • API 不兼容导致的编译错误

5. 版本同步建议：

   <!-- 在 package.reference.props 中设置与 common.props 一致的版本 -->
   <!-- 示例：如果 common.props 中版本为 2.7.1.6 -->
   <LMESFrameworkPackageVersion>2.7.1.6</LMESFrameworkPackageVersion>
   
   <!-- 如果不确定版本，可以先使用通配符（仅开发阶段，不推荐用于生产） -->
   <!-- <LMESFrameworkPackageVersion>2.7.*</LMESFrameworkPackageVersion> -->

6. 实际操作步骤：

   # 步骤 1：查看 common.props 中的版本号
   Select-String -Path common.props -Pattern "VersionPrefix|VersionMajor|VersionMinor"
   
   # 步骤 2：确认 NuGet 包源中是否有该版本
   dotnet list package --include-transitive | Select-String "CMS.Plugin.MesSuite.Shared"
   
   # 步骤 3：修改 package.reference.props 中的版本号
   # 使用文本编辑器打开 package.reference.props
   notepad package.reference.props
   
   # 步骤 4：验证配置
   dotnet restore
   dotnet build

步骤 5：验证配置

修改完成后，执行以下命令验证：

Windows PowerShell / CMD：

# 清理项目
dotnet clean

# 还原 NuGet 包
dotnet restore

# 编译项目
dotnet build

# 如果编译成功，说明配置正确
# 如果失败，检查错误信息，确认包版本是否正确

验证检查清单：

• ✅ 所有外部引用已改为 PackageReference
• ✅ 版本变量引用正确
• ✅ LMESFrameworkPackageVersion 版本与源码版本一致
• ✅ NuGet 包源配置正确
• ✅ 编译无错误
• ✅ 运行时无版本冲突