Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท .NET, Tools and Concepts

Project files (.csproj)

Reference for .NET project files: the SDK-style .csproj, TargetFramework, Nullable, ImplicitUsings, LangVersion, package and project references, props files.

A project file tells the .NET SDK how to build your code: which language features and target framework to use, which packages and projects to reference, and what kind of output to produce. It is a small XML file with the extension .csproj (.fsproj for F#, .vbproj for Visual Basic). Modern ("SDK-style") project files are short because the SDK supplies sensible defaults, such as compiling every .cs file in the folder.

XML
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

The editors on this site compile a single file and do not read a .csproj. The settings described here are the ones the runner already uses: C# 14, nullable reference types on, implicit usings on, .NET 10. The project files below are read-only, but the examples let you parse and generate one with ordinary C#.

Try it

A project file is plain XML, so you can read it with System.Xml.Linq. This is how tools and build scripts check settings.

C# Reading properties from a project file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Generating a project file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

An SDK-style project has a root <Project Sdk="..."> element with property groups (settings) and item groups (lists of files, packages and references).

Choosing an SDK

Sdk value Use for
Microsoft.NET.Sdk Console apps, class libraries, tests.
Microsoft.NET.Sdk.Web ASP.NET Core apps. Adds the web framework reference and web implicit usings.
Microsoft.NET.Sdk.Worker Background services using the generic host.
Microsoft.NET.Sdk.Razor Razor class libraries.

Common properties

Property Description
OutputType Exe for an application, Library (the default) for a class library. Web projects are Exe automatically.
TargetFramework net10.0 (or net8.0, net9.0, netstandard2.0). TargetFrameworks (plural) builds for several.
LangVersion latest, preview, default or a number such as 13. The default depends on the target framework: .NET 10 uses C# 14.
Nullable enable turns on nullable reference type analysis (Nullable context).
ImplicitUsings enable adds global using directives for common namespaces (Implicit usings).
AssemblyName, RootNamespace Output file name and the namespace given to new files.
TreatWarningsAsErrors Turns every warning into an error. WarningsAsErrors and NoWarn are the targeted versions.
AllowUnsafeBlocks Allows unsafe code.
InvariantGlobalization Avoids ICU and culture data; all cultures behave like the invariant culture.
PublishAot, PublishTrimmed, PublishSingleFile Publishing options.
Version, Authors, Description, PackageId Metadata used when you create a NuGet package.

Items

XML
<ItemGroup>
  <PackageReference Include="Humanizer" Version="2.14.1" />
  <ProjectReference Include="..\Core\Core.csproj" />
  <Using Include="System.Text" />
  <InternalsVisibleTo Include="Shop.Tests" />
  <None Update="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

A <Using Include="..."> item becomes a global using. <InternalsVisibleTo> emits the attribute for you.

Usage notes

  • Files are included automatically. SDK-style projects compile every *.cs file under the folder, except bin and obj. You list a file only to exclude or customize it.
  • Shared settings. Directory.Build.props in a parent folder is imported by every project below it, which is the place for Nullable, LangVersion or TreatWarningsAsErrors. Directory.Packages.props with ManagePackageVersionsCentrally keeps package versions in one place.
  • Conditions. Most elements accept Condition="'$(Configuration)' == 'Release'", so you can vary settings by configuration or operating system.
  • Edit by hand or by command. dotnet add package and dotnet add reference edit the file for you (The dotnet CLI).
  • Do not commit bin and obj. They hold build output and restore data and are recreated at will.
  • Old-style projects (pre-2017) listed every file and had a long header. If you meet one, the SDK can still build it, but migrating is worthwhile.
  • File-based programs. For one-file scripts, #:property Nullable=enable and #:package lines at the top of the file stand in for a project file.
  • Typos fail quietly. An unknown property name is not an error; MSBuild simply ignores it. If a setting seems to have no effect, check its spelling.