Skip to content

ADR-0102: Framework support policy for the .NET 11 wave

Field Value
Status Accepted
Date 2026-11-13
Deciders ConnectSoft Architecture Team (owner decisions during the .NET 11 wave)
Supersedes -

Context

.NET 11.0.0 and SDK 11.0.100 were released, and .NET 8 and .NET 9 reached end of support on 2026-11-10. ConnectSoft maintains a large estate that has to move together:

  • the ConnectSoft.Extensions.* libraries (six dependency levels) and the other libraries,
  • the library templates, ConnectSoft.BaseTemplate and the templates derived from it,
  • the DerechHaLev estate (nine services, the Blazor shell and the E2E solution).

The libraries that were promoted first started to require Microsoft.Extensions.* >= 11.0.0. From that moment a consumer that still pins the 10.0.x runtime family fails restore with NU1605 (package downgrade), even when the consumer itself targets net10.0. The upgrade order and the package version shape are therefore not free choices. They follow from the package band, which is explained in Upgrade order and promotion levels.

The estate also needed answers for several smaller questions: which target frameworks libraries and templates support, how a template generates a single-target project, what happens to templates that copy the base template unchanged, which packages must stay on their current version, and how far MAUI can be claimed to work.

Decision

1. Dropped and supported frameworks

  1. net8.0 and net9.0 are dropped as library targets. They are end of support and are not offered by any template.
  2. Libraries (ConnectSoft.Extensions.* and the other libraries) multi-target net10.0;net11.0.

2. Package version shapes

  1. Runtime-family packages (Microsoft.Extensions.* core packages and System.*) use one plain 11.0.0 line in Directory.Packages.props. A net10.0 consumer uses 11.0.0 as well, because promoted libraries require Microsoft.Extensions.* >= 11.0.0.
  2. Packages whose 11.x release is net11-only (ASP.NET Core, EF Core, HealthChecks, Localization, SignalR, JSInterop) use two inline per-TFM PackageVersion lines: net10.0 resolves to 10.0.15 and every other framework resolves to 11.0.0.
  3. No band ItemGroup blocks. Version bands are not expressed as separate item groups. A package has either one plain line or the two inline per-TFM lines described above.

The per-TFM condition always compares against the literal net10.0 (== 'net10.0' gives 10.0.15, != 'net10.0' gives 11.0.0). See the traps in Upgrade order and promotion levels for why a literal net11.0 must not be used in a condition.

3. Template Framework choice and its exceptions

  1. Templates expose a Framework choice net10.0 | net11.0 with default net11.0. Generated projects are single-target.
  2. Switch symbols make the Docker images (dotnet/sdk: and dotnet/aspnet: tags), the pipeline SDK ('11.0.x') and global.json follow the choice.
  3. In ConnectSoft.BaseTemplate the source literal is net11.0 and Framework declares replaces: net11.0. The Blazor, Marketing and MAUI templates keep the source literal net10.0 with replaces: net10.0 and default net11.0.
  4. The option name is --Framework for BaseTemplate-derived templates.
  5. Exception - copyOnly-base templates. Templates that copy base-template/** unchanged (ConnectSoft.AI.SoftwareFactory.AgentTemplate and ConnectSoft.MicroserviceTemplate) are net11.0 only. The net10.0 choice is removed at pack time. A template that mixes a net10.0 copy of the base with other projects fails restore with NU1201 (project targets a framework that the referenced project does not support), so a choice that cannot work is not offered.
  6. Library templates (LibraryTemplate, ApiLibraryTemplate, AISkillsLibraryTemplate) generate libraries that multi-target net10.0;net11.0; their Framework parameter only selects the primary moniker.

4. DerechHaLev estate

The nine services, the Blazor shell and the E2E solution target a single net11.0. There is no multi-targeting in the estate. Docker images use the 11.0 tags, pipelines use dotnetVersion: '11.0.x', and the IIS deployment checks the installed runtime through requiredAspNetCoreRuntime, which expects Microsoft.AspNetCore.App 11.. The .NET 11 Hosting Bundle must be installed on a server before the first deployment of an 11.0 build.

5. Package holds

Package Decision Reason
Microsoft.OpenApi Stays 2.7.5 Swashbuckle 11 requires OpenApi 3.x.
Swashbuckle.AspNetCore Stays 10.3.1 See the hold explanation below.
AutoMapper 17.0.0 with ConnectSoft.Extensions.ObjectMapping.AutoMapper 1.0.26 AutoMapper is commercial from v15. Majors are taken only where the licence wiring exists.
IdentityModel Stays 5.2.0 Held at the current major.
KubernetesClient 17.0.14 Required by HealthChecks.UI 9.
Asyncify Pinned Held at the current version.
SixLabors.ImageSharp 3.1.12 Version 3.2 needs a licence key.

The Swashbuckle and OpenApi hold. Swashbuckle 11 requires Microsoft.OpenApi 3.x. The latest ServiceModel.Grpc.AspNetCore.Swashbuckle (1.26.0) throws MissingMethodException against OpenApi 3, which would make the gRPC Swagger document return HTTP 500. The estate therefore stays on Microsoft.OpenApi 2.7.5 and Swashbuckle 10.3.1. The hold is revisited when that package ships a build for OpenApi 3.

Related package-level notes that came out of the wave:

  • Microsoft.Extensions.Http.Resilience 11 marks the retry-budget options experimental (EXTEXP0001). Projects where the options validator generator trips use NoWarn EXTEXP0001.
  • Orleans 10.4.2 added IManagementGrain.DeactivateGrain(GrainId, CancellationToken), so test fakes of that interface need the new member.
  • A net10.0 web project that references Microsoft.Extensions.Logging.Abstractions 11 gets two LoggerMessage generators (CS0757). A Directory.Build.targets target named RemoveReferencePackLoggerMessageGenerator removes the duplicate.

6. StyleCop.Analyzers 1.3.180

StyleCop.Analyzers moves to 1.3.180. It reports SA1000 (new () and SA1206 (required public) differently from 1.1.118, and the code was fixed accordingly. Promoted libraries leak a dependency on StyleCop 1.3.180 or later, so consuming repositories pin >= 1.3.180 as well.

7. MAUI caveat

ConnectSoft.MauiBaseTemplate and ConnectSoft.Maui.UIKit gained net11.0 mobile targets, with MAUI 10.0.80 for net10.0 and 11.0.10 for net11.0. The net11.0 mobile builds are unverified: only preview workloads were available when the wave ran. Microsoft.Maui.Controls.Compatibility has no stable 11 release. Until stable MAUI 11 workloads are available, the net11.0 mobile targets must not be described as verified.

Alternatives considered

Option Outcome
Keep net8.0;net9.0;net10.0 for libraries Rejected. Both older runtimes are end of support, and keeping their targets would keep the older package families in every library.
Libraries net11.0 only Rejected. It would force every consumer to move to .NET 11 at once and remove the option to stay on net10.0 (LTS).
Version band ItemGroup blocks Rejected. They duplicate every package line per band and drift. Inline per-TFM lines keep the decision next to the package.
One Framework choice for every template Rejected for copyOnly-base templates because mixed target frameworks fail restore (NU1201).
Move to Swashbuckle 11 now Rejected because the gRPC Swagger integration would return HTTP 500.

Consequences

  • Consumers that stay on net10.0 still need the 11.0.0 runtime-family packages. A net10.0 project that references promoted libraries must not pin Microsoft.Extensions.* at 10.0.x.
  • The strict dependency order described in Upgrade order and promotion levels is mandatory. A consumer can only move after its producers are promoted.
  • Template documentation, generated Dockerfiles, pipelines and global.json files follow the Framework choice. Pages that describe a template parameter must be regenerated when the manifest changes (see the template documentation tooling under tools/template-docs).
  • CI agents need both the 10.x and the 11.x SDK where a net10.0 generation or test host is required.
  • The OpenApi and Swashbuckle hold, the AutoMapper licence boundary, the ImageSharp licence boundary and the MAUI caveat are explicit exceptions that must be revisited, not forgotten.
  • The DerechHaLev estate has one framework to test and deploy, which removes a whole class of multi-target problems for the estate at the cost of requiring the .NET 11 Hosting Bundle on every server.