Property Patterns

by dotnet0608d8924cd3MIT5.5K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Diagnose and fix concrete MSBuild property defects in projects and existing shared-file hierarchies. USE FOR: conditions, defaults, append versus overwrite, last-write-wins values, OS/TFM checks, portable paths, normalization, and reviews centered on those property defects. Property defects in Directory.Build.* remain in scope, including overwritten values across parent/child imports and conditions that run before TargetFramework is set, even when the fix changes import order or moves a property group to .targets. DO NOT USE FOR: placement-only or import-only requests with no concrete property defect, such as discovering shared files or choosing which file owns a target or customization (use directory-build-organization); item operations; target structure; broad reviews without a concrete property defect; non-MSBuild work.

Instructions onlySoftware Development

AI-generated overview

Reference patterns for diagnosing and fixing MSBuild property defects in project and shared build files.

What it does: This skill supplies canonical MSBuild property patterns covering conditional defaults, nested conditional groups, semicolon composition, path normalization, target framework and OS detection, guard properties, feature gating, fallback chains, and evaluation order. It is used to diagnose and fix concrete property defects such as overwritten values, missing conditions, and non-portable paths in projects and shared-file hierarchies. It produces corrected property definitions and guidance rather than files or scripts.
When to use it: Use it when a project or shared build file has a concrete MSBuild property defect, such as a default that cannot be overridden, an appended list that overwrites prior values, or a path that breaks portability. It also applies to reviews centered on such property defects, including defects in Directory.Build files. It is not for placement-only or import-only questions, item operations, or target structure.
Requirements: No scripts or tooling are required; it is instructions only. The work concerns MSBuild project and shared build files, so an MSBuild-based project context is implied.

MSBuild Property Patterns

Canonical property definition and manipulation patterns from the MSBuild repository.

Conditional Defaults — The Foundational Pattern

Set a property only if not already set, allowing callers to override:

xml

<PropertyGroup>  <Configuration Condition="'$(Configuration)' == ''">Debug</Configuration>  <Platform Condition="'$(Platform)' == ''">AnyCPU</Platform>  <BuildInParallel Condition="'$(BuildInParallel)' == ''">true</BuildInParallel></PropertyGroup>

<PropertyGroup>  <Configuration Condition="'$(Configuration)' == ''">Debug</Configuration>  <Platform Condition="'$(Platform)' == ''">AnyCPU</Platform>  <BuildInParallel Condition="'$(BuildInParallel)' == ''">true</BuildInParallel></PropertyGroup>

Rules

Always quote both sides: '$(Prop)' == ''
In .props: creates overridable defaults. In .targets: creates fallbacks.
Properties without the condition cannot be overridden by earlier imports.

Nested Conditional Groups

Group related properties under a shared condition:

xml

<PropertyGroup Condition="$(TargetFramework.StartsWith('net4'))">  <DefineConstants>$(DefineConstants);FEATURE_APARTMENT_STATE</DefineConstants>  <DefineConstants>$(DefineConstants);FEATURE_APM</DefineConstants>  <FeatureAppDomain>true</FeatureAppDomain></PropertyGroup>
<PropertyGroup Condition="'$([MSBuild]::GetTargetFrameworkIdentifier('$(TargetFramework)'))' == '.NETCoreApp'">  <NetCoreBuild>true</NetCoreBuild>  <DefineConstants>$(DefineConstants);RUNTIME_TYPE_NETCORE</DefineConstants></PropertyGroup>

<PropertyGroup Condition="$(TargetFramework.StartsWith('net4'))">  <DefineConstants>$(DefineConstants);FEATURE_APARTMENT_STATE</DefineConstants>  <DefineConstants>$(DefineConstants);FEATURE_APM</DefineConstants>  <FeatureAppDomain>true</FeatureAppDomain></PropertyGroup>
<PropertyGroup Condition="'$([MSBuild]::GetTargetFrameworkIdentifier('$(TargetFramework)'))' == '.NETCoreApp'">  <NetCoreBuild>true</NetCoreBuild>  <DefineConstants>$(DefineConstants);RUNTIME_TYPE_NETCORE</DefineConstants></PropertyGroup>

Use the outer Condition on PropertyGroup to avoid repeating the same condition on every property.

Warning: $(TargetFramework) is empty in .props files for single-targeting projects until the project body is evaluated. Place TargetFramework-conditioned property groups in .targets files (or the project file itself), where the value is always available.

Composition — Semicolon Concatenation

Properties that hold lists use semicolons. Always include the existing value when appending:

xml

<PropertyGroup>  <DefineConstants>$(DefineConstants);MY_FEATURE</DefineConstants>  <NoWarn>$(NoWarn);NU5131;IDE0005</NoWarn>  <LibraryTargetFrameworks>$(FullFrameworkTFM);$(LatestDotNetCoreForMSBuild);netstandard2.0</LibraryTargetFrameworks></PropertyGroup>

<PropertyGroup>  <DefineConstants>$(DefineConstants);MY_FEATURE</DefineConstants>  <NoWarn>$(NoWarn);NU5131;IDE0005</NoWarn>  <LibraryTargetFrameworks>$(FullFrameworkTFM);$(LatestDotNetCoreForMSBuild);netstandard2.0</LibraryTargetFrameworks></PropertyGroup>

Path Normalization and Trailing Slashes

xml

<!-- Ensure trailing slash on directories --><PropertyGroup>  <OutDir Condition="'$(OutDir)' != '' and !HasTrailingSlash('$(OutDir)')">$(OutDir)\</OutDir></PropertyGroup>
<!-- Normalize paths for cross-platform --><PropertyGroup>  <TargetRefPath>$([MSBuild]::NormalizePath('$(TargetDir)', 'ref', '$(TargetFileName)'))</TargetRefPath></PropertyGroup>
<!-- Make relative path absolute --><PropertyGroup>  <MSBuildProjectExtensionsPath      Condition="'$([System.IO.Path]::IsPathRooted('$(MSBuildProjectExtensionsPath)'))' == 'false'">    $([System.IO.Path]::Combine('$(MSBuildProjectDirectory)', '$(MSBuildProjectExtensionsPath)'))  </MSBuildProjectExtensionsPath></PropertyGroup>

<!-- Ensure trailing slash on directories --><PropertyGroup>  <OutDir Condition="'$(OutDir)' != '' and !HasTrailingSlash('$(OutDir)')">$(OutDir)\</OutDir></PropertyGroup>
<!-- Normalize paths for cross-platform --><PropertyGroup>  <TargetRefPath>$([MSBuild]::NormalizePath('$(TargetDir)', 'ref', '$(TargetFileName)'))</TargetRefPath></PropertyGroup>
<!-- Make relative path absolute --><PropertyGroup>  <MSBuildProjectExtensionsPath      Condition="'$([System.IO.Path]::IsPathRooted('$(MSBuildProjectExtensionsPath)'))' == 'false'">    $([System.IO.Path]::Combine('$(MSBuildProjectDirectory)', '$(MSBuildProjectExtensionsPath)'))  </MSBuildProjectExtensionsPath></PropertyGroup>

Preferred path functions

Function	Purpose
`$([MSBuild]::NormalizePath(...))`	Combine and normalize (cross-platform)
`$([System.IO.Path]::Combine(...))`	Combine path segments
`$([System.IO.Path]::IsPathRooted(...))`	Check if absolute
`HasTrailingSlash(...)`	Check for trailing slash
`$([MSBuild]::GetDirectoryNameOfFileAbove(...))`	Walk up directory tree
`$(MSBuildThisFileDirectory)`	Directory of current file

Target Framework Detection Helpers

xml

<!-- Get TFM identifier --><PropertyGroup Condition="'$([MSBuild]::GetTargetFrameworkIdentifier('$(TargetFramework)'))' == '.NETCoreApp'">  <NetCoreBuild>true</NetCoreBuild></PropertyGroup>
<!-- Check TFM compatibility --><PropertyGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net472'))">  <UseFrozenVersions>true</UseFrozenVersions></PropertyGroup>
<!-- OS detection --><PropertyGroup Condition="$([MSBuild]::IsOSPlatform('windows'))">  <DefineConstants>$(DefineConstants);TEST_ISWINDOWS</DefineConstants></PropertyGroup>

<!-- Get TFM identifier --><PropertyGroup Condition="'$([MSBuild]::GetTargetFrameworkIdentifier('$(TargetFramework)'))' == '.NETCoreApp'">  <NetCoreBuild>true</NetCoreBuild></PropertyGroup>
<!-- Check TFM compatibility --><PropertyGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net472'))">  <UseFrozenVersions>true</UseFrozenVersions></PropertyGroup>
<!-- OS detection --><PropertyGroup Condition="$([MSBuild]::IsOSPlatform('windows'))">  <DefineConstants>$(DefineConstants);TEST_ISWINDOWS</DefineConstants></PropertyGroup>

Guard Properties

Mark that a file has been imported to prevent double-imports:

xml

<!-- At the end of MySDK.props --><PropertyGroup>  <MySDKPropsImported>true</MySDKPropsImported></PropertyGroup>
<!-- At the top of MySDK.targets --><Import Project="MySDK.props" Condition="'$(MySDKPropsImported)' != 'true'" />

<!-- At the end of MySDK.props --><PropertyGroup>  <MySDKPropsImported>true</MySDKPropsImported></PropertyGroup>
<!-- At the top of MySDK.targets --><Import Project="MySDK.props" Condition="'$(MySDKPropsImported)' != 'true'" />

Feature Gating by MSBuild Version

xml

<PropertyGroup Condition="$([MSBuild]::AreFeaturesEnabled('17.10'))">  <UseNewBehavior>true</UseNewBehavior></PropertyGroup>

<PropertyGroup Condition="$([MSBuild]::AreFeaturesEnabled('17.10'))">  <UseNewBehavior>true</UseNewBehavior></PropertyGroup>

Fallback Chains

Set via primary source first, then fall back:

xml

<PropertyGroup>  <TlbExpPath>$([Microsoft.Build.Utilities.ToolLocationHelper]::GetPathToDotNetFrameworkSdkFile('tlbexp.exe'))</TlbExpPath>  <TlbExpPath Condition="'$(TlbExpPath)' == ''">$(_NetFxToolsDir)TlbExp.exe</TlbExpPath></PropertyGroup>

<PropertyGroup>  <TlbExpPath>$([Microsoft.Build.Utilities.ToolLocationHelper]::GetPathToDotNetFrameworkSdkFile('tlbexp.exe'))</TlbExpPath>  <TlbExpPath Condition="'$(TlbExpPath)' == ''">$(_NetFxToolsDir)TlbExp.exe</TlbExpPath></PropertyGroup>

Last Write Wins — Evaluation Order

MSBuild evaluates properties top-to-bottom. The last assignment wins:

xml

<!-- File 1 (imported first) --><MyProp>value1</MyProp>        <!-- set to value1 --><!-- File 2 (imported second) --><MyProp>value2</MyProp>        <!-- overwritten to value2 --><!-- File 3 (imported third) --><MyProp Condition="'$(MyProp)' == ''">value3</MyProp>  <!-- NOT set — already value2 -->

<!-- File 1 (imported first) --><MyProp>value1</MyProp>        <!-- set to value1 --><!-- File 2 (imported second) --><MyProp>value2</MyProp>        <!-- overwritten to value2 --><!-- File 3 (imported third) --><MyProp Condition="'$(MyProp)' == ''">value3</MyProp>  <!-- NOT set — already value2 -->

Properties in .targets (imported late) override properties in .props (imported early) and the project file.

Common Pitfalls

Unquoted conditions ($(X)==true) fail when the property is empty. Always quote both sides.
Overwriting DefineConstants (<DefineConstants>MY_CONST</DefineConstants>) drops all prior constants. Always append with $(DefineConstants);.
Hardcoded absolute paths break portability. Use $(MSBuildThisFileDirectory) or $([MSBuild]::NormalizePath(...)).
Missing Condition on defaults makes properties non-overridable. Add Condition="'$(Prop)' == ''" for values meant to be defaults.

Source and attribution

Source:dotnet/skillsinplugins/dotnet-msbuild/skills/property-patternsat commit0608d89

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Property Patterns

MSBuild Property Patterns

Conditional Defaults — The Foundational Pattern

Rules

Nested Conditional Groups

Composition — Semicolon Concatenation

Path Normalization and Trailing Slashes

Preferred path functions

Target Framework Detection Helpers

Guard Properties

Feature Gating by MSBuild Version

Fallback Chains

Last Write Wins — Evaluation Order

Common Pitfalls

Source and attribution

More from dotnet/skills

Setup Local Sdk

System Text Json Net11

Thread Abort Migration

Migrate Dotnet9 To Dotnet10

Target Authoring

Resolve Project References

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices