.CSPROJ File Format – SDKs and imports

Naming an SDK

All four forms below have the same effect: an implicit <Import Project="Sdk.props" Sdk="…"/> at the very top of the project and an implicit <Import Project="Sdk.targets" Sdk="…"/> at the very bottom.

<Project Sdk="Microsoft.NET.Sdk">                  <!-- the attribute -->
<Project Sdk="Microsoft.NET.Sdk;My.Extra.Sdk/2.1.0"> <!-- several, with a version -->

<Project>
  <Sdk Name="Microsoft.NET.Sdk" Version="10.0.0" MinimumVersion="9.0.0" />   <!-- the element -->
</Project>

<Project>
  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />                    <!-- written out, to put things in between -->
  <!-- … the project … -->
  <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>

In the attribute, SDKs are separated by semicolons and a version follows a slash. An empty name, or a slash with no version after it, is an error (MSB4238). The written-out form is how a project runs its own properties before the SDK’s targets but after its props, or imports an SDK in the middle of a file.

How an SDK is found

MSBuild asks its SDK resolvers in turn; the first that knows the name answers with a folder. The ones that come with the .NET SDK are:

• the .NET SDK resolver, for the SDKs bundled with the .NET SDK (Microsoft.NET.Sdk and its relatives, which sit in the Sdks folder of the installed SDK) and for the .NET SDK version global.json asks for;
• the NuGet SDK resolver, for any other name: it restores a NuGet package of that name and uses its Sdk folder. The version comes from the attribute (My.Sdk/2.1.0) or from the msbuild-sdks section of global.json.

An SDK is a folder with Sdk/Sdk.props and Sdk/Sdk.targets. A name that no resolver finds is an error at load time; the explorer cannot know, so it lists a name it does not know as found by the SDK resolvers and shows the two file names the folder would have.

{
  "sdk": { "version": "10.0.100", "rollForward": "latestFeature", "allowPrerelease": false },
  "msbuild-sdks": { "My.Extra.Sdk": "2.1.0", "Microsoft.Build.Traversal": "4.1.0" }
}

The SDKs of the .NET SDK

Other SDKs come as NuGet packages: Microsoft.Build.NoTargets (a project that builds nothing), Microsoft.Build.Traversal (a project that builds the projects it references), Microsoft.Build.CentralPackageVersions, MSTest.Sdk, Aspire.AppHost.Sdk, Uno.Sdk and others.

What Microsoft.NET.Sdk imports

The complete chain for a C# project in .NET SDK 10.0.404, in the order MSBuild imports it (this is what dotnet msbuild -preprocess lists). Names are relative to the SDK’s folder. An F# or Visual Basic project differs in the language-specific files; the workload manifests an installation adds are not listed.

The explorer lists every one of these files for a project that names Microsoft.NET.Sdk, with the place it is imported at, in the Overview. It does not open them: they are a different file each, and a project’s own view stays its own.

Files MSBuild looks for by name

Props and targets files

A .props file sets properties and default items and is imported before the project body, so the project can override it. A .targets file defines targets and anything that must see the project’s final values and is imported after. Both are ordinary MSBuild files with a Project root; the names are convention only, and the explorer treats both alike. In an imported file $(MSBuildThisFileDirectory) is its own folder, and a Condition on the Import such as Exists('…') makes it optional.

A property defined in a props file is overridden by the project’s later definition of the same name; the usual idiom for a default that the project may change is <Name Condition="'$(Name)' == ''">value</Name>.

Choose

Choose holds one or more When elements, each with a required Condition, and at most one Otherwise at the end. MSBuild takes the first When whose condition is true, else the Otherwise; a When after the Otherwise is an error (MSB4084), a When without a condition is an error (MSB4035). A branch holds PropertyGroup, ItemGroup and further Choose elements. Unlike a Condition on a group, a Choose decides once, during evaluation; legacy Visual Studio projects use it to give each configuration its own settings.

Legacy projects

Before SDKs, a project listed everything. It has the MSBuild 2003 namespace, a ToolsVersion, no Sdk, an Import of Microsoft.Common.props at the top and of Microsoft.CSharp.targets at the bottom, an ItemGroup that names each Compile file and each Reference, and a PropertyGroup for every configuration and platform. The explorer tells the two styles apart in the Overview (SDK style or legacy style with the 2003 namespace) and lists the explicit imports in the Imports tab, since for a legacy project they are in the file.

In the explorer

The Overview of a project lists the SDK references (name, version, how it was written and whether the explorer knows it), the implicit imports of each SDK in the order above, and the files the common targets import by themselves. The Imports tab lists the Import elements written in the file with their conditions.

Not described

Known, not yet covered

• Reference: the import chains of the other SDKs (web, Razor, Blazor, Worker) down to the last file, and of an F# or Visual Basic project; the sdk-resolvers of third parties; the contents of the SDK files themselves.

Sources

Microsoft Learn, use MSBuild project SDKs, customize your build and global.json. The import chain, the Directory.Build lookup and the language targets were read from the files of .NET SDK 10.0.404 itself (Sdks/Microsoft.NET.Sdk/Sdk/Sdk.targets, Current/Microsoft.Common.props, Microsoft.Common.targets) and listed by dotnet msbuild -preprocess.