Documentation

adrs/008-dotnet-9-adoption.md

ADR-008: .NET 9.0 with Latest C# Features

Status

Superseded by ADR-029: Migration to .NET 10 LTS

Context

The Dynaplex architecture requires a modern runtime and language features to support its microservices design, performance requirements, and developer productivity goals. We need to decide on the target framework version and language feature set for all components in the system.

Key considerations:

  • Performance improvements in newer .NET versions
  • Language features that improve code safety and expressiveness
  • Tooling and IDE support
  • Deployment target compatibility
  • Long-term support (LTS) vs current release trade-offs
  • Team familiarity with latest features

Decision

We will adopt .NET 9.0 as the target framework across all Dynaplex components with the C# language version set to "latest".

Implementation details:

  • All projects target <TargetFramework>net9.0</TargetFramework>
  • Language version set to <LangVersion>latest</LangVersion>
  • Nullable reference types enabled with <Nullable>enable</Nullable>
  • Implicit usings enabled for cleaner code
  • Enable latest analyzer rules for code quality

Consequences

Positive

  • Performance: .NET 9 offers significant performance improvements, especially for JSON serialization, LINQ, and async operations
  • Native AOT Support: Option for ahead-of-time compilation for reduced startup time and memory usage
  • Modern Language Features: Access to latest C# features including:
    • Primary constructors
    • Collection expressions
    • Improved pattern matching
    • Required members
    • File-scoped types
  • Enhanced Diagnostics: Better debugging and profiling tools
  • Improved Container Support: Optimized container images and better Docker integration
  • Source Generators: Better support for compile-time code generation (used in JSON serialization)

Negative

  • Deployment Requirements: All deployment targets must support .NET 9 runtime
  • No LTS: .NET 9 is not an LTS release (next LTS is .NET 10 in 2025)
  • Learning Curve: Developers need to familiarize themselves with new language features
  • Early Adoption Risks: Potential for framework bugs or breaking changes
  • Tooling Requirements: Requires latest Visual Studio 2022 or Rider versions
  • Third-party Compatibility: Some libraries may not yet support .NET 9

Neutral

  • Migration Path: Will need to plan migration to .NET 10 LTS when available
  • Feature Adoption: Teams can gradually adopt new language features
  • Backward Compatibility: Can still use older C# patterns where appropriate

Implementation Notes

Project Configuration

<PropertyGroup>
  <TargetFramework>net9.0</TargetFramework>
  <LangVersion>latest</LangVersion>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest</AnalysisLevel>
</PropertyGroup>

Key Features Being Used

  1. Source Generation: System.Text.Json source generation for performance
  2. Required Members: Ensuring proper initialization of DTOs
  3. File-scoped Namespaces: Reducing indentation and improving readability
  4. Global Usings: Centralized using statements for common namespaces
  5. Nullable Reference Types: Preventing null reference exceptions at compile time

Migration Considerations

  • Monitor .NET 10 LTS release schedule (November 2025)
  • Plan for upgrade during a maintenance window
  • Most code should be forward-compatible
  • Review breaking changes documentation before upgrading
  • ADR-007: Migration to .NET Aspire Microservices (requires modern .NET)
  • ADR-014: TypedResults for Type-Safe Responses (uses latest C# features)
  • ADR-021: Microsoft Kiota for API Client Generation (requires .NET 8+)
  • ADR-029: Migration to .NET 10 LTS (supersedes this ADR)