.CSPROJ File Format – Conditions

Where a condition may be written

On every element that does something: PropertyGroup, each property, ItemGroup, each item and each item metadata element, ItemDefinitionGroup, Target, each task, Output, OnError, Import, ImportGroup, UsingTask and When (where it is required: it is how a Choose picks its branch). Choose and Otherwise take none. The attribute on Project itself is not checked by MSBuild.

A condition is evaluated while the file is evaluated: properties and items it reads are those defined earlier in the evaluation order, not those further down the file.

Grammar

condition    = or-expr
or-expr      = and-expr { "or" and-expr }
and-expr     = relational { "and" relational }
relational   = factor [ ( "==" | "!=" | "<" | "<=" | ">" | ">=" ) factor ]
factor       = argument
             | function "(" [ argument { "," argument } ] ")"
             | "(" or-expr ")"
             | "!" factor
argument     = quoted-string | number | word | property | metadata | item-list

and binds tighter than or, and both are left-associative. A relational operator takes one operand on each side and cannot be chained: a == b == c is an error. and and or are written in any case (AND, Or) and, as MSBuild’s own comment notes, need no spaces around them: '$(A)'==''and '$(B)'=='' is valid.

Tokens

Operators

What counts as a boolean

The condition as a whole, and each operand of and, or and !, must evaluate to a boolean: the words true, false, on, off, yes and no, in any case, with or without quotes. Anything else is an error when the condition is evaluated: Condition="x" reports that the condition evaluates to x instead of a boolean (MSB4113), and so does Condition="$(Undefined)", which evaluates to the empty string.

Item lists and metadata

Inside a target, a condition may read item lists and item metadata. Outside a target (during evaluation, before any item list is final) MSBuild refuses them in some conditions. Each row was found by running the tool.

Functions

Two functions exist; the name is matched without regard to case, takes exactly one argument, and any other name is an error.

Property functions are different: they are written inside $(…) and have their own page, expressions and functions; $([MSBuild]::IsOSPlatform('Windows')) and $([System.IO.File]::Exists('a')) are expressions that give a string (True or False) which the condition then compares.

Examples

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <DefineConstants>$(DefineConstants);TRACE</DefineConstants>
</PropertyGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net48' and Exists('legacy')">
  <Compile Include="legacy\**\*.cs" />
</ItemGroup>
<Import Project="local.props" Condition="Exists('local.props')" />
<PropertyGroup Condition="$([MSBuild]::IsOSPlatform('Linux')) or '$(CI)' != ''">
  <Deterministic>true</Deterministic>
</PropertyGroup>
<Target Name="Report" Condition="'@(Compile)' != '' and $(MSBuildToolsVersion) >= 15.0">
  <Message Text="Compiling @(Compile->Count()) files" />
</Target>

Errors

A condition that cannot be parsed makes MSBuild refuse the file, with an error that gives the position (counted from 1) inside the condition. These are the errors of the scanner and parser, each checked against the tool; the explorer reports the same ones, with the position.

Expressions that are malformed inside a value rather than a condition are not errors: $(, @( and $() in a property value or an item’s Include are left as plain text.

In the explorer

Open a project in the explorer and its Conditions tab lists every condition with its line, the element it is on, how the parser read it (for example ((a == 1) or ((b == 2) and (c == 3)))) and whether it parses. In the Structure tree a condition is taken apart: each operator, quoted string, function and expression is a node of its own, and a syntax error is marked on the part of the condition where MSBuild would stop.

Not described

Known, not yet covered

• Reference: the exact conversion rules for comparing mixed numbers, versions and strings (for example a value with trailing text against a number) are not listed beyond the cases above; they are in ConditionEvaluator.cs and the expression nodes of MSBuild’s source.

Sources

MSBuild source (dotnet/msbuild, src/Build/Evaluation/Conditionals/Scanner.cs and Parser.cs): tokens, grammar, function names. The error codes and their conditions were found by running dotnet msbuild of the .NET SDK on each case. Microsoft Learn, MSBuild conditions.