dotnet publish
Framework-dependent
dotnet publish writes a folder that can be copied to another machine and run. The program of this page reads the runtime it runs on, so the output of every shape is comparable:
using System.Runtime.InteropServices;
Console.WriteLine("published and running");
Console.WriteLine(RuntimeInformation.FrameworkDescription);
With no other option the publish is framework-dependent: the folder holds the assembly and a launcher, and the program needs the .NET runtime that is already installed on the target machine.
dotnet publish -c Release
Determining projects to restore...
Restored /tmp/cs/pub/app.csproj (in 407 ms).
app -> /tmp/cs/pub/bin/Release/net10.0/app.dll
app -> /tmp/cs/pub/bin/Release/net10.0/publish/
The folder holds five files, and the first is the launcher a shell runs:
-rwxr-xr-x 1 agent agent 92448 Nov 20 11:54 app
-rw-r--r-- 1 agent agent 381 Nov 20 11:54 app.deps.json
-rw-r--r-- 1 agent agent 4608 Nov 20 11:54 app.dll
-rw-r--r-- 1 agent agent 10812 Nov 20 11:54 app.pdb
-rw-r--r-- 1 agent agent 330 Nov 20 11:54 app.runtimeconfig.json
./bin/Release/net10.0/publish/app
published and running
.NET 10.0.15
The whole program is app.dll, four and a half kilobytes, and the runtime it needs is the 10.0.15 one that is installed. The .deps.json and .runtimeconfig.json are what the launcher reads to find that runtime, and the .pdb holds the debug symbols, which a release machine may leave behind.
Self-contained
-r names the runtime identifier and --self-contained puts the runtime into the folder, so the target machine needs nothing installed. The RID of this container is linux-musl-x64, the one dotnet --info reported.
dotnet publish -c Release -r linux-musl-x64 --self-contained -o sc
Restored /tmp/cs/pub/app.csproj (in 788 ms).
app -> /tmp/cs/pub/bin/Release/net10.0/linux-musl-x64/app.dll
app -> /tmp/cs/pub/sc/
du -sh sc
ls sc | wc -l
./sc/app
79M sc
192
published and running
.NET 10.0.15
192 files and 79 megabytes: the framework itself, copied next to the program. The restore took under a second because the runtime pack of this platform is already in /usr/lib/dotnet/packs; on a machine without it the same command downloads the pack.
Single file
-p:PublishSingleFile=true packs the self-contained output into one executable, which unpacks itself into a temporary folder at start.
dotnet publish -c Release -r linux-musl-x64 --self-contained -p:PublishSingleFile=true -o one
Restored /tmp/cs/pub/app.csproj (in 1.08 sec).
app -> /tmp/cs/pub/bin/Release/net10.0/linux-musl-x64/app.dll
app -> /tmp/cs/pub/one/
ls -l one
./one/app
-rwxr-xr-x 1 agent agent 73673518 Nov 20 11:55 app
-rw-r--r-- 1 agent agent 10824 Nov 20 11:55 app.pdb
published and running
.NET 10.0.15
One file of 73 673 518 bytes, and the same output. The .pdb is written next to it and can be dropped; without it the stack traces of an exception lose their line numbers, which is the trade a production build usually makes.
The three sizes
| Shape | What is in the folder | Size |
|---|---|---|
| framework-dependent | 5 files, the program is app.dll | 4.5 KB of program, 97 KB with the launcher |
| self-contained | 192 files | 79 MB |
| single file | 1 file plus the .pdb | 73 673 518 bytes, 71 MB |
The numbers are of this container and this program: 4 CPUs, the SDK 10.0.303, the runtime 10.0.15, Alpine Linux 3.24.3 on x86_64. A larger program adds kilobytes to the assembly and nothing to the runtime, which is why the self-contained size barely moves between programs.
Which one to ship
- A container image of a server takes the framework-dependent publish: the base image already holds the runtime, and the image stays small.
- A tool for a machine you do not control takes the self-contained or the single-file publish: nothing has to be installed first.
- A library is not published at all: it is packed with dotnet pack and referenced as a package, which the lesson on a library and the project that uses it shows from the project side.
Trimming and NativeAOT change these sizes again, and both are the subject of the lesson on trimming and NativeAOT, including the error this container gives for an AOT build.
Exercises
- Publish the program framework-dependent and run it on a machine with an older runtime. What does the launcher say?
- Compare du -sh of the self-contained folder with the sum of ls -l. Why do the two differ?
- Publish with -p:PublishSingleFile=true and no -r. Which error does the SDK give?
- Delete the .pdb and throw an exception in the program. Which part of the stack trace changes?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does a framework-dependent publish need on the target machine?
Answer
The .NET runtime, installed already
The folder holds the assembly and a launcher, and the launcher loads the shared runtime of the machine.
-
Which option puts the runtime into the published folder?
Answer
-r <RID> --self-contained
The runtime identifier plus --self-contained copies the runtime of that platform next to the program.
-
What does this program print?
using System.Runtime.InteropServices; Console.WriteLine(RuntimeInformation.FrameworkDescription);Answer
.NET 10.0.15
FrameworkDescription names the runtime, which is 10.0.15 here; 10.0.303 is the SDK and the RID is another property.
-
How large was the single-file publish of this page?
Answer
About 71 MB
The measured file was 73 673 518 bytes, and the self-contained folder of 192 files was 79 MB.
-
What does
dotnet publish -c Release -o outwrite into out?Answer
The publish folder of a framework-dependent build
Without -r and a self-contained flag the publish is framework-dependent, and -o names the folder it goes to.
-
What does the .runtimeconfig.json of a published program tell the launcher?
Answer
Which framework version to load
The launcher reads the runtime configuration to find the framework, and the .deps.json lists the assemblies of the program.
-
What does this program print?
var name = "app.dll"; Console.WriteLine(Path.GetFileNameWithoutExtension(name));Answer
app
GetFileNameWithoutExtension drops the folder and the extension, leaving the base name of the published assembly.
-
Why is a container image of a server usually built framework-dependent?
Answer
The base image already holds the runtime, so the image stays small
The runtime is in the base image either way, so copying 79 MB of it again only makes the image larger.
-
What does the .pdb file hold?
Answer
Debug symbols, which a stack trace needs for file names and line numbers
Without the .pdb a stack trace loses its line numbers, which is the usual trade of a release publish.
-
What is the difference between dotnet build and dotnet publish?
Answer
publish writes a folder that can be copied to another machine, build writes the output of this machine
A build produces the assembly in bin for local use; a publish resolves the files a deployment needs, including the runtime when asked.
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