Understanding dotnet build vs. dotnet publish

When you are working with .NET from the command line, two of the most fundamental commands you will use are dotnet build and dotnet publish. While they might seem similar, they serve two very different purposes in the development lifecycle.

Understanding the difference is key to correctly compiling and deploying your .NET applications.

dotnet build

The dotnet build command compiles your project and its dependencies into a set of binary files. Its primary purpose is to build your source code into something that can be run.

When you run dotnet build, the following happens:

1. Your C# source code (.cs files) is compiled into Intermediate Language (IL) and placed in DLL files.
2. The build output is placed in the bin/Debug/<target-framework> directory by default.

This output in the bin folder is not a complete, runnable application. It contains your compiled code and the dependencies needed to run it, but it's not optimized or packaged for deployment. It often contains extra files that are only needed for debugging.

When to use dotnet build:

You use dotnet build during development to compile your code and check for compilation errors. It's the command you run frequently to ensure your code is valid before you run or debug it.

dotnet publish

The dotnet publish command prepares your application for deployment. Its purpose is to create a complete, self-contained package of your application that can be deployed to a hosting environment (like a server or a cloud service).

When you run dotnet publish, it does everything dotnet build does, and then it goes further:

1. It compiles your code.
2. It reads your project file to determine the dependencies your application needs to run.
3. It copies all of these dependencies from the NuGet cache into a single output folder.
4. It removes any unnecessary files that are not needed for deployment (like debugging symbols).
5. It generates a .deps.json file, which describes the application's dependencies, and a .runtimeconfig.json file, which specifies the runtime and its configuration.

By default, the output is placed in the bin/Debug/<target-framework>/publish directory.

The contents of this publish folder are all you need to deploy and run your application on a target machine.

When to use dotnet publish:

You use dotnet publish when you are ready to deploy your application. You run this command once at the end of your development or CI/CD process to create the final deployment artifact.

Deployment Modes

The dotnet publish command also allows you to control the deployment mode:

• Framework-Dependent (default): This creates a small package that includes your application and its dependencies but relies on a version of the .NET runtime being installed on the target machine.

• Self-Contained: This creates a much larger package that includes your application, its dependencies, and the .NET runtime itself. The advantage is that your application can run on a machine without needing to have .NET pre-installed.

You can create a self-contained publish by specifying a runtime identifier:

dotnet publish --runtime linux-x64

Summary

Here's a simple way to remember the difference:

• dotnet build is for developers. You use it during the development loop to compile your code.

• dotnet publish is for deployment. You use it when you are ready to ship your application.

Think of it like cooking. dotnet build is like preparing all your ingredients (compiling your code). dotnet publish is like putting all those ingredients together, cooking the final dish, and packing it up in a container, ready to be delivered.