.NET 10 migration project

[playlend]

Migrating Harmony Core Projects to .NET 10

Harmony Core now targets .NET 10, building against EF Core 10 and ASP.NET Core 10. The
update also carries two dependency security fixes — SSH.NET 2026.0.0 and a MessagePack
≥ 2.5.301 floor — and two harmonycore CLI upgrade-flow fixes. What follows is a migration
guide for existing projects: each issue was hit in practice while migrating Harmony Core
itself and its sample projects, and error messages are quoted verbatim so they can be found
by searching.

Required versions

Component	Minimum version	Notes
.NET SDK	10.0.x
Harmony Core packages (Harmony.Core, .EF, .OData, .AspNetCore)	10.0.x	Built against EF Core 10 / ASP.NET Core 10
Synergex.SynergyDE.Build	26.8.1648	Older compilers crash importing EF Core 10 metadata (dblnet64 STATUS_STACK_OVERFLOW)
Synergex.SynergyDE.synrnt	12.4.1.1005
MSTest (test projects)	3.6.1	Needs the project properties described in Test projects
SSH.NET	2026.0.0	Security fix — GHSA-q939-rpr3-3284 (high) affects every version ≤ 2025.1.0, so 2026.0.0 is the first version that clears NuGet audit warnings; upgrade-latest stamps it

Important

Do not mix versions. A project targeting net10.0 that still references net8-era
Harmony packages builds cleanly and then fails on the first EF query at runtime with
System.TypeInitializationException. Upgrade the target framework and every package
together — harmonycore upgrade-latest does exactly that.

Tip

SSH.NET 2026.0.0 can be adopted early, while still on .NET 8 — it targets net8.0, and
the published 8.x Harmony.Core places no upper bound on it (>= 2024.1.0) — clearing the
NU1903 high-severity audit warnings that projects created from the 8.x templates produce.
The 8.x-era upgrade-latest will stamp it back down to its own pinned version (2025.0.0
today), so re-apply the bump if you run the old tool afterwards.

Recommended upgrade procedure

1. Install the .NET 10 SDK.

2. Run harmonycore upgrade-latest with the Harmony Core 10 release. This restamps
   TargetFramework to net10.0 and updates all package pins, including the Synergy compiler
   package, in every project.

   If you run this with the 8.x-era tool, it shows a spurious acknowledgment —
   ... requires you to regenerate from codegen template — even though 10.x is well past every
   regen boundary (the old tool compared version strings lexically, ranking 10.x below
   3.x/8.x). Answer YES and continue; you regenerate in the next step anyway. The 10.x
   tool fixes the comparison, so the prompt appears only for genuinely pre-boundary projects.

3. Run harmonycore regen -p to regenerate code from the current templates.

4. Rebuild and work through the compiler/code issues below — they only affect hand-written
   DBL code; generated code is already updated.

---

Compiler changes (Synergex.SynergyDE.Build 26.8.x)

The 26.8 compiler is stricter than 26.5. Three patterns that compiled before now error:

1. Unimplemented partial methods with output parameters

DBL-E-MISIMP: ... required since it has at least one output parameter

An optional (declaration-only) partial method may no longer have out/inout parameters.
Either implement the method, or change the parameter to in and have the caller pre-create the
object. Example from Harmony Core itself: AddCustomMimeTypes changed from
out provider, @FileExtensionContentTypeProvider to in with the caller constructing the
provider before the call.

2. Inline continued block lambdas

DBL-E-NOSPECL: inline lambda body expected

An &-continued begin ... end lambda body inline in an argument list is rejected. Use either
a single-line brace lambda — lambda(x) { x.DoThing().DoOther() } — or declare a named block
lambda on its own lines and pass it by name.

3. Stricter ambiguity checking

DBL-E-AMBSYM: Ambiguous symbol Format

Calls that resolve against multiple overloads (commonly string.Format with several arguments)
may now need an explicit cast to disambiguate, e.g. passing an (object[]) for the params
array.

---

Hand-written code: removed ASP.NET Core hosting APIs

.NET 10 removed the long-obsolete IHostingEnvironment family and its extension-method surface
from the Microsoft.AspNetCore.Hosting namespace. The generated Startup.dbl now declares the
environment as IWebHostEnvironment, whose IsDevelopment() / IsProduction() /
IsStaging() extensions live in the Microsoft.Extensions.Hosting namespace.

Custom code such as StartupCustom.dbl that calls these fails with:

DBL-E-NFND: %DBL-E-NFND, _env.IsDevelopment() not found

Fix: add one line to the file's imports:

import Microsoft.Extensions.Hosting

The import is harmless on .NET 8, so it can be added before migrating.

---

Custom authentication (JWT)

Harmony Core 10's code generator seeds default values for the JWT user tokens
(CUSTOM_JWT_ISSUER, CUSTOM_JWT_AUDIENCE, CUSTOM_JWT_GETKEY), so enabling
"CustomAuthentication": true now generates a working AuthenticationTools out of the box.
Previously (since early 2025), enabling it without manually defining those three tokens
produced an uncompilable project:

DBL-E-NFND: %DBL-E-NFND, AuthenticationTools.GetToken() not found

because the AuthenticationTools template was silently skipped while the controller that
calls it still generated. That defect is fixed in Harmony Core 10.

Warning

The default CUSTOM_JWT_GETKEY is a clearly-marked development-only signing key. Before
deploying, set your own values (via the UserTokens section of Harmony.Core.CodeGen.json
— user-defined tokens override the defaults) and follow the generated code's TODO about
sourcing the key from secure storage.

---

Test projects (MSTest / Microsoft.Testing.Platform)

MSTest 3.6+ brings in Microsoft.Testing.Platform, whose MSBuild targets generate entry-point
and extension-registration source files — in C#, VB, or F# only. Synergy test projects fail
with:

Microsoft.Testing.Platform.MSBuild.targets(...): error : Language 'Synergy' is not supported.

Fix: the project supplies its own main, so opt out in the .synproj:

<!-- test projects (MSTest-based, e.g. Services.Test): -->
<ProvidesMainMethod>true</ProvidesMainMethod>

<!-- executable helper projects that receive the packages transitively
     (e.g. Services.Test.GenerateValues) additionally need: -->
<GenerateTestingPlatformEntryPoint>False</GenerateTestingPlatformEntryPoint>
<GenerateSelfRegisteredExtensions>False</GenerateSelfRegisteredExtensions>

Projects scaffolded by harmonycore features --add-unit-tests from the Harmony Core 10
templates already contain these; test projects created earlier need them added by hand.

Additionally, a helper project that calls into the test project (such as
Services.Test.GenerateValues invoking AssemblyInitialize, whose signature uses MSTest's
TestContext) needs its own direct MSTest.TestFramework package reference. dblnet
resolves types that appear in a referenced project's public signatures only from the
consuming project's direct references — the transitive flow through the project reference is
not sufficient — so without it the compile fails with:

DBL-E-NVTREF: Cannot find Microsoft.VisualStudio.TestTools.UnitTesting.TestContext used in ...

This is a general rule worth remembering when a DBL-E-NVTREF names a type from a NuGet
package your project doesn't reference directly: add the package to the failing project.

---

Traditional unit tests: dotnet test with .elb containers

The .NET 10 SDK changed how dotnet test decides between "build a project" and "run a test
container": only a bare argument ending in .dll/.exe selects container (VSTest) mode.
The value of --test-adapter-path no longer counts (it did, accidentally, on .NET 8), so the
old invocation now tries to parse the .elb as a project file:

error MSB4025: The project file could not be loaded. Data at the root level is invalid.

Fix: pass the adapter DLL as an explicit additional argument (VSTest skips it as a test
source with an informational message):

dotnet test TestDir\TraditionalBridge.UnitTest.elb TestDir\SynergyTraditionalUnitTest.TestAdapter.dll --test-adapter-path TestDir

---

Handled inside Harmony Core 10 (no action needed, listed for awareness)

• EF Core 10 reworked its internal query pipeline (query parameters, IgnoreQueryFilters
  overloads, value-generation requirements, LINQ surface changes). Harmony Core's EF provider
  absorbs all of it — these appear as runtime failures only when net10 apps run against
  pre-10 Harmony packages.
• EF Core 10 changed metadata debug-string formats (e.g. navigations now include
  Required/Optional). Avoid asserting on ToString() of EF metadata in tests.
• Harmony.Core 10 packages floor MessagePack at 2.5.301: StreamJsonRpc 2.22.x otherwise
  pulls in 2.5.192, which carries advisories GHSA-vh6j-jc39-fggf / GHSA-2f33-pr97-265q — so
  those NuGet audit warnings disappear once on the 10.x packages.
• The 10.x CLI tool fixes two upgrade-flow defects: the lexical version comparison behind the
  spurious "requires you to regenerate" acknowledgment (see the upgrade procedure above), and
  its versions cache taking precedence over a cli-tool-versions.json placed next to the
  solution (the local file now always wins).