# MSBuild Property Patterns for Cross-Platform Build Configuration: 9 Essential Patterns > Master MSBuild property patterns for cross-platform builds. Discover 9 essential techniques for uniform behavior on Windows, macOS, and Linux, with command-line overrides. - Repository: [.NET Platform/skills](https://github.com/dotnet/skills) - Tags: how-to-guide - Published: 2026-07-07 --- **MSBuild uses conditional defaults, path normalization functions, and guard properties to create portable build configurations that behave identically across Windows, macOS, and Linux while allowing command-line overrides.** MSBuild projects that compile on multiple operating systems require careful property management to handle path separators, trailing slashes, and overridable defaults. The **dotnet/skills** repository defines authoritative MSBuild property patterns for cross-platform build configuration in [`plugins/dotnet-msbuild/skills/property-patterns/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/property-patterns/SKILL.md), providing battle-tested XML patterns that work identically on .NET SDK projects regardless of the host OS. ## Conditional Defaults for Overridable Configuration The foundational pattern for cross-platform builds uses the `Condition` attribute to set values only when they are not already defined. This allows CI/CD pipelines and solution files to override defaults without modifying project files. According to the dotnet/skills source code, standard practice defines `Configuration` and `Platform` properties using the `== ''` condition check: ```xml Debug AnyCPU ``` This pattern ensures that command-line arguments like `/p:Configuration=Release` take precedence over hard-coded defaults, preventing accidental overrides that break builds on different agents. ## Path Normalization and Trailing-Slash Handling Cross-platform builds fail when paths use hard-coded backslashes or missing trailing separators. The [`plugins/dotnet-msbuild/skills/property-patterns/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/property-patterns/SKILL.md) documentation recommends using MSBuild intrinsic functions and `System.IO.Path` methods to guarantee platform-agnostic paths. **Trailing-slash enforcement** prevents "directory not found" errors on Linux by appending the separator only when absent: ```xml $(OutDir)\ ``` **Absolute path generation** uses `NormalizePath` to combine segments with the correct separator for the current OS: ```xml $([MSBuild]::NormalizePath('$(TargetDir)', 'ref', '$(TargetFileName)')) ``` For paths that might be relative, convert them to absolute using `System.IO.Path`: ```xml $([System.IO.Path]::Combine('$(MSBuildProjectDirectory)', '$(MSBuildProjectExtensionsPath)')) ``` ## Composition Patterns for List-Type Properties Appending to semicolon-delimited lists like `DefineConstants` and `NoWarn` requires preserving existing values to avoid clobbering settings from imported targets. The composition pattern uses property references within the assignment: ```xml $(DefineConstants);MY_FEATURE $(NoWarn);NU5131;IDE0005 ``` This guarantees that standard compilation constants defined by the SDK remain intact while adding project-specific values. ## Nested Conditional Groups for Framework-Specific Settings When applying multiple properties to a specific target framework, group them under a single `Condition` to reduce XML repetition and improve maintainability: ```xml $(DefineConstants);FEATURE_APARTMENT_STATE $(DefineConstants);FEATURE_APM ``` ## Target Framework Detection Helpers Detecting the Target Framework Moniker (TFM) enables conditional logic for .NET Core versus .NET Framework builds. Use `GetTargetFrameworkIdentifier` to branch logic: ```xml true ``` ## Guard Properties for Import-Once Safety Import loops occur more easily on case-insensitive file systems (Windows) than on case-sensitive ones (Linux). Guard properties ensure a `.props` file processes only once: ```xml true ``` ## Feature Gating by MSBuild Version Enable newer behaviors only when building with recent MSBuild versions to maintain backward compatibility: ```xml true ``` ## Fallback Chains for Tool Resolution When locating external tools, provide a primary resolution path and a secondary fallback to handle different installation scenarios: ```xml $([Microsoft.Build.Utilities.ToolLocationHelper]::GetPathToDotNetFrameworkSdkFile('tlbexp.exe')) $(_NetFxToolsDir)TlbExp.exe ``` ## Understanding Last-Write-Wins Evaluation MSBuild evaluates properties top-to-bottom during the property evaluation phase. Later assignments override earlier ones, which you can leverage to expose overridable defaults: ```xml value1 value2 ``` Design your `.props` files to set conservative defaults early and allow consuming projects to override them later in the evaluation order. ## Summary - **Conditional defaults** using `Condition="'$(Property)' == ''"` enable command-line overrides while providing safe defaults - **Path normalization** via `$([MSBuild]::NormalizePath(...))` and `$([System.IO.Path]::Combine(...))` eliminates platform-specific path separators - **Trailing-slash handling** with `HasTrailingSlash` prevents directory resolution errors on Linux - **Composition** using `$(DefineConstants);NEW_VALUE` preserves existing list items when adding constants - **Guard properties** prevent duplicate imports that cause duplicate definitions on case-sensitive file systems - **Feature gating** via `$([MSBuild]::AreFeaturesEnabled(...))` allows conditional use of new MSBuild capabilities - **Fallback chains** provide robust tool resolution across different installation environments - **Evaluation order** determines final property values—define defaults early and overrides late ## Frequently Asked Questions ### How do I ensure my MSBuild properties work on both Windows and Linux? Use `$([MSBuild]::NormalizePath(...))` to combine path segments and `$([System.IO.Path]::IsPathRooted(...))` to check if paths need resolution. Always check for trailing slashes using `HasTrailingSlash` before appending subdirectories, as Linux treats `folder` and `folder/` differently than Windows in certain contexts. ### What is the correct way to add a new compiler constant without losing existing ones? Append to `DefineConstants` using the composition pattern: `$(DefineConstants);YOUR_CONSTANT`. This preserves constants defined by the SDK or previous imports. Never assign a bare string to `DefineConstants` without referencing the existing value first. ### Can I prevent a .props file from being imported multiple times? Yes, define a **guard property** at the top of your props file, such as `true`, then condition the import: `Condition="'$(MyPropsImported)' != 'true'"`. This is essential for case-sensitive file systems where import loops behave differently than on Windows. ### How do I detect which .NET version I am targeting during build? Use `$([MSBuild]::GetTargetFrameworkIdentifier('$(TargetFramework)'))` to return strings like `.NETCoreApp` or `.NETFramework`, or compare the `TargetFramework` property directly using `StartsWith` for version-specific constants.