Version: Next

LMES Standard Component Source Code Customization Guide

This document details how to decouple LMES standard components from the MesSuite large solution to achieve independent compilation and deployment. It applies to all LMES standard components, such as QualityManagement, ProductManagement, OrderManagement, etc.

Development Environment Preparation

1. Environment Requirements

.NET SDK: 6.0 or higher
IDE: Visual Studio 2022 / JetBrains Rider / VS Code
Database (Choose one):
- MySQL 8.0.32+
- PostgreSQL 12+
- SQL Server 2016+
Git: Version control tool

2. Install Dependencies

Windows PowerShell / CMD:

# Verify .NET SDK version
dotnet --version

# Clone project (if not already cloned)
git clone [repository-url]

# Enter component directory (taking QualityManagement as an example)
cd QualityManagement

# Restore NuGet packages
dotnet restore

3. Configure NuGet Package Source

Ensure NuGet.config file has the correct package source address configured:

<?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>

Independent Compilation Configuration

Configuration Principles

Core Concept: Decouple LMES standard components from the MesSuite large solution to achieve independent compilation and deployment.

Applicable Components:

✅ QualityManagement
✅ ProductManagement
✅ OrderManagement
✅ All other LMES standard components

Identification Rules:

✅ Need Modification: All ProjectReference referencing external solutions
✅ Criteria: Include path contains ..\..\..\..\src\ or cross-plugin references
❌ Keep Unchanged: ProjectReference within this solution

Conversion Steps

Step 1: Identify External Project References

Check all .csproj files to find external solution references:

Windows PowerShell:

# Method 1: Use Select-String (Recommended)
# Execute in component root directory, find all external references
Get-ChildItem -Path src -Recurse -Filter *.csproj | Select-String -Pattern "ProjectReference.*\\\\\\\\"

# Method 2: Find external references with specific pattern
Get-ChildItem -Path src -Recurse -Filter *.csproj | Select-String -Pattern "ProjectReference.*src\\\\CMS.Plugin"

# Method 3: Output to file
Get-ChildItem -Path src -Recurse -Filter *.csproj | Select-String -Pattern "ProjectReference.*\\\\\\\\" > external-references.txt

Windows CMD:

:: Find all external references
findstr /S /C:"ProjectReference" src\*.csproj

:: Find references with multi-level paths
findstr /S /C:"..\\..\\..\\.." src\*.csproj

Cross-platform (Linux/macOS/Windows):

# Use dotnet CLI or text editor's global search function
# Visual Studio: Ctrl+Shift+F
# VS Code: Ctrl+Shift+F
# Rider: Ctrl+Shift+F
# Search keyword: ProjectReference.*\..\..

Step 2: Apply Conversion Rules

General Conversion Template:

<!-- ❌ Before Conversion: External solution project reference -->
<ProjectReference Include="..\..\..\..\src\[ProjectName]\[ProjectName].csproj" />

<!-- ✅ After Conversion: Corresponding package reference -->
<PackageReference Include="[ProjectName]" Version="$(LMESFrameworkPackageVersion)" />

Conversion Rule Explanation:

Change ProjectReference to PackageReference
Change Include value from file path to package name (remove path and .csproj suffix)
Add Version attribute, using the corresponding version variable:
- LMES Component: $(LMESFrameworkPackageVersion)
- CMS Framework: $(CMSFrameworkPackageVersion)
- ABP Framework: $(ABPPackageVersion)

Step 3: Actual Modification Examples

Example 1: Modify Application Layer Reference (taking QualityManagement as an example)

File: src/CMS.Plugin.{ComponentName}.Application/CMS.Plugin.{ComponentName}.Application.csproj

Actual Example: src/CMS.Plugin.QualityManagement.Application/CMS.Plugin.QualityManagement.Application.csproj

<!-- ❌ Before Modification -->
<ItemGroup>
  <!-- External solution reference - Needs to be changed to PackageReference -->
  <ProjectReference Include="..\..\..\..\src\CMS.Plugin.MesSuite.Shared\CMS.Plugin.MesSuite.Shared.csproj" />
  
  <!-- Internal solution reference - Keep 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>

<!-- ✅ After Modification -->
<ItemGroup>
  <!-- Changed to package reference -->
  <PackageReference Include="CMS.Plugin.MesSuite.Shared" Version="$(LMESFrameworkPackageVersion)" />
  
  <!-- Internal solution references remain unchanged -->
  <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>

Example 2: Modify Main Component Project Reference (taking QualityManagement as an example)

File: src/CMS.Plugin.{ComponentName}/CMS.Plugin.{ComponentName}.csproj

Actual Example: src/CMS.Plugin.QualityManagement/CMS.Plugin.QualityManagement.csproj

<!-- ❌ Before Modification -->
<ItemGroup>
  <!-- External plugin reference - Needs to be changed to PackageReference -->
  <ProjectReference Include="..\..\..\ProductManagement\src\CMS.Plugin.ProductManagement.Abstractions\CMS.Plugin.ProductManagement.Abstractions.csproj" />
  
  <!-- Internal solution reference - Keep 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>

<!-- ✅ After Modification -->
<ItemGroup>
  <!-- Changed to package reference -->
  <PackageReference Include="CMS.Plugin.ProductManagement.Abstractions" Version="$(LMESFrameworkPackageVersion)" />
  
  <!-- Internal solution references remain unchanged -->
  <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>

Step 4: Version Number Configuration

Version numbers are uniformly managed in the package.reference.props file:

<Project>
  <PropertyGroup>
    <!-- Microsoft Package Version -->
    <MicrosoftPackageVersion>6.0.0</MicrosoftPackageVersion>
    
    <!-- ABP Framework Package Version -->
    <ABPPackageVersion>6.0.0</ABPPackageVersion>
    
    <!-- CMS Abp Package Version -->
    <CMSAbpPackageVersion>1.4.1</CMSAbpPackageVersion>
    
    <!-- CMS Framework Package Version -->
    <CMSFrameworkPackageVersion>2.16.1</CMSFrameworkPackageVersion>
    
    <!-- LMES Framework Package Version - Must match version in common.props -->
    <LMESFrameworkPackageVersion>2.7.1.6</LMESFrameworkPackageVersion>
  </PropertyGroup>
</Project>

Version Number Usage:

$(LMESFrameworkPackageVersion): For LMES related packages (e.g., MesSuite.Shared, ProductManagement.Abstractions, etc.)
$(CMSFrameworkPackageVersion): For CMS Framework packages
$(CMSAbpPackageVersion): For CMS ABP extension packages
$(ABPPackageVersion): For ABP Framework core packages

⚠️ Important: Version Consistency

When changing to PackageReference, you must ensure that LMESFrameworkPackageVersion matches the current source code version:

Check Current Source Version: Check common.props file

# Open common.props file in component root directory
notepad common.props

# Or use PowerShell to view version info
Select-String -Path common.props -Pattern "VersionPrefix"

Find version definition in common.props:

<PropertyGroup>
  <VersionMajor>2</VersionMajor>
  <VersionMinor>7</VersionMinor>
  <VersionPatch>1</VersionPatch>
  <VersionCode>6</VersionCode>
  <VersionPrefix>$(VersionMajor).$(VersionMinor).$(VersionPatch).$(VersionCode)</VersionPrefix>
  <!-- Full version is: 2.7.1.6 -->
</PropertyGroup>

Confirm NuGet Package Version:

# Query available versions in NuGet package source
dotnet list package --include-transitive | Select-String "CMS.Plugin.MesSuite.Shared"

# Or visit NuGet package source website to check published versions

Version Matching Principle:
- ✅ Recommended: Use the same version number as defined in common.props (e.g., 2.7.1.6)
- ✅ Compatible: Use a published stable version (confirm via NuGet package source)
- ❌ Avoid: Using unpublished version numbers (will cause dotnet restore failure)
- ❌ Avoid: Version number too low (may miss necessary APIs or features)
Symptoms of Version Mismatch:
- dotnet restore fails, prompting package not found
- Compilation passes but FileNotFoundException occurs at runtime
- Compilation errors due to API incompatibility

Version Synchronization Suggestion:

<!-- Set version consistent with common.props in package.reference.props -->
<!-- Example: If version in common.props is 2.7.1.6 -->
<LMESFrameworkPackageVersion>2.7.1.6</LMESFrameworkPackageVersion>

<!-- If unsure about version, can use wildcard (Development phase only, not recommended for production) -->
<!-- <LMESFrameworkPackageVersion>2.7.*</LMESFrameworkPackageVersion> -->

Actual Operation Steps:

# Step 1: View version number in common.props
Select-String -Path common.props -Pattern "VersionPrefix|VersionMajor|VersionMinor"

# Step 2: Confirm if the version exists in NuGet package source
dotnet list package --include-transitive | Select-String "CMS.Plugin.MesSuite.Shared"

# Step 3: Modify version number in package.reference.props
# Open package.reference.props with text editor
notepad package.reference.props

# Step 4: Verify configuration
dotnet restore
dotnet build

Step 5: Verify Configuration

After modification, execute the following commands to verify:

Windows PowerShell / CMD:

# Clean project
dotnet clean

# Restore NuGet packages
dotnet restore

# Build project
dotnet build

# If build succeeds, configuration is correct
# If fails, check error message and confirm package versions are correct

Verification Checklist:

✅ All external references changed to PackageReference
✅ Version variables referenced correctly
✅ LMESFrameworkPackageVersion matches source version
✅ NuGet package source configured correctly
✅ Compilation has no errors
✅ No runtime version conflicts

Development Environment Preparation​

1. Environment Requirements​

2. Install Dependencies​

3. Configure NuGet Package Source​

Independent Compilation Configuration​

Configuration Principles​

Conversion Steps​

Step 1: Identify External Project References​

Step 2: Apply Conversion Rules​

Step 3: Actual Modification Examples​

Step 4: Version Number Configuration​

Step 5: Verify Configuration​