The project file
An SDK-style project
A project file is XML, and the first line of an SDK-style project names the SDK that knows how to build it:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<AssemblyName>report</AssemblyName>
<RootNamespace>Report</RootNamespace>
<Version>2.1.0</Version>
</PropertyGroup>
</Project>
The file is short because the SDK supplies the rest. Sdk
brings a long list of default items and properties: every
*.cs file under the project folder is compiled without
being named, the intermediate files go to obj and the
output to bin, and the compiler is the one the SDK
ships.
That is the whole difference from the old project format, which listed every
source file and every reference and needed a matching import block. A file
added to the folder is part of the project; a file deleted from it leaves
the project. The lesson on
the toolchain
reads the file of a project that was written for that old format.
The properties that matter
A PropertyGroup holds settings a build reads by name. These are the ones a beginner meets first:
- <OutputType>Exe</OutputType> makes an executable; Library makes a .dll with no entry point.
- <TargetFramework>net10.0</TargetFramework> names the framework the program runs on. A library may list several frameworks in TargetFrameworks, separated by semicolons, and is built once for each.
- <Nullable>enable</Nullable> turns on the nullable annotations of the lesson on nullable reference types.
- <ImplicitUsings>enable</ImplicitUsings> adds the common using lines to every file; the lesson on namespaces shows which ones.
- <AssemblyName> and <RootNamespace> name the output file and the default namespace.
- <Version> becomes the version of the assembly and of the package, if the project is packed.
- <LangVersion> chooses the C# version, which the lesson on the toolchain uses to show the version this SDK speaks.
A property may also be set on the command line, and then it wins:
dotnet build -p:Version=3.0.0
The command-line form is how a continuous build stamps a version without editing the file, and how the lessons of this course show one setting without changing the project.
Items: PackageReference and ProjectReference
An ItemGroup holds things rather than values: a package the project uses, another project of the same solution, a file to copy to the output.
<ItemGroup>
<PackageReference Include="System.Text.Json" Version="10.0.0" />
<ProjectReference Include="../Pricing/Pricing.csproj" />
<None Update="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
A PackageReference is downloaded during the restore, from the feeds the machine is configured with. This container has no network, so a project with a package that is not in the SDK fails the restore with error NU1301; the lesson on publishing and the testing group of this course show that error as it is. The BCL itself needs no package: it is the shared framework the runtime already carries.
The properties inside the assembly
The properties above are not only build settings: several of them are written into the assembly as attributes, and a program can read them back at run time. This program prints the name, the version and the target framework of the assembly it is running from.
using System.Reflection;
using System.Runtime.Versioning;
Assembly assembly = Assembly.GetExecutingAssembly();
Console.WriteLine($"assembly: {assembly.GetName().Name}");
Console.WriteLine($"version: {assembly.GetName().Version}");
Console.WriteLine($"informational: {assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion}");
Console.WriteLine($"framework: {assembly.GetCustomAttribute<TargetFrameworkAttribute>()?.FrameworkName}");
dotnet build
dotnet run
assembly: report
version: 2.1.0.0
informational: 2.1.0
framework: .NETCoreApp,Version=v10.0
Four values, three of them from the project file: AssemblyName gave the name, Version gave 2.1.0.0 (four parts, with the last two filled with zeros) and 2.1.0 as the informational version, and TargetFramework gave .NETCoreApp,Version=v10.0. The operator ?. is there because GetCustomAttribute returns null when an attribute is missing, and the nullable check of the lesson on nullable reference types would report a dereference without it.
bin and obj
A build writes into two folders, and they are not the same thing:
- obj is the work of the SDK: the restore, project.assets.json, the generated files of the compiler and one .dll per source file before they are linked.
- bin is the result: report.dll, report as the native launcher on Linux, and the .deps.json and .runtimeconfig.json that tell the runtime which framework to load.
Both folders belong in .gitignore. They are the answer to "why does the build behave differently on the other machine": a bin copied from elsewhere can be stale, and deleting both is always safe.
Exercises
- Change OutputType to Library and build. Which error does the compiler give for a program with statements in it?
- Set <Version>3.0.0-beta.1</Version> and look at the informational version the program prints.
- Add <TargetFrameworks>net10.0;net9.0</TargetFrameworks> and build. Which framework is missing, and what does the error say?
- Run the build with -p:AssemblyName=other and find the new file in bin.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which line of an SDK-style project names the framework it is built for?
Answer
<TargetFramework>net10.0</TargetFramework>
TargetFramework names the framework, and the SDK attribute names the build machinery; the other two set the output kind and the nullable checks.
-
Why does an SDK-style project not list its source files?
Answer
The SDK compiles every .cs file under the project folder by default
The SDK brings default items that include every .cs file, so a file added to the folder joins the build and a removed one leaves it.
-
What does this program print?
var version = typeof(object).Assembly.GetName().Version; Console.WriteLine(version is not null); Console.WriteLine(version.Major >= 10);Answer
True / True
A runtime assembly always reports its version, and the major part of this runtime is 10.
-
What does this program print?
Console.WriteLine(1 + 1); Console.WriteLine("1" + 1);Answer
2 / 11
The first + adds two ints; the second joins a string and an int, because a string operand makes the operator concatenate.
-
Which folder holds project.assets.json?
Answer
obj, written by the restore
The restore writes project.assets.json and the other nuget files into obj; bin holds the output of the build.
-
What does
dotnet build -p:Version=3.0.0do?Answer
Builds with Version set to 3.0.0, without editing the project file
A -p:NAME=value word sets an MSBuild property for one build, and it wins over the value in the file.
-
What happens to a project with a PackageReference to a package that is not in the local cache, on a machine with no network?
Answer
The restore fails with error NU1301 and nothing is built
The restore is the step that fetches packages, so without the feed it reports NU1301 and the build stops there.
-
What does this program print?
using System.Reflection; var assembly = Assembly.GetExecutingAssembly(); Console.WriteLine(assembly.GetName().Name is null);Answer
False
An assembly always has a name here, so the null check is False; the program prints the boolean, not the name.
-
Which output file tells the runtime which framework version to load?
Answer
The .runtimeconfig.json next to the assembly
The build writes a .runtimeconfig.json beside the assembly, and the runtime reads it before it loads anything.
-
What does an ItemGroup hold that a PropertyGroup does not?
Answer
A list of things, such as packages and projects, each with its own attributes
A PropertyGroup sets named values; an ItemGroup lists items such as PackageReference and ProjectReference, and each item may carry metadata.
The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev