@nx/dotnet: expose structured evaluated MSBuild metadata and framework/RID-specific target variants

[Redth]

Description

Would the Nx team be open to extending the existing @nx/dotnet MSBuild analyzer so it exposes more of the evaluated project-system model and can represent framework/RID-specific task variants?

The current analyzer already has the right architecture: a thin Nx plugin invokes a C# analyzer that constructs an MSBuild ProjectGraph, evaluates project properties and items, and generates Nx targets with commands, inputs, outputs, caching, and dependencies.

I've have been prototyping an additive metadata layer in Redth/Maui.BuildHelpers/DotnetNx. That work started from cross-platform .NET and MAUI CI needs, but the useful concepts are general .NET project-system concepts rather than MAUI-specific behavior.

After comparing the prototype with Nx core and first-party inferred-task plugins, I think the upstream opportunity is narrower and more Nx-aligned than upstreaming the CLI wrapper, companion plugin, or Actions.

Proposed capabilities

1. Structured evaluated .NET metadata

Expose a stable, namespaced metadata model from the existing MSBuild evaluation, potentially under metadata.dotnet.

At project scope:

• Inferred Nx projectType when the analyzer can confidently distinguish an executable application from a library.
• Technologies such as .NET, project language, and detected SDK technologies.
• Capabilities including test, executable, packable, publishable, and tool.
• Package IDs where applicable.

Per evaluated target framework:

• Target framework short name.
• Framework identifier and version.
• Target platform identifier and version.
• Runtime identifier(s).
• Configuration-specific capabilities.
• Provenance for explicit versus inferred values.

The intent is not to mirror every MSBuild property. It is to expose a small model that affects how projects and tasks are understood by Nx.

This must come from evaluated MSBuild state rather than XML parsing so SDK defaults, imports, Directory.Build.props, conditions, and inner builds are handled correctly.

2. Keep capabilities aligned with Nx targets

Facts such as “testable,” “packable,” “publishable,” and “runnable” are overlapping capabilities rather than mutually exclusive project types.

The generated targets should remain authoritative:

• A test target represents testability.
• A pack target represents packaging.
• A publish target represents publication/deployment preparation.
• A run target represents executability.

Structured metadata can make those evaluated facts inspectable, while projectType remains limited to Nx’s native application/library distinction.

Note: I am not proposing automatically generating broad type:* tags for these facts.

3. Framework- and RID-specific target configurations

Multi-targeted projects expose a correctness issue that project-level metadata alone cannot solve.

For example, a project targeting both iOS and Windows may have no host capable of running an unqualified dotnet build across every target framework. Treating it as independently “macOS-compatible” and “Windows-compatible” at project scope is misleading.

Where command semantics are known, @nx/dotnet could represent framework/RID variants as Nx target configurations or generated target variants:

build
build:net10.0
build:net10.0-ios
publish:net10.0-ios:ios-arm64

The exact naming is open for discussion. The important part is that each variant has correct:

• Command arguments.
• Inputs and outputs.
• Cache identity.
• Dependencies.
• Target framework and runtime identifier metadata.

Debug/Release should continue to use normal Nx target configurations rather than tags.

4. Explicit tags from evaluated MSBuild

Some repositories intentionally keep project taxonomy in Directory.Build.props and project files. It may be useful for the analyzer to support explicit Nx tags supplied through evaluated MSBuild properties/items:

<PropertyGroup>
  <NxTags>scope:client;owner:devflow</NxTags>
</PropertyGroup>

<ItemGroup>
  <NxTag Include="requires:emulator"
         Condition="'$(TargetFramework)' == 'net10.0-android'" />
</ItemGroup>

A conditioned value should remain associated with that framework configuration. It should only be promoted to a project-wide tag when it applies to every evaluated configuration.

This keeps tags developer-authored and suitable for architecture/boundary rules.

5. Optional selector projection

Nx project selection can filter arbitrary dimensions through tags, while custom metadata is primarily inspectable. There may therefore be value in an opt-in projection of a small allow-list of metadata dimensions into namespaced selector tags:

dotnet:tfm:net10.0-ios
dotnet:platform:ios
dotnet:rid:ios-arm64

I wouldn't enable this by default, and would avoid high-cardinality projections such as package IDs or every evaluated property.

This portion may be better left to a companion plugin if inferred tags do not fit first-party plugin conventions. The structured metadata is independently useful.

Host and environment requirements

Cross-platform repositories also need to route tasks to compatible agents, but a target framework alone cannot prove that a task is runnable in an environment.

Host requirements vary by target:

• Build may support some cross-targeting.
• Test and run may require a runtime, device, or emulator.
• Publish may require an RID, native toolchain, signing, or packaging support.
• Any operation may require workloads or SDKs not installed on a runner.

Because of this, I would not propose a project-wide “buildable on OS” flag inferred solely from TFMs, since there's just too many factors to make the right inference from.

A future model could expose explicit target/configuration requirements or executor constraints. Until Nx has such a concept, this information can remain namespaced target metadata consumed by CI tooling. Inference should be clearly advisory and retain its provenance.

Motivation

Cross-platform .NET repositories repeatedly need to answer:

• Which frameworks and runtime identifiers does this affected project contain?
• Which affected task variant is valid on this agent?
• Which projects expose test, run, pack, or publish capabilities?
• Which outputs belong to a framework/RID-specific invocation?
• Which metadata came from an explicit repository decision versus analyzer inference?

These facts already exist in evaluated MSBuild state. Exposing them through @nx/dotnet avoids parallel XML parsing and lets Nx model task variants more accurately.

.NET MAUI is one example because a single workspace commonly contains Android, Apple, Windows, test, tool, package, and platform-neutral projects. The proposal is not MAUI-specific and should not special-case MAUI.

Non-goals

This proposal does not ask Nx to adopt:

• The nxdn CLI wrapper.
• The @redth/dotnet-nx companion plugin.
• Any GitHub Actions or CI matrix generation.
• Automatic installation or detection of workloads, devices, signing assets, or native toolchains.
• A tag for every MSBuild property.
• Any MAUI-specific task behavior.

Prior implementation and lessons

The current prototype demonstrates:

• MSBuild-evaluated per-framework metadata.
• Runtime identifiers and capability data.
• Explicit versus inferred provenance.
• Configuration-scoped explicit tags.
• Target-specific host requirements.
• Intersection semantics before lifting host compatibility to project scope.
• Optional, namespaced selector-tag projection.

It also helped identify approaches I no longer recommend:

• Flattening conditional framework facts into project-wide tags.
• Treating test/package/tool capabilities as exclusive project types.
• Inferring project-wide OS compatibility by unioning target-framework hosts.
• Using tags as the source of truth for target behavior.

This could be split into smaller contributions against the existing analyzer. If you're all open to this, I could split it into:

• structured metadata model
• projectType/technology improvements
• framework/RID-specific target configuration design

[Redth]

I have opened the proposed work as small draft contributions for design review:

• feat(dotnet): infer project type and SDK technologies #36679 - native projectType and stable SDK technology metadata
• feat(dotnet): add structured metadata.dotnet with per-TFM capabilities #36678 - structured evaluated metadata.dotnet with per-TFM/RID facts and capabilities
• feat(dotnet): add evaluated MSBuild project tags #36677 - explicit developer-authored NxTags/NxTag values from evaluated MSBuild
• feat(dotnet): opt-in per-target-framework target variants for multi-targeted projects #36680 - opt-in, self-contained per-TFM build variants
• feat(dotnet): opt-in per-runtime-identifier target variants for multi-targeted executables #36681 - opt-in per-RID release-build/publish variants (conceptually stacked on feat(dotnet): opt-in per-target-framework target variants for multi-targeted projects #36680; review its final two commits as the RID delta)

The first four are independent against master. The RID draft builds on the TFM-variant design. Each PR deliberately excludes the other areas so maintainers can review or accept them separately.

[jaysoo]

Thanks, I've tagged @AgentEnder to take a look.

Do you have a ranking of the five items in terms of priorities so we can take that into consideration? Or do they all need to move as a whole?

[Redth]

They don't necessarily all need to move together but they all bring the dotnet integration to a level that's much more useful in general.

The three in draft (two of which are stacked together) are probably the most interesting in terms of being able to leverage nx in more complex scenarios, but may require some more discussion and shaping...

#36677, #36678, #36679 are all a bit more self-contained and just add some niceties independently, so maybe those are the easiest to look at first?

[AgentEnder]

Hey @Redth, thanks for putting this together, and for splitting it up the way you did. Five scoped PRs with the design written out separately made this genuinely reviewable, which is not what usually happens with a change this size. We want all of it.

Three are close. The variant work is the right idea, and we've settled the open design questions on our side so you're not left guessing.

Verdicts

• feat(dotnet): add evaluated MSBuild project tags #36677, NxTags - yes. Intersecting across inner builds before promoting is the right rule.
• feat(dotnet): add structured metadata.dotnet with per-TFM capabilities #36678, metadata.dotnet - yes, two changes. Types move to @nx/dotnet, and drop the project-level capabilities aggregate.
• feat(dotnet): infer project type and SDK technologies #36679, projectType - yes.
• feat(dotnet): infer project type and SDK technologies #36679, technologies - drop this half. metadata.technologies is keyed to an icon map and core branches on specific values, so unknown strings render as grey placeholder boxes. That isn't documented anywhere, so this one's on us rather than you.
• feat(dotnet): opt-in per-target-framework target variants for multi-targeted projects #36680 / feat(dotnet): opt-in per-runtime-identifier target variants for multi-targeted executables #36681, variants - yes to the concept, with rework.

Discrete feedback is on each PR.

One correction to the framing: there's more precedent here than your writeup assumes. @nx/maven already emits structured metadata and maven:<groupId> tags by default, so both are established for us. Item 5 held back further than it needed to. Namespaced, low-cardinality derived tags (dotnet:sdk:*, dotnet:tfm:*) are in scope, and they're the better home for the SDK identity from #36679.

Variants: your first instinct was right

build:net10.0 was correct, and the reason you moved away from it doesn't hold. The #35837 ambiguity warning only fires when the alternate parse's configuration genuinely exists. build has debug and release, not net10.0-ios, so app:build:net10.0-ios resolves to exactly one interpretation. #35837 was a real report precisely because release is a configuration name.

What we settled:

• TFM and RID are targets, Debug/Release stays a configuration. Inputs can't vary by configuration at all, and per-TFM inputs are the main prize here. Platforms/iOS/** shouldn't invalidate the Android build.
• Separator is :. Not --, which means "atomized shard" everywhere else in Nx.
• Drop build-<tfm>-release. The variant already carries a release configuration.
• build becomes an nx:noop aggregate over the TFM variants, so nx affected -t build fans out and CI doesn't enumerate anything. RID variants stay out of it.
• No host inference, and you were right to refuse it. There's a mechanical reason now: the project config hash folds in every target on the project, so varying the target set by host would split the cache for every task on that project, not just the variants.
• tfmVariants and ridVariants, default on for multi-targeted projects.
• We'll add a core variantOf marker. That one's ours, not yours.

Sequencing, and an offer

#36680 needs targetGroups in the analyzer, which #36527 introduces and we haven't reviewed yet. That's on us, and we're picking it up first.

Also worth saying plainly: this is more rework than you signed up for, particularly on #36680. If you'd rather not carry it, we're happy to take those two on ourselves with you credited. The design is yours either way. Whichever you prefer is fine by us.

On host and environment requirements

A future model could expose explicit target/configuration requirements or executor constraints. Until Nx has such a concept, this information can remain namespaced target metadata consumed by CI tooling.

Our posture is Nx Cloud plus agents, with assignment rules routing targets to the right resource class by target name or glob. Docs: https://nx.dev/docs/kb/assignment-rules

That answer only works because of #36680 and #36681. Assignment rules match on target name, so without per-TFM targets there's nothing to route. The variants aren't just a caching improvement for us, they're the prerequisite for the routing story.

And a heads up: if this is for MAUI or another OSS project, we offer Nx Cloud free for qualifying open source projects. Worth pursuing.