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

The same program, published three ways on this machine
ShapeWhat is in the folderSize
framework-dependent5 files, the program is app.dll4.5 KB of program, 97 KB with the launcher
self-contained192 files79 MB
single file1 file plus the .pdb73 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

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

  1. Publish the program framework-dependent and run it on a machine with an older runtime. What does the launcher say?
  2. Compare du -sh of the self-contained folder with the sum of ls -l. Why do the two differ?
  3. Publish with -p:PublishSingleFile=true and no -r. Which error does the SDK give?
  4. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. What does dotnet publish -c Release -o out write 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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