managing-apps/assets/documentation/NET10-Upgrade-Plan.md

.NET 10 Upgrade Documentation Plan

Overview

This document outlines the comprehensive plan for upgrading the Managing Apps solution from .NET 8 to .NET 10. The upgrade involves multiple .NET projects, Orleans clustering, and requires careful planning to minimize risks and ensure performance improvements.

Current State Assessment

Project Structure

• Backend: Multiple .NET projects targeting net8.0

  • Managing.Api (ASP.NET Core Web API)
  • Managing.Application (Business logic)
  • Managing.Domain (Domain models)
  • Managing.Infrastructure.* (Database, Exchanges, Storage, etc.)
  • Orleans 9.2.1 clustering with PostgreSQL persistence

• Frontend: React/TypeScript application (not affected by .NET upgrade)

Key Dependencies

• Orleans 9.2.1 → Potential upgrade to Orleans 10.x
• Entity Framework Core 8.0.11 → 10.x
• ASP.NET Core 8.0.x → 10.x
• PostgreSQL/Npgsql 8.0.10 → Latest compatible version
• InfluxDB client and other infrastructure dependencies

Upgrade Strategy

Phase 1: Preparation (Week 1-2)

1.1 Development Environment Setup

• Install .NET 10 SDK on all development machines
• Update CI/CD pipelines to support .NET 10
• Create dedicated upgrade branch (feature/net10-upgrade)
• Set up parallel environments (keep .NET 8 for rollback)

1.2 Dependency Analysis

• Audit all NuGet packages for .NET 10 compatibility
• Identify packages requiring updates
• Test critical third-party packages in isolation
• Document breaking changes in dependencies

1.3 Documentation Updates

• Update Dockerfiles (FROM mcr.microsoft.com/dotnet/sdk:8.0 → 10.0)
• Update deployment scripts
• Update README and architecture docs
• Create rollback procedures

Phase 2: Core Framework Upgrade (Week 3-4)

2.1 Project File Updates

Priority Order:

1. Managing.Common, Managing.Core (lowest risk)
2. Managing.Domain (pure domain logic)
3. Managing.Infrastructure.* (infrastructure concerns)
4. Managing.Application (business logic)
5. Managing.Api (entry point, highest risk)

For each project:

<!-- Before -->
<TargetFramework>net8.0</TargetFramework>

<!-- After -->
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>

2.2 Package Updates

Microsoft Packages (Safe to update first):

• Microsoft.AspNetCore.* → 10.x
• Microsoft.EntityFrameworkCore → 10.x
• Microsoft.Extensions.* → 10.x

Third-party Packages:

• Orleans → 10.x (if available) or stay on 9.x with compatibility testing
• Npgsql → Latest .NET 10 compatible
• All other packages → Update to latest versions

Phase 3: Orleans Clustering Upgrade (Week 5-6)

3.1 Orleans Assessment

• Evaluate Orleans 10.x preview vs staying on 9.x
• Test clustering configuration changes
• Validate grain persistence compatibility
• Performance test grain activation/deactivation

3.2 Configuration Updates

// Potential Orleans 10.x configuration changes
builder.Host.UseOrleans(siloBuilder =>
{
    // Updated clustering configuration syntax
    siloBuilder.ConfigureServices(services =>
    {
        // Add any new required services for Orleans 10.x
    });
});

3.3 Clustering Validation

• Multi-server clustering test
• Grain state persistence test
• Reminders and timers validation
• Network partitioning simulation

Phase 4: Database & Infrastructure (Week 7-8)

4.1 Entity Framework Core

• Run EF Core migration scripts
• Test query performance with .NET 10
• Validate async operation improvements
• Memory usage optimization

4.2 Database Providers

• PostgreSQL/Npgsql compatibility testing
• InfluxDB client validation
• Connection pooling optimization
• Transaction handling validation

Phase 5: Performance Optimization (Week 9-10)

5.1 Garbage Collection Tuning

{
  "runtimeOptions": {
    "configProperties": {
      "System.GC.Concurrent": true,
      "System.GC.Server": true,
      "System.GC.HeapCount": 8,
      "System.GC.RetainVM": false,
      "System.GC.NoAffinitize": true
    }
  }
}

5.2 Memory Management

• Implement Span<T> where appropriate
• Optimize string operations
• Use ValueTask for async operations
• Implement object pooling for hot paths

5.3 Async/Await Optimization

• Use ConfigureAwait(false) appropriately
• Implement IAsyncEnumerable for streaming
• Optimize async state machines

Risk Assessment

High Risk Areas

1. Orleans Clustering: Most complex, potential for downtime
2. Database Operations: EF Core changes could affect queries
3. Third-party Dependencies: May not support .NET 10 immediately

Medium Risk Areas

1. ASP.NET Core Middleware: Authentication, routing changes
2. Serialization: JSON/binary serialization changes
3. Logging and Monitoring: Integration compatibility

Low Risk Areas

1. Domain Models: Pure C# logic, minimal changes
2. Business Logic: Framework-agnostic code

Testing Strategy

Unit Testing

• All existing tests pass on .NET 10
• New tests for .NET 10 specific features
• Performance regression tests

Integration Testing

• API endpoint testing
• Database integration tests
• Orleans grain communication tests
• External service integration

Performance Testing

• Memory usage benchmarks
• Request throughput testing
• Orleans grain activation latency
• Database query performance

Staging Environment

• Full system testing in staging
• Load testing with production-like data
• Multi-day stability testing
• Failover and recovery testing

Rollback Plan

Immediate Rollback (First 24 hours)

• Keep .NET 8 containers available
• Feature flags for problematic features
• Database backup and restore procedures

Gradual Rollback (1-7 days)

• Roll back individual services if needed
• Maintain API compatibility during rollback
• Client-side feature toggles

Emergency Procedures

• Complete environment rollback to .NET 8
• Database state recovery
• User communication plan

Success Metrics

Performance Improvements

• 10-20% reduction in memory usage
• 5-15% improvement in request throughput
• Reduced GC pause times
• Faster application startup

Reliability Improvements

• Zero downtime during upgrade
• No data loss or corruption
• All existing functionality preserved
• Improved error handling and logging

Development Experience

• Faster build times
• Better debugging experience
• Access to latest .NET features
• Improved developer productivity

Timeline and Milestones

Week 1-2: Preparation

• Environment setup complete
• Dependency analysis finished
• Documentation updated

Week 3-4: Core Upgrade

• All project files updated to .NET 10
• Microsoft packages updated
• Basic functionality testing passed

Week 5-6: Orleans Upgrade

• Orleans configuration updated
• Clustering validation complete
• Grain functionality verified

Week 7-8: Infrastructure

• Database operations validated
• External integrations tested
• Performance benchmarks established

Week 9-10: Optimization

• Memory optimizations implemented
• Performance tuning complete
• Final testing and validation

Week 11-12: Production Deployment

• Staging environment validation
• Production deployment
• Post-deployment monitoring
• Go-live decision

Communication Plan

Internal Stakeholders

• Weekly progress updates
• Risk assessments and mitigation plans
• Go/no-go decision checkpoints

External Users

• Pre-upgrade notification
• Maintenance window communication
• Post-upgrade feature announcements

Monitoring and Observability

Key Metrics to Monitor

• Application memory usage
• CPU utilization
• Request latency and throughput
• Error rates and exceptions
• Orleans cluster health
• Database connection pools
• Garbage collection statistics

Alerting Setup

• Memory usage thresholds
• Error rate monitoring
• Performance degradation alerts
• Orleans cluster health checks

Contingency Plans

Package Compatibility Issues

• Pin incompatible packages to working versions
• Implement adapter patterns for breaking changes
• Vendor critical dependencies if needed

Performance Regression

• Performance profiling and optimization
• Feature flags for performance-intensive features
• Gradual rollout with A/B testing

Orleans Issues

• Alternative clustering configurations
• Grain state migration procedures
• Fallback to single-server mode

Resources Required

Team

• 2-3 Senior .NET Developers
• 1 DevOps Engineer
• 1 QA Engineer
• 1 Product Owner

Infrastructure

• Staging environment identical to production
• Performance testing environment
• Backup and recovery systems
• Monitoring and alerting setup

Budget

• Development time: 8-12 weeks
• Infrastructure costs for testing environments
• Third-party tool licenses if needed
• Training and documentation time

---

Appendices

Appendix A: Package Compatibility Matrix

Package	Current Version	.NET 10 Compatible	Notes
Microsoft.AspNetCore.*	8.0.x	10.x	Direct upgrade
Microsoft.EntityFrameworkCore	8.0.11	10.x	Migration scripts required
Microsoft.Orleans.*	9.2.1	10.x (preview)	Major version upgrade

Appendix B: Breaking Changes Checklist

• ASP.NET Core authentication middleware
• EF Core query behavior changes
• Orleans grain activation patterns
• Serialization format changes
• Logging framework updates

Appendix C: Performance Benchmarks

Baseline (.NET 8):

• Memory usage: [TBD]
• Request throughput: [TBD]
• GC pause time: [TBD]

Target (.NET 10):

• Memory usage: [TBD] (10-20% reduction)
• Request throughput: [TBD] (5-15% improvement)
• GC pause time: [TBD] (significant reduction)

---

Document Version: 1.0 Last Updated: November 24, 2025 Authors: Development Team Reviewers: Architecture Team, DevOps Team