Skip to content

MIGRATION_SUMMARY.md

Latest commit

 

History

History
132 lines (102 loc) · 4.5 KB

MIGRATION_SUMMARY.md

File metadata and controls

132 lines (102 loc) · 4.5 KB
Raw

Shared Files to Framework Migration - Summary

User Request

Move ALL shared files to Framework so that Utilities, Tasks, Build, and MSBuild projects get shared code through Framework only (not direct Shared references).

Result

Migration is MOSTLY FEASIBLE - Only 4-5 files blocked by TaskLoggingHelper.

Corrected Analysis: Migration is Mostly Feasible

Key Discovery

ErrorUtilities, ResourceUtilities, FileUtilities have NO Utilities dependencies!

  • They only depend on Framework
  • Can be moved to Framework without circular dependencies
  • This unblocks ~50+ other Category 1 files

Limited Blocker: TaskLoggingHelper Only

Framework (would contain Shared files)
    ↓
PropertyParser, PlatformNegotiation (only 4 Shared files affected)
    ↓
TaskLoggingHelper (Utilities public API)
    ↓
Framework (Utilities depends on Framework)

Only 4-5 files have this circular dependency.

Key Finding

TaskLoggingHelper is defined in src/Shared/TaskLoggingHelper.cs but is compiled as:

  • Public class in Microsoft.Build.Utilities namespace (Utilities DLL)
  • Public API - exposed to all MSBuild tasks through Task.Log property

Shared files that depend on it:

  • PropertyParser.cs
  • PlatformNegotiation.cs
  • TaskLoggingHelperExtension.cs
  • AssemblyFolders/AssemblyFoldersFromConfig.cs

Answers to Specific Questions

1. "Utilities project should not contain anything referenced by Shared"

Answer: It DOES.

Utilities contains TaskLoggingHelper (public API) which IS referenced by Shared files.

2. "All shared files should be internal"

Answer: MOSTLY TRUE (corrected).

Only 2 files have public visibility:

  • IMSBuildElementLocation.cs - Only compiled in Framework, not truly shared
  • NodeEngineShutdownReason.cs - Can move file, namespace doesn't need to change

Previous analysis was WRONG - these are actually INTERNAL:

  • FileMatcher.cs - internal
  • ReadOnlyEmptyDictionary.cs - internal
  • FileSystem/WindowsNative.cs - internal

Current State

Successfully Moved (5 files - 4.3% reduction)

  • ✅ CanonicalError.cs
  • ✅ FileDelegates.cs
  • ✅ VersionUtilities.cs
  • ✅ AssemblyFolders/Serialization/AssemblyFolderCollection.cs
  • ✅ AssemblyFolders/Serialization/AssemblyFolderItem.cs

Can Move (~54 Category 1 files - 46% potential reduction)

  • ✅ ErrorUtilities, ResourceUtilities, FileUtilities (foundational, no Utilities deps)
  • ✅ All Category 1 files except TaskLoggingHelper-dependent ones
  • ✅ Includes: FrameworkLocationHelper, FileMatcher, Registry files, etc.

Cannot Move (4-5 files - TaskLoggingHelper-dependent)

  • ❌ TaskLoggingHelper.cs (Utilities public API)
  • ❌ PropertyParser.cs
  • ❌ PlatformNegotiation.cs
  • ❌ TaskLoggingHelperExtension.cs
  • ❌ AssemblyFoldersFromConfig.cs

Options Forward

Option 1: Large-Scale Migration ✅ RECOMMENDED

Move ~54 Category 1 files to Framework:

  • ErrorUtilities, ResourceUtilities, FileUtilities (no Utilities deps!)
  • All Category 1 files except 4-5 TaskLoggingHelper-dependent ones
  • 46% reduction in duplication
  • No breaking changes required
  • Achieves stated goal for most files

Option 2: Conservative Approach

  • Keep current 5 files
  • Add 10-15 more simple files (Registry, interfaces, extensions)
  • ~15-20% reduction
  • Lower implementation risk

Option 3: Complete Migration (Breaking Changes) ⚠️

If breaking changes acceptable:

  1. Move TaskLoggingHelper to Framework
  2. Change namespace to Microsoft.Build.Framework
  3. Move remaining 4-5 files
  4. Requires major version bump
  5. Achieves 100% migration goal

Technical Details

See SHARED_TO_FRAMEWORK_MIGRATION.md for complete analysis including:

  • List of all 117 shared files
  • Dependency analysis
  • Conditional compilation details
  • Architecture diagrams

Conclusion

The goal of moving shared files to Framework CAN MOSTLY be achieved:

  1. 54 of 58 Category 1 files can move (93% of goal)
  2. Only 4-5 files blocked by TaskLoggingHelper dependency
  3. ErrorUtilities has no circular dependency - it can move!
  4. This enables ~46% reduction in duplication

Corrected Understanding:

  • Previous analysis incorrectly thought ErrorUtilities blocked migration
  • ErrorUtilities only depends on Framework, not Utilities
  • This unblocks the majority of shared files

Next Steps:

  1. Move ErrorUtilities, ResourceUtilities, FileUtilities to Framework
  2. Move all other Category 1 files except TaskLoggingHelper-dependent ones
  3. Update project references
  4. Achieve 46% reduction without breaking changes