adrs/005-slnx-solution-format.md

ADR-005: Adoption of .slnx Solution Format

Status

Accepted

Context

The Acsis Core Polylith monorepo contains 20+ components, each with 2-3 projects (Spec, Implementation, Tests), plus bases and projects. This creates a large number of projects that need to be organized in a single development solution.

Traditional Visual Studio .sln files presented several challenges:

Readability Issues:

Binary/encoded format difficult to read and understand
Complex GUID-based project references
Merge conflicts are difficult to resolve
Hard to review changes in pull requests

Maintenance Challenges:

Manual editing requires understanding complex format
Adding new projects requires GUID generation
Project paths are fragile to directory restructuring
Solution folders are cumbersome to manage

Polylith-Specific Issues:

Need clear organization by component and type
Many projects make traditional solution navigation cumbersome
Want to show architectural structure in solution organization
Difficult to maintain consistent project grouping

The new .slnx format (XML-based solution files) was introduced in Visual Studio 2022 17.8 and offers a modern alternative to traditional .sln files.

Decision

We adopted the new .slnx (XML-based) solution format for the development workspace.

Key Benefits:

Human-readable XML: Easy to read, edit, and review
Merge-friendly: Text-based format resolves conflicts cleanly
Path-based references: No GUIDs, uses relative paths
Hierarchical organization: Clear folder structure matches repository layout
Modern tooling: Future-proof with Microsoft's direction

Solution Structure:

<Solution>
  <Folder Name="/projects/">
    <Folder Name="/projects/bbu-rfid/">
      <Project Path="../projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/Acsis.Dynaplex.Projects.BbuRfid.csproj" />
    </Folder>
  </Folder>
  <Folder Name="/engines/">
    <Folder Name="/engines/core-data/">
      <Project Path="../engines/core-data/src/Acsis.Dynaplex.Engines.CoreData/Acsis.Dynaplex.Engines.CoreData.csproj" />
      <Project Path="../engines/core-data/src/Acsis.Dynaplex.Engines.CoreData.Spec/Acsis.Dynaplex.Engines.CoreData.Spec.csproj" Type="Classic C#" />
    </Folder>
    <!-- ... more components -->
  </Folder>
</Solution>

Organization Principles:

Mirror repository structure: Solution folders match physical directory structure
Group by component: Each component has its own solution folder
Separate Spec and Implementation: Both projects visible but clearly distinguished
Hierarchical navigation: Logical grouping for easy navigation

Consequences

Positive

Developer Experience:

Clear navigation: Solution structure mirrors repository layout
Easy project location: Developers can quickly find relevant projects
Logical grouping: Components grouped together for context
Familiar structure: Matches file system organization

Maintenance Benefits:

Human-readable format: Can be edited in any text editor
Version control friendly: Clean diffs and merge conflict resolution
No GUID management: Path-based references are self-documenting
Easy project addition: Simple XML addition for new components

Review and Collaboration:

Reviewable changes: Solution changes are clear in pull requests
Merge conflict resolution: Text-based conflicts are easier to resolve
Documentation: Solution structure serves as architecture documentation
Team coordination: Clear project organization aids team collaboration

Architecture Alignment:

Visual representation: Solution structure shows architectural boundaries
Component isolation: Each component's projects are grouped together
Clear dependencies: Project references are explicit and readable
Polylith visualization: Solution represents Polylith structure clearly

Negative

Tool Compatibility:

New format: Not supported by older Visual Studio versions (< 17.8)
Third-party tools: Some tools may not support .slnx format yet
Build servers: CI/CD systems need updated tooling
IDE limitations: Feature parity with .sln may lag in some IDEs

Transition Challenges:

Team migration: All developers need compatible IDE versions
Legacy tooling: Existing scripts/tools expect .sln format
Learning curve: Team needs to understand new format
Backup strategy: May need to maintain .sln fallback temporarily

Ecosystem Maturity:

Community adoption: Limited community experience with .slnx
Documentation: Less documentation and examples available
Tooling gaps: Some specialized tools may not support format
Unknown issues: Potential undiscovered issues with new format

Performance Considerations:

Load time: Unknown performance characteristics with large solutions
Memory usage: Impact on IDE memory usage unclear
Build performance: Effect on build times needs monitoring

Mitigation Strategies

Compatibility Management:

<!-- Maintain .sln backup for compatibility -->
./
├── acsis-core.slnx           # Primary development solution
├── acsis-core.sln.bak        # Backup traditional format
└── acsis-core.sln.DotSettings.user

Tool Requirements:

Document minimum Visual Studio/Rider versions
Update CI/CD pipelines to use compatible tooling
Provide guidance for developers on IDE updates

Gradual Migration:

Phase introduction with team feedback
Monitor for issues and performance impacts
Maintain fallback options during transition

Documentation:

Clear documentation of .slnx benefits and usage
Migration guide for team members
Troubleshooting guide for common issues

Implementation Details

Current Solution Structure:

acsis-core.slnx
├── /projects/
│   └── /projects/bbu-rfid/
│       └── Acsis.Dynaplex.Projects.BbuRfid.csproj
├── /engines/
│   ├── /strata/analyzers/
│   │   └── Acsis.RoslynAnalyzers.csproj
│   ├── /engines/core-data/
│   │   ├── Acsis.Dynaplex.Engines.CoreData.csproj
│   │   └── Acsis.Dynaplex.Engines.CoreData.Spec.csproj
│   └── ... (18 more components)

Project Type Annotations:

<!-- Spec projects marked as "Classic C#" for distinction -->
<Project Path="../engines/core-data/src/Acsis.Dynaplex.Engines.CoreData.Spec/Acsis.Dynaplex.Engines.CoreData.Spec.csproj" Type="Classic C#" />

Benefits in Practice:

Quick navigation: Developers can quickly jump to any component
Architecture visibility: Solution structure shows component boundaries
Easy maintenance: Adding new components is straightforward XML editing
Clean reviews: Solution changes are reviewable and understandable

Performance Observations

After adoption:

Load time: Comparable to traditional .sln with large project count
Memory usage: No significant increase observed
Build performance: No measurable impact on build times
IDE responsiveness: Similar performance to .sln format

ADR-001: Architecture requiring organized project structure
ADR-002: Spec naming visible in solution structure
ADR-006: MSBuild properties supporting project references

Alternatives Considered

Traditional .sln Format

Pros: Universal compatibility, mature tooling, well-understood
Cons: Poor readability, difficult maintenance, merge conflicts

Multiple Solution Files

Pros: Smaller solutions, component-focused development
Cons: Fragmented development experience, difficult cross-component work

Directory.Build.props Only

Pros: No solution file needed, purely MSBuild-based
Cons: Poor IDE support, no project organization, difficult navigation

Custom Solution Management

Pros: Tailored to exact needs, maximum flexibility
Cons: Significant development overhead, limited IDE integration

Success Metrics

The .slnx adoption has been successful based on:

Developer feedback: Positive response to improved navigation
Maintenance reduction: Easier solution file management
Review quality: Better visibility of structural changes in PRs
New developer onboarding: Clearer project organization aids understanding

Future Considerations

IDE Evolution: Monitor Visual Studio and Rider support improvements
Tooling Ecosystem: Watch for third-party tool adoption
Performance Optimization: Investigate large solution performance optimizations
Advanced Features: Explore additional .slnx capabilities as they're released

The .slnx format has proven to be an excellent choice for managing the complex project structure required by our Polylith architecture.

Documentation