Every Build Tells a Story: The Science of `dotnet build`

Ever Wondered What Happens After You Press "Build Solution"?

If you’re a .net developer, chances are you’ve hit that magical “Build Solution” button countless times. But have you ever paused to wonder, what really happens behind the scenes? How does your carefully crafted code transform into a working application? Is it some sort of developer sorcery, or is there a structured process behind it? 🤔

Let’s demystify the journey of your code from its humble beginnings in a text editor to becoming a fully functional application. To truly appreciate the role of build systems, let’s first imagine a world without them.

a baby is laying on a blue pillow and making a face .

What If Build Systems Didn't Exist?

Picture this: You’ve just written a complex .NET application with multiple files, dependencies, and configurations. Without a build system, your workflow would look something like this:

Manually Compile Files: You’d need to individually compile each source file with the correct compiler and flags.
Resolve Dependencies by Hand: Missing a library? Time to manually search, download, and link it correctly.
Handle Configurations Manually: Switching between Debug and Release builds would mean editing settings manually for every environment.
Repeat the Process for Every Change: Made a tiny change in one file? Start the entire process all over again.

a man wearing a yellow vest and tie is screaming with his mouth open

Sounds exhausting, right? Now imagine doing this for a project with dozens of files or hundreds of dependencies. Every small code change could cascade into hours of tedious work. And debugging? Good luck finding out whether the issue is in your code or a missing compiler flag.

This is where build systems shine; they automate and optimise the entire process, letting developers focus on what matters: writing great code 🧑‍💻.

What Is a Build System?

A build system is like a highly efficient production line for your code. It automates the process of turning your source code into an executable application, handling all the tedious and error-prone tasks for you.

At its core, a build system is responsible for:

Compiling Code: Transforms your high-level code (C#, for instance) into machine-readable Intermediate Language (IL).
Dependency Management: Ensures all external libraries and packages are correctly resolved and included.
Configuration Management: Builds applications for specific environments (e.g., Debug vs. Release).
Packaging: Bundles your code, resources, and configurations into a deployable format.

a man in a blue and white striped shirt and tie is saying oh my god wow

For .NET applications, this process is powered by MSBuild, the backbone of tools like Visual Studio and dotnet build.

Behind the Scenes of `dotnet build`

When you press “Build Solution” or run dotnet build, a series of carefully orchestrated steps happen under the hood:

Project Evaluation
The process starts with evaluating your .csproj file. This XML file defines:
- The source files to include.
  - Dependencies (NuGet packages, project references).
  - Target framework(s) (e.g., .NET 6, .NET 7).
  - ```
      <PropertyGroup>
        <TargetFramework>net7.0</TargetFramework>
        <OutputType>Exe</OutputType>
      </PropertyGroup>
```

The build system uses this file to figure out what needs to be done.

Dependency Restoration
If dependencies are missing, dotnet build triggers a restore step (equivalent to dotnet restore). It fetches NuGet packages and resolves references, ensuring your project has everything it needs.
Compiling the Code
- Source files are compiled into Intermediate Language (IL) using the Roslyn compiler (csc for C#).
- The compiler also generates metadata about your code, like method signatures and type information.
Linking and Assembly Generation
The compiled IL is combined into assemblies (.dll or .exe). This involves resolving all dependencies and ensuring the output is valid for the target runtime.
Incremental Builds
To save time, dotnet build checks whether files have changed. If nothing is modified, it skips recompiling unchanged files. This is powered by MSBuild, which tracks file timestamps and dependencies.
Target Execution
The build process uses predefined targets and tasks defined by MSBuild. For example:
- CoreCompile handles compilation.
- ResolveReferences ensures dependencies are correctly linked.

You can customise or extend these targets in your .csproj file to fit your specific needs.

Output Delivery
Finally, the compiled binaries are placed in the bin/Debug or bin/Release folder, ready for execution or further steps like packaging.

Try It Yourself!: Run dotnet build /bl in your project directory. It generates a detailed binary log (msbuild.binlog) to visualise every step of the build process using tools like MSBuild Log Viewer.

Key Concepts in the .NET Build System

To better understand the inner workings of dotnet build, here are some essential concepts to keep in mind:

MSBuild: The engine behind the scenes. It orchestrates the build process, defining tasks and targets like compilation, packaging, and deployment.
Roslyn compiler translates your C# code into Intermediate Language (IL). IL is a platform-agnostic, low-level representation of your code. Think of it as a universal language for the .NET ecosystem, which is later executed by the .NET runtime.
.csproj (or other project files): These files define how the project is built, which files are included, and the dependencies it relies on.

Targets and Tasks: Targets are actions (like compiling or packaging), and tasks are individual steps within those targets. For instance, the CoreCompile target handles compiling the code, and the ResolveReferences task resolves external dependencies.

Why Does It Matter?

The .NET build system doesn’t just compile your code—it provides:

Automation: Eliminates manual compilation and dependency management.
Consistency: Ensures the same build process across all environments and team members.
Speed: Incremental builds make iterative development much faster.
Scalability: Handles complex projects with multiple files, dependencies, and configurations effortlessly.

Without it, modern development would be chaotic and slow, making build systems indispensable for developers.

A Simple Example: Building a .NET Project

Let’s look at a simple example to demonstrate how this works in practice:

Project Structure
Consider the following project structure:

MyApp/
├── MyApp.csproj
├── Program.cs
└── Dependencies/
    └── MyLibrary.cs

Project File (MyApp.csproj)
The MyApp.csproj file defines how the project should be built:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="Dependencies\MyLibrary.csproj" />
  </ItemGroup>
</Project>

Running dotnet build
When you run dotnet build from the project root, it will:
- Parse MyApp.csproj to gather all the build information.
- Restore any necessary dependencies (including MyLibrary).
- Compile the source files and link them into an executable (MyApp.exe).
- Place the output in the bin/Debug directory.

Final Thoughts

Next time you press “Build Solution” or run dotnet build, remember the intricate dance happening behind the scenes. Build systems like MSBuild are the unsung heroes of software development, quietly ensuring that your code compiles, links, and packages correctly every single time.

Understanding how these systems work not only helps you appreciate their complexity but also empowers you to troubleshoot and optimise your development workflow. So, take a moment to thank your build system; it’s doing a lot more than you think. 😊

Key Takeaways:

Build systems automate and simplify the transformation of code into applications.
MSBuild is the heart of the .NET build ecosystem, making dotnet build powerful and flexible.
Learning how your build system works can help you troubleshoot, optimise, and streamline your workflow.

What’s your experience with dotnet build? Have you customised your builds or debugged complex issues? Let’s share stories and insights in the comments! 🚀