Document that modifying Properties property on ProjectReference items should be avoided, use AdditionalProperties instead
- Dominant language
- C#
- Stars
- 5.5k
- Forks
- 1.5k
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 141
Description
### Issue Description
This is a documentation companion bug for [[BuildCheck Suggestion]: Flag usage of the Properties metadata on inputs to the MSBuild Task like ProjectReference](https://github.com/dotnet/msbuild/issues/12659)
There is existing documentation on [Pass properties to projects](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-task?view=vs-2022#pass-properties-to-projects) that concentrates on running msbuild task.
Developers could also use alternative approach - modify ProjectReference item group which is very appealing as everything else is taken care by the build.
The problem:
- Modifying Properties element like this will break cross-targeting projects (it completely overwrites properties and does not allow msbuild inject intended additional properties like TargetFramework).
```
BuildArchitecture=AMD64
ARM64=false;ARM64EC=false
```
- The correct approach for developer is to use AdditionalProperties property - it will correctly merge with existing properties (add new, change existing). For removal one could use GlobalPropertiesToRemove
- Documentation, however, does not steer strongly enough from Properties to AdditionalProperties
Additional point: I asked couple of AI models (Copilot, Claude Sonnet 4.5) if approach above is valid. They did not mention AdditionalProperties at all. Sonnet did pick that above would overwrite properties but suggested approach to do `%(Properties);ARM64=true;ARM64EC=false` is not going work either.
Improving documentation can prevent use of this anti-pattern and long troubleshooting.
### Steps to Reproduce
-
### Expected Behavior
Updated documentation for "Pass properties to projects":
- has section and example for modifying ProjectReference item group in say Directory.Build.Props as it's a good alternative to calling msbuild task directly.
- Uses strong wording cautioning against modifying Properties on ProjectReference and steer towards AdditionalProperties.
- Probably mentions special SetBlah properties (SetConfiguration, SetPlatform, SetTargetFramework) - they should be used for Configuration/Platform/TargetFramework rather than AdditionalProperties
Updated documentation for [Diagnose and fix race conditions](https://learn.microsoft.com/en-us/visualstudio/msbuild/fix-intermittent-build-failures?view=vs-2022#diagnose-and-fix-race-conditions) should probably mention Properties anti-patterns.
### Actual Behavior
-
### Analysis
_No response_
### Versions & Configurations
_No response_
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.