A .csproj file is an MSBuild project file: XML following the MSBuild
schema, which Microsoft publishes as Microsoft.Build.xsd in the
dotnet/msbuild repository. The same
schema applies to .vbproj, .fsproj, .vcxproj,
.props and .targets files. The items and properties that give
a project its meaning are on the items and
properties page.
Elements
| Element | Children | Attributes |
|---|---|---|
Project | Choose, Import, ImportGroup, ItemGroup, ItemDefinitionGroup, ProjectExtensions, PropertyGroup, Sdk, Target, UsingTask | DefaultTargets, InitialTargets, Sdk, ToolsVersion, TreatAsLocalProperty, xmlns |
PropertyGroup | properties | Condition |
| Property (any name) | – | Condition; the text is the value |
ItemGroup | items | Condition |
| Item (any name, the item type) | metadata | Include, Exclude, Remove, Update, MatchOnMetadata, MatchOnMetadataOptions, KeepDuplicates, KeepMetadata, RemoveMetadata, Condition; other attributes are metadata |
| ItemMetadata (any name) | – | Condition; the text is the value |
ItemDefinitionGroup | items | Condition; sets default metadata for every item of a type |
Import | – | Project, Condition, Label, Sdk |
ImportGroup | Import | Condition |
Sdk | – | Name, Version |
Choose | When, Otherwise | – |
When | Choose, ItemGroup, PropertyGroup | Condition |
Otherwise | Choose, ItemGroup, PropertyGroup | – |
Target | tasks, PropertyGroup, ItemGroup, OnError | Name, Condition, Inputs, Outputs, Returns, KeepDuplicateOutputs, BeforeTargets, AfterTargets, DependsOnTargets, Label |
| Task (named after the task) | Output | Condition, ContinueOnError, the task’s parameters |
Output | – | TaskParameter, PropertyName or ItemName, Condition |
OnError | – | ExecuteTargets, Condition; must be last in its target |
UsingTask | ParameterGroup, Task | TaskName, AssemblyName or AssemblyFile, TaskFactory, Architecture, Runtime, Override, Condition |
ParameterGroup | parameters | – |
| Parameter (any name) | – | ParameterType, Required, Output |
Task (inside UsingTask) | data for the task factory | Evaluate |
ProjectExtensions | any XML | –; at most one, for data that is not MSBuild’s |
Project
| Attribute | Meaning |
|---|---|
Sdk | An SDK name with an optional /version, e.g. Microsoft.NET.Sdk. MSBuild adds an implicit <Import Project="Sdk.props" Sdk="…"/> at the top of the project and <Import Project="Sdk.targets" Sdk="…"/> at the bottom. |
DefaultTargets | Targets to build when none is named, separated by semicolons. Without it, the first target after imports are evaluated is used. |
InitialTargets | Targets that run before the default or named targets; from every imported file, in import order. |
ToolsVersion | The toolset version, which sets $(MSBuildBinPath) and $(MSBuildToolsPath). |
TreatAsLocalProperty | Properties that global (command-line) properties do not override in this file and its later imports. |
xmlns | If present, http://schemas.microsoft.com/developer/msbuild/2003; not needed since Visual Studio 2017. |
Items
| Attribute | Meaning |
|---|---|
Include | Files or wildcards to add (*, ?, and ** for any depth), separated by semicolons. |
Exclude | Files or wildcards not to add. |
Remove | Files or wildcards to remove from the item list. |
Update | Change the metadata of items already in the list; outside targets only. |
MatchOnMetadata | With a Remove that only references other items, match on these metadata names instead of the item values. |
MatchOnMetadataOptions | CaseSensitive, CaseInsensitive (default) or PathLike. |
KeepDuplicates | Whether to add an exact duplicate; inside targets only. |
KeepMetadata | Only these metadata names are copied from source items; inside targets only. |
RemoveMetadata | These metadata names are not copied; inside targets only. |
Condition | See conditions. |
Any other attribute, or any child element, is metadata: e.g.
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />.
Import
Project (required) is the path of the file to import, relative to the
importing file, and may contain wildcards: the matches are imported in sorted order.
Sdk names an SDK to find the file in. Imported files have the same schema;
by convention they end in .props or .targets.
MSBuildProjectDirectory and similar reserved properties refer to the
importing project.
Target
| Attribute | Meaning |
|---|---|
Name | Required. Any characters except $@()%*?.. The last target with a given name wins. |
Condition | If false, neither the target nor its DependsOnTargets run. |
Inputs, Outputs | Files whose timestamps are compared to decide whether the target is up to date. |
Returns | Items returned to callers; without it, Outputs are returned. |
KeepDuplicateOutputs | true: keep duplicate items in the returned list (default false). |
BeforeTargets, AfterTargets | Run this target before or after the named targets. |
DependsOnTargets | Targets to run first, left to right. |
Label | An identifier. |
A target runs at most once per build.
Tasks
A task element is named after the task (e.g. Csc, the C# compiler
task); its attributes set the task’s parameters, and Output
children store its outputs in properties or items.
ContinueOnError values:
| Value | Meaning when the task fails |
|---|---|
WarnAndContinue or true | Carry on; its errors become warnings. |
ErrorAndContinue | Carry on; its errors stay errors. |
ErrorAndStop or false | The default: stop the target and the build, which fails; OnError targets still run. |
UsingTask
| Attribute | Meaning |
|---|---|
TaskName | Required. The task, with its namespace where needed. |
AssemblyName / AssemblyFile | One is required: the assembly by name, or by path (relative to the declaring file). |
TaskFactory | The class that creates the task; default AssemblyTaskFactory. |
Architecture | x86, x64, CurrentArchitecture or *. |
Runtime | CLR2, CLR4, CurrentRuntime, NET (MSBuild 18 and later) or *. |
Override | true: take priority over other definitions of the task (MSBuild 17.2 and later). Otherwise the first UsingTask for a name wins. |
Conditions
Condition is allowed on Import, ImportGroup,
items, ItemDefinitionGroup, ItemGroup, metadata,
OnError, Output, properties, PropertyGroup,
Target, tasks, UsingTask and When.
| Expression | Meaning |
|---|---|
'a' == 'b', 'a' != 'b' | String comparison, ignoring case. Quotes are needed for empty values. |
<, >, <=, >= | Numeric comparison of decimal, 0x hexadecimal or four-part version values (written < and > in XML). |
Exists('path') | A file or folder exists (no wildcards). |
HasTrailingSlash('s') | The string ends in \ or /. |
!, And, Or, ( ) | Logic; And binds tighter than Or. |
Expansions
| Form | Meaning |
|---|---|
$(Name) | A property’s value; empty if not defined. String methods may follow, e.g. $(TargetFramework.TrimEnd(`0123456789`)). |
@(Type), @(Type, 'sep') | An item list joined by semicolons (or by sep). |
@(Type->'%(Meta)') | An item transform. |
%(Meta), %(Type.Meta) | Item metadata; inside targets, causes batching. |
Sources
Microsoft Learn (MSBuild): MSBuild project file schema reference, and the element pages for Project, Item, Import, Target, Task and UsingTask; MSBuild conditions; .NET project SDK overview (implicit imports).