What is an SDK-style .csproj, and how does it differ from an old-style project file?

1. What the Sdk attribute expands to

<Project Sdk="Microsoft.NET.Sdk"> is shorthand for two implicit imports, one before your content and one after it:

 <Project Sdk="Microsoft.NET.Sdk">        what MSBuild actually evaluates
                                         +--------------------------------------+
                                         | <Import Sdk.props />                 |
                                         |   Directory.Build.props (if found)   |
                                         |   default properties                 |
                                         |   default item globs (**/*.cs ...)   |
   <PropertyGroup> ... </PropertyGroup>  | --- your project content ----------- |
   <ItemGroup> ... </ItemGroup>          |                                      |
                                         | <Import Sdk.targets />               |
                                         |   Directory.Build.targets (if found) |
                                         |   build / pack / publish targets     |
 </Project>                              +--------------------------------------+

The order matters. Anything you set in the project overrides the defaults from Sdk.props, but Sdk.targets runs after your content, so it sees your final property values. Run dotnet msbuild -preprocess:full.xml to see the fully expanded project; it is often several thousand lines.

The attribute can also name a versioned SDK from NuGet, for example <Project Sdk="Microsoft.Build.NoTargets/3.7.0">. MSBuild's SDK resolvers find it in the installed .NET SDK or download it as a package.

2. Old-style and SDK-style side by side

An old-style class library, abbreviated:

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <ProjectGuid>{5A3B...}</ProjectGuid>
    <OutputType>Library</OutputType>
    <TargetFrameworkVersion>v4.8</TargetFrameworkVersion>
    ...
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' "> ... </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' "> ... </PropertyGroup>
  <ItemGroup>
    <Reference Include="Newtonsoft.Json">
      <HintPath>..\packages\Newtonsoft.Json.13.0.3\lib\net45\Newtonsoft.Json.dll</HintPath>
    </Reference>
    <Reference Include="System" />
    ...
  </ItemGroup>
  <ItemGroup>
    <Compile Include="Customer.cs" />
    <Compile Include="Order.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
    ... one line per file ...
  </ItemGroup>
  <ItemGroup>
    <None Include="packages.config" />
  </ItemGroup>
  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
</Project>

The same library, SDK-style:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

3. Default items and globbing

Every glob excludes bin/, obj/, **/*.user, **/*.*proj, **/*.sln and other files listed in DefaultItemExcludes. You can extend that list:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);scratch/**</DefaultItemExcludes>
</PropertyGroup>

The three item operations:

Using Include for a file that is already globbed adds it twice, which fails with NETSDK1022 (duplicate items).

4. The SDKs and what each adds

5. Properties you will set most often

6. What ImplicitUsings generates

For Microsoft.NET.Sdk the generated file contains global using directives for System, System.Collections.Generic, System.IO, System.Linq, System.Net.Http, System.Threading and System.Threading.Tasks. The Web SDK adds ASP.NET Core namespaces such as Microsoft.AspNetCore.Builder. You can add or remove entries:

<ItemGroup>
  <Using Include="Orders.Domain" />
  <Using Remove="System.Net.Http" />
</ItemGroup>

7. Migrating an old project

1. Convert the project file to SDK-style while keeping the same target (net48). Remove the <Compile> list, ProjectGuid and the configuration blocks.
2. Convert packages.config to PackageReference (Visual Studio offers "Migrate packages.config to PackageReference"). Keep only top-level packages.
3. Delete Properties/AssemblyInfo.cs or set GenerateAssemblyInfo to false, otherwise you get CS0579 duplicate attribute errors.
4. Build with dotnet build and fix differences such as files that were deliberately not in the old <Compile> list but are now globbed.
5. Get it building in CI on the CLI, then change the target framework in a separate step.

The .NET Upgrade Assistant and the newer AI-assisted modernisation tooling in Visual Studio can automate parts of this, but review the result as you would any other change.

8. File-based apps in .NET 10

.NET 10 can run a single C# file without a project file: dotnet run app.cs. Directives at the top of the file, such as #:package [email protected] and #:sdk Microsoft.NET.Sdk.Web, play the role of the project file. When the script grows, dotnet project convert app.cs turns it into a normal SDK-style project. It's useful for scripts and samples, but production code still belongs in projects.

9. Diagnosing project-file problems

10. .NET 11 awareness

The .NET 11 SDK (preview now) keeps the same project format. Moving a project later is usually a one-line change to TargetFramework (net11.0), plus fixing any new warnings. Keep production projects on net10.0 (LTS) for now.

11. Try it yourself

1. Run dotnet new console -o Demo and open Demo.csproj.
2. Add Extra.cs with a class and build. You didn't touch the project file.
3. Run dotnet msbuild -getItem:Compile and find Extra.cs in the list.
4. Add <Compile Include="Extra.cs" /> and build to see NETSDK1022. Change it to <Compile Remove="Extra.cs" /> and see the class disappear.
5. Run dotnet msbuild -preprocess:full.xml and search for Sdk.props and Sdk.targets.
6. Change Sdk to Microsoft.NET.Sdk.Web, preprocess again, and compare the size.
7. Open obj/Debug/net10.0/Demo.GlobalUsings.g.cs to see what ImplicitUsings generated.

<!-- An ASP.NET Core API project -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>Orders.Api</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <!-- Exclude a folder of legacy files from compilation -->
    <Compile Remove="Legacy/**" />
    <!-- Change metadata on a file that globbing already includes -->
    <None Update="seed-data.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\Orders.Domain\Orders.Domain.csproj" />
  </ItemGroup>
</Project>

// Program.cs: with ImplicitUsings, common namespaces need no using directives
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/health", () => Results.Ok(new { status = "ok", region = "australiaeast" }));
app.Run();