Upgrade to .NET 10, Aspire 13, and System.CommandLine 2.0 (#794)

### Summary & Motivation

Upgrade the codebase to .NET 10 and adopt new C# 14 language features.

- Update all projects to target .NET 10.
- Update to Aspire 13 and use `Aspire.Hosting.JavaScript` over the
deprecated `Aspire.Hosting.NodeJS`.
- Update Docker images to use secure chiseled base images:
`mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled-extra` for projects
using Entity Framework, and
`mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled` for AppGateway.
- Upgrade `System.CommandLine` to 2.0.0 and migrate from
`NamingConventionBinder` to the new `SetAction` API.
- Convert extension methods to C# 14 extension members syntax using
`extension(Type param)`.
- Update properties with backing fields to use the new `field` keyword.
- Remove `params` keyword from extension methods to avoid Roslyn
compiler errors
([dotnet/roslyn#80024](dotnet/roslyn#80024)).

### Downstream projects

Downstream projects must make the following changes to align with this
upgrade:

1. **Update all `*.csproj` files** to target .NET 10:
   ```diff
   - <TargetFramework>net9.0</TargetFramework>
   + <TargetFramework>net10.0</TargetFramework>
   ```

2. **Update all WebApp `.esproj` files** (e.g.,
`application/your-self-contained-system/WebApp/YourSystem.WebApp.esproj`):
   ```diff
   - <TargetFrameworkMoniker>net9.0</TargetFrameworkMoniker>
   + <TargetFrameworkMoniker>net10.0</TargetFrameworkMoniker>
   ```

3. **Update Dockerfiles** to use secure chiseled base images:
   - For API and Workers projects (that use Entity Framework):
     ```diff
     - FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine
     - RUN apk add --no-cache icu-libs
     - ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false
     + FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled-extra
     ```

4. **Remove WebApp `.esproj` references from AppHost** in
`application/AppHost/AppHost.csproj`:
   ```diff
- <ProjectReference
Include="..\your-self-contained-system\WebApp\YourSystem.WebApp.esproj"/>
   ```
With `Aspire.Hosting.JavaScript` using the new `AddJavaScriptApp()` over
`AddNpmApp()` eliminates the need for `.esproj` project references in
AppHost.

5. **Update
`application/your-self-contained-system/Tests/EndpointBaseTest.cs`** to
use the new `field` keyword for auto-implemented properties with backing
fields:
   ```diff
   - private ServiceProvider? _provider;

- protected ServiceProvider Provider => _provider ??=
Services.BuildServiceProvider();
+ protected ServiceProvider Provider => field ??=
Services.BuildServiceProvider();
   ```

   Also update the reference in `EndpointBaseTest` constructor:
   ```diff
   - using var serviceScope = Provider.CreateScope();
   + using var serviceScope = Provider!.CreateScope();
   ```

6. **Fix extension method calls in SharedKernel** that had the `params`
keyword removed due to [Roslyn issue
#80024](dotnet/roslyn#80024):
- Methods like `AddApiServices()`, `AddSharedInfrastructure()`,
`AddWorkerServices()`, and similar extension methods in SharedKernel no
longer use `params` for their assembly parameters.
- Update calls to pass arrays explicitly:
`services.AddApiServices([assembly1, assembly2])` instead of
`services.AddApiServices(assembly1, assembly2)`.
- Example from `application/your-self-contained-system/Api/Program.cs`:
     ```diff
- builder.Services.AddApiServices(Assembly.GetExecutingAssembly(),
typeof(Configuration).Assembly);
+ builder.Services.AddApiServices([Assembly.GetExecutingAssembly(),
typeof(Configuration).Assembly]);
     ```

7. **If you have a custom developer CLI**, update any custom commands to
use System.CommandLine 2.0.0 syntax:
- Replace `System.CommandLine.NamingConventionBinder` with
`System.CommandLine.Invocation`.
- Replace `Handler = CommandHandler.Create<...>(Execute)` with
`this.SetAction(parseResult => Execute(...))`.
- Update option definitions from inline construction to explicit
`Options.Add()` calls.
- See `developer-cli/Commands/CheckCommand.cs` for a complete example.

8. **Optional: Adopt C# 14 features:**
- Convert extension methods to use the new `extension(Type param)`
syntax (see
`application/shared-kernel/SharedKernel/ApiResults/ApiResultExtensions.cs`
for examples).
- Update properties with explicit backing fields to use the new `field`
keyword (see the `EndpointBaseTest.cs` change in step 5).

9. **Developers need to install .NET 10 SDK.** Aspire's AppHost
automatically handles SSL certificate creation and management when
running the application locally. If you encounter certificate-related
errors after upgrading, the AppHost will regenerate certificates
automatically on the next run.

### Checklist

- [x] I have added tests, or done manual regression tests
- [x] I have updated the documentation, if necessary

Author: tjementum

.cursor/rules/main.mdc

@@ -42,18 +42,18 @@ This is a mono repository with multiple self-contained systems (SCS), each being
 - [application](mdc:application): Contains application code:
   - [account-management](mdc:application/account-management): An SCS for tenant and user management:
     - [WebApp](mdc:application/account-management/WebApp): A React, TypeScript SPA.
-    - [Api](mdc:application/account-management/Api): .NET 9 minimal API.
-    - [Core](mdc:application/account-management/Core): .NET 9 Vertical Sliced Architecture.
+    - [Api](mdc:application/account-management/Api): .NET 10 minimal API.
+    - [Core](mdc:application/account-management/Core): .NET 10 Vertical Sliced Architecture.
     - [Workers](mdc:application/account-management/Workers): A .NET Console job.
     - [Tests](mdc:application/account-management/Tests): xUnit tests for backend.
   - [back-office](mdc:application/back-office): An empty SCS that will be used to create tools for Support and System Admins:
     - [WebApp](mdc:application/back-office/WebApp): A React, TypeScript SPA.
-    - [Api](mdc:application/back-office/Api): .NET 9 minimal API.
-    - [Core](mdc:application/back-office/Core): .NET 9 Vertical Sliced Architecture.
+    - [Api](mdc:application/back-office/Api): .NET 10 minimal API.
+    - [Core](mdc:application/back-office/Core): .NET 10 Vertical Sliced Architecture.
     - [Workers](mdc:application/back-office/Workers): A .NET Console job.
     - [Tests](mdc:application/back-office/Tests): xUnit tests for backend.
-  - [AppHost](mdc:application/AppHost): .NET Aspire project for orchestrating SCSs and Docker containers. Never run directly—typically running in watch mode.
-  - [AppGateway](mdc:application/AppGateway): Main entry point using .NET YARP as reverse proxy for all SCSs.
+  - [AppHost](mdc:application/AppHost): Aspire project for orchestrating SCSs and Docker containers. Never run directly—typically running in watch mode.
+  - [AppGateway](mdc:application/AppGateway): Main entry point using YARP as reverse proxy for all SCSs.
   - [shared-kernel](mdc:application/shared-kernel): Reusable .NET backend shared by all SCSs.
   - [shared-webapp](mdc:application/shared-webapp): Reusable frontend shared by all SCSs.
 - [cloud-infrastructure](mdc:cloud-infrastructure): Bash and Azure Bicep scripts (IaC).

.github/workflows/app-gateway.yml

@@ -118,7 +118,7 @@ jobs:
       - name: Setup .NET Core SDK
         uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: 9.0.x
+          global-json-file: application/global.json
 
       - name: Restore .NET Tools
         working-directory: application

.windsurf/rules/backend/commands.md

@@ -63,9 +63,7 @@ public sealed class CreateUserValidator : AbstractValidator<CreateUserCommand>
     public CreateUserValidator()
     {
         // ✅ DO: Use the same message for better user experience and easier localization
-        RuleFor(x => x.Name)
-            .NotEmpty().WithMessage("Name must be between 1 and 50 characters.")
-            .MaximumLength(50).WithMessage("Name must be between 1 and 50 characters.");
+        RuleFor(x => x.Name).Length(1, 50).WithMessage("Name must be between 1 and 50 characters.");
     }
 }
 
@@ -99,7 +97,7 @@ public sealed class CreateUserValidator : AbstractValidator<CreateUserCommand>
 {
     public CreateUserValidator()
     {
-        // ❌ DON'T: Use different validation messages for the same property
+        // ❌ DON'T: Use different validation messages for the same property and redundant validation rules
         RuleFor(x => x.Name)
             .NotEmpty().WithMessage("Name must not be empty.")
             .MaximumLength(50).WithMessage("Name must not be more than 50 characters.");

.windsurf/rules/main.md

@@ -42,18 +42,18 @@ This is a mono repository with multiple self-contained systems (SCS), each being
 - [application](/application): Contains application code:
   - [account-management](/application/account-management): An SCS for tenant and user management:
     - [WebApp](/application/account-management/WebApp): A React, TypeScript SPA.
-    - [Api](/application/account-management/Api): .NET 9 minimal API.
-    - [Core](/application/account-management/Core): .NET 9 Vertical Sliced Architecture.
+    - [Api](/application/account-management/Api): .NET 10 minimal API.
+    - [Core](/application/account-management/Core): .NET 10 Vertical Sliced Architecture.
     - [Workers](/application/account-management/Workers): A .NET Console job.
     - [Tests](/application/account-management/Tests): xUnit tests for backend.
   - [back-office](/application/back-office): An empty SCS that will be used to create tools for Support and System Admins:
     - [WebApp](/application/back-office/WebApp): A React, TypeScript SPA.
-    - [Api](/application/back-office/Api): .NET 9 minimal API.
-    - [Core](/application/back-office/Core): .NET 9 Vertical Sliced Architecture.
+    - [Api](/application/back-office/Api): .NET 10 minimal API.
+    - [Core](/application/back-office/Core): .NET 10 Vertical Sliced Architecture.
     - [Workers](/application/back-office/Workers): A .NET Console job.
     - [Tests](/application/back-office/Tests): xUnit tests for backend.
-  - [AppHost](/application/AppHost): .NET Aspire project for orchestrating SCSs and Docker containers. Never run directly—typically running in watch mode.
-  - [AppGateway](/application/AppGateway): Main entry point using .NET YARP as reverse proxy for all SCSs.
+  - [AppHost](/application/AppHost): Aspire project for orchestrating SCSs and Docker containers. Never run directly—typically running in watch mode.
+  - [AppGateway](/application/AppGateway): Main entry point using YARP as reverse proxy for all SCSs.
   - [shared-kernel](/application/shared-kernel): Reusable .NET backend shared by all SCSs.
   - [shared-webapp](/application/shared-webapp): Reusable frontend shared by all SCSs.
 - [cloud-infrastructure](/cloud-infrastructure): Bash and Azure Bicep scripts (IaC).

README.md

@@ -27,7 +27,7 @@ Built to demonstrate seamless flow—backend contracts feed a fully-typed React
 
 ## What's inside
 
-* **Backend** - .NET 9 and C# adhering to the principles of vertical slice architecture, DDD, CQRS, and clean code
+* **Backend** - .NET 10 and C# 14 adhering to the principles of vertical slice architecture, DDD, CQRS, and clean code
 * **Frontend** – React 19, TypeScript, TanStack Router & Query, React Aria for accessible and UI
 * **CI/CD** - GitHub actions for fast passwordless deployments of docker containers and infrastructure (Bicep)
 * **Infrastructure** - Cost efficient and scalable Azure PaaS services like Azure Container Apps, Azure SQL, etc.
@@ -59,7 +59,7 @@ For development, you need .NET, Docker, and Node. And GitHub and Azure CLI for s
 2.	From an Administrator PowerShell terminal, use [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (preinstalled on Windows 11) to install any missing packages:
 
     ```powershell
-    winget install Microsoft.DotNet.SDK.9
+    winget install Microsoft.DotNet.SDK.10
     winget install Git.Git
     winget install Docker.DockerDesktop
     winget install OpenJS.NodeJS
@@ -125,10 +125,10 @@ Open a terminal and run the following commands (if not installed):
   sudo apt-get update
   ```
 
-- Install .NET SDK 9.0, Node, GitHub CLI
+- Install .NET SDK 10.0, Node, GitHub CLI
 
   ```bash
-  sudo apt-get install -y dotnet-sdk-9.0 nodejs gh
+  sudo apt-get install -y dotnet-sdk-10.0 nodejs gh
   ```
 
 - Install Azure CLI
@@ -161,7 +161,7 @@ We recommend you keep the commit history, which serves as a great learning and t
 
 ## 2. Run the Aspire AppHost to spin up everything on localhost
 
-Using .NET Aspire, docker images with SQL Server, Blob Storage emulator, and development mail server will be downloaded and started. No need install anything, or learn complicated commands. Simply run this command, and everything just works 🎉
+Using Aspire, docker images with SQL Server, Blob Storage emulator, and development mail server will be downloaded and started. No need install anything, or learn complicated commands. Simply run this command, and everything just works 🎉
 
 ```bash
 cd application/AppHost
@@ -205,7 +205,7 @@ PlatformPlatform is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) contain
 ├─ .github               # Separate GitHub workflows for deploying Infrastructure and app
 ├─ .windsurf             # Copy of .cursor for Windsurf AI editor (synchronized by CLI)
 ├─ application           # Contains the application source code
-│  ├─ AppHost            # .NET Aspire project starting app and all dependencies in Docker
+│  ├─ AppHost            # Aspire project starting app and all dependencies in Docker
 │  ├─ AppGateway         # Main entry point for the app using YARP as a reverse proxy 
 │  ├─ account-management # Self-contained system with account sign-up, user management, etc.
 │  │   ├─ WebApp         # React SPA frontend using TypeScript and React Aria Components
@@ -233,12 +233,12 @@ PlatformPlatform is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) contain
 
 # Technologies
 
-### .NET 9 Backend With Vertical Sliced Architecture, DDD, CQRS, Minimal API, and Aspire
+### .NET 10 Backend With Vertical Sliced Architecture, DDD, CQRS, Minimal API, and Aspire
 
 The backend is built using the most popular, mature, and commonly used technologies in the .NET ecosystem:
 
-- [.NET 9](https://dotnet.microsoft.com) and [C# 13](https://learn.microsoft.com/en-us/dotnet/csharp/tour-of-csharp)
-- [.NET Aspire](https://aka.ms/dotnet-aspire)
+- [.NET 10](https://dotnet.microsoft.com) and [C# 14](https://learn.microsoft.com/en-us/dotnet/csharp/tour-of-csharp)
+- [Aspire](https://aka.ms/dotnet-aspire)
 - [YARP](https://microsoft.github.io/reverse-proxy)
 - [ASP.NET Minimal API](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis)
 - [Entity Framework](https://learn.microsoft.com/en-us/ef)

application/AppGateway/ApiAggregation/ApiAggregationEndpoints.cs

@@ -2,26 +2,29 @@ namespace PlatformPlatform.AppGateway.ApiAggregation;
 
 public static class Endpoints
 {
-    public static WebApplication ApiAggregationEndpoints(this WebApplication app)
+    extension(WebApplication app)
     {
-        app.MapGet("/swagger", context =>
-            {
-                context.Response.Redirect("/openapi/v1");
-                return Task.CompletedTask;
-            }
-        );
+        public WebApplication ApiAggregationEndpoints()
+        {
+            app.MapGet("/swagger", context =>
+                {
+                    context.Response.Redirect("/openapi/v1");
+                    return Task.CompletedTask;
+                }
+            );
 
-        app.MapGet("/openapi", context =>
-            {
-                context.Response.Redirect("/openapi/v1");
-                return Task.CompletedTask;
-            }
-        );
+            app.MapGet("/openapi", context =>
+                {
+                    context.Response.Redirect("/openapi/v1");
+                    return Task.CompletedTask;
+                }
+            );
 
-        app.MapGet("/openapi/v1.json", async (ApiAggregationService apiAggregationService)
-            => Results.Content(await apiAggregationService.GetAggregatedOpenApiJson(), "application/json")
-        ).CacheOutput(c => c.Expire(TimeSpan.FromMinutes(5)));
+            app.MapGet("/openapi/v1.json", async (ApiAggregationService apiAggregationService)
+                => Results.Content(await apiAggregationService.GetAggregatedOpenApiJson(), "application/json")
+            ).CacheOutput(c => c.Expire(TimeSpan.FromMinutes(5)));
 
-        return app;
+            return app;
+        }
     }
 }

application/AppGateway/AppGateway.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <AssemblyName>PlatformPlatform.AppGateway</AssemblyName>
         <RootNamespace>PlatformPlatform.AppGateway</RootNamespace>
         <Nullable>enable</Nullable>

application/AppGateway/Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled
 
 WORKDIR /app
 COPY ./AppGateway/publish .

application/AppGateway/Program.cs

@@ -36,7 +36,7 @@
     );
 }
 
-builder.AddNamedBlobStorages(("account-management-storage", "ACCOUNT_MANAGEMENT_STORAGE_URL"));
+builder.AddNamedBlobStorages([("account-management-storage", "ACCOUNT_MANAGEMENT_STORAGE_URL")]);
 
 builder.WebHost.UseKestrel(option => option.AddServerHeader = false);
 

application/AppHost/AppHost.csproj

@@ -1,30 +1,25 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-    <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2"/>
+<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
 
     <PropertyGroup>
         <OutputType>Exe</OutputType>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
         <UserSecretsId>platformplatform-f817f2a1-ac57-4756-aef2-a57ca864bbd3</UserSecretsId>
     </PropertyGroup>
 
     <ItemGroup>
         <ProjectReference Include="..\account-management\Api\AccountManagement.Api.csproj"/>
-        <ProjectReference Include="..\account-management\WebApp\AccountManagement.WebApp.esproj"/>
         <ProjectReference Include="..\account-management\Workers\AccountManagement.Workers.csproj"/>
         <ProjectReference Include="..\AppGateway\AppGateway.csproj"/>
         <ProjectReference Include="..\back-office\Api\BackOffice.Api.csproj"/>
-        <ProjectReference Include="..\back-office\WebApp\BackOffice.WebApp.esproj"/>
         <ProjectReference Include="..\back-office\Workers\BackOffice.Workers.csproj"/>
     </ItemGroup>
 
     <ItemGroup>
         <PackageReference Include="Aspire.Azure.Storage.Blobs"/>
-        <PackageReference Include="Aspire.Hosting.AppHost"/>
         <PackageReference Include="Aspire.Hosting.Azure.Storage"/>
-        <PackageReference Include="Aspire.Hosting.NodeJs"/>
+        <PackageReference Include="Aspire.Hosting.JavaScript"/>
         <PackageReference Include="Aspire.Hosting.SqlServer"/>
         <PackageReference Include="Microsoft.Extensions.Configuration"/>
         <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets"/>