Managing Target Frameworks

Manage Project Target Frameworks

Related Skills

Defer to these skills for package versions, CPM, and property edits.

Workflow

Track progress using this checklist:

Task Progress:
- [ ] Step 1: Locate target framework property
- [ ] Step 2: Modify target frameworks
- [ ] Step 3: Restore and resolve errors
- [ ] Step 4: Apply conditional compilation (if needed)

Step 1: Locate the Target Framework Property

Before making changes, determine where the TargetFramework or TargetFrameworks property is defined. It may be in the project file, a Directory.Build.props, or another imported MSBuild file. Use the modifying-project-properties skill to locate and understand the property definition.

Step 2: Modify Target Frameworks

Determine the intended change from user context and apply the matching scenario:

Replace a TFM — swap the value in place; preserve the singular/plural property name:

<!-- Single-targeted: stays singular -->
<TargetFramework>OldTFM</TargetFramework>
<!-- After -->
<TargetFramework>NewTFM</TargetFramework>

<!-- Multi-targeted: replace only the specific TFM -->
<TargetFrameworks>OldTFM;OtherTFM</TargetFrameworks>
<!-- After -->
<TargetFrameworks>NewTFM;OtherTFM</TargetFrameworks>

Add multi-targeting — convert singular TargetFramework to plural TargetFrameworks and add the new TFM:

<!-- Before -->
<TargetFramework>ExistingTFM</TargetFramework>

<!-- After -->
<TargetFrameworks>ExistingTFM;NewTFM</TargetFrameworks>

Append to existing multi-targeted project — add the new TFM to the existing list:

<!-- Before -->
<TargetFrameworks>TFM1;TFM2</TargetFrameworks>

<!-- After -->
<TargetFrameworks>TFM1;TFM2;NewTFM</TargetFrameworks>

Remove a TFM — remove the TFM from the list; revert to singular TargetFramework if only one remains:

<!-- Multiple TFMs remain: stays plural -->
<TargetFrameworks>TFM1;TFM2;TFMToRemove</TargetFrameworks>
<!-- After -->
<TargetFrameworks>TFM1;TFM2</TargetFrameworks>

<!-- One TFM remains: revert to singular -->
<TargetFrameworks>TFM1;TFMToRemove</TargetFrameworks>
<!-- After -->
<TargetFramework>TFM1</TargetFramework>

Order TFMs newest to oldest when multiple TFMs are present — MSBuild uses the first TFM as the default for IDE operations and dotnet run, so the newest framework provides the best developer experience.

Step 3: Resolve Errors

Restore first and resolve all NUxxxx errors before building. Then build and resolve MSBxxxx/CSxxxx errors. Common multi-targeting errors:

Multi-targeting-specific pattern — use conditional package references when no single package version works for all TFMs:

<ItemGroup Condition="'$(TargetFramework)' == 'SpecificTFM'">
  <PackageReference Include="PackageName" />
</ItemGroup>

Step 4: Apply Conditional Compilation (If Needed)

Use #if directives only when APIs genuinely differ between TFMs. Not every difference needs conditionals — some just need a different overload or parameter. Overusing #if makes code harder to maintain and review.

Preprocessor symbol convention: MSBuild automatically defines preprocessor symbols for each target framework. The symbol name is the TFM with . replaced by _, uppercased (e.g., net10.0 → NET10_0, net48 → NET48, netstandard2.0 → NETSTANDARD2_0). These symbols do not need to be declared manually — they are available in any #if directive.

#if NET10_0_OR_GREATER
    // API available only in .NET 10+
#elif NETFRAMEWORK
    // .NET Framework fallback
#endif

Use _OR_GREATER suffix symbols (e.g., NET8_0_OR_GREATER) when the code applies to a minimum version rather than an exact version. Use NETFRAMEWORK for any .NET Framework target, NETSTANDARD for any .NET Standard target.

Anti-Patterns

• ❌ Using singular TargetFramework with multiple TFMs — MSBuild silently ignores all but the first value
• ❌ Wrapping every API call in #if when only some APIs differ — creates unmaintainable code with unnecessary divergence
• ❌ Stopping after the first TFM builds — each TFM can have different API surfaces, so verify all TFMs compile
• ❌ Editing the project file directly without checking if the property is inherited from Directory.Build.props — changes would be overridden by the import
• ❌ Converting TargetFramework to TargetFrameworks when only a TFM replacement was requested — changes build behavior unnecessarily
• ❌ Leaving TargetFrameworks (plural) when only one TFM remains — causes MSBuild to produce a TFM-specific output folder structure instead of a flat bin/ layout

Success Criteria

• TFM replaced in place without changing singular/plural when only a replacement was requested
• TargetFramework changed to TargetFrameworks (plural) when adding multi-targeting
• New TFM appended correctly when project already uses TargetFrameworks
• TargetFrameworks reverted to singular TargetFramework when only one TFM remains after removal
• TFMs semicolon-separated, newest to oldest
• #if directives only where APIs genuinely differ
• All TFMs build successfully

Resources

• Multi-targeting
• MSBuild Multi-targeting
• Target Frameworks