Define precedence relationship with MSBuild properties and CLI args

[richlander]

I was defining some intended UX at #26028 (comment). I realized that I didn't understand the precedence relationship in MSBuild and the CLI. If this is documented, it would have great to have the link. If not, we should document the behavior.

There are a few scenarios I have in mind. I'm sure that there are other ways to mix these things up. These are the ones that came to mind for me.

Overlapping properties

Flip the properties in various ways.

<SelfContained>true</SelfContained>
<PublishSelfContained>false</PublishSelfContained>

and

dotnet publish

Overlapping properties, between XML and the "MSBuild" CLI

<PublishSelfContained>false</PublishSelfContained>

and

dotnet publish -p:SelfContained=true

Overlapping properties, between XML and the CLI

<PublishSelfContained>false</PublishSelfContained>

and

dotnet publish --self-contained true

[marcpopMSFT]

As far as I know, the CLI always wins. In both of the above scenarios, this is the case. I'm sure there might be cases where it doesn't work but that'd have to be related properties rather than matching properties. I don't believe PublishSelfContained has been implemented yet so I don't know how to answer your questions of competing project properties yet but for competing project properties, I don't think it's entirely predictable.

[richlander]

When we implement PublishSelfContained, it would be good to document the expected behavior somewhere and to ensure we either don't implement features with unpredictable behavior or document the narrow cases where they are unpredictable.

[baronfel]

The most relevant documentation we have is on MSBuild Properties in the conceptual docs, specifically the section on global properties.

This is a common pit of failure for users, especially at solution-level builds. CLI-specified properties override project-local properties for the entire build, which often means that CLI properties are not the correct vehicle for any kind of logic that can vary.

@jaredpar has asked for something like --local-property in the past, which would ideally behave as a normal MSBuild Property with an initial value, but would otherwise participate in build logic and be overridable.

[jaredpar]

@jaredpar has asked for something like --local-property in the past, which would ideally behave as a normal MSBuild Property with an initial value, but would otherwise participate in build logic and be overridable.

Indeed. Essentially anything that let me set the initial property of a value for a build. This would just set a default initial value but have no other effect. The resulting property could be mutated just like any other property in subsequent build steps. I find the fact that -p prorties are global and immutable is generally confusing to customers.