Publish modes
A build produces a program that runs on this machine with this SDK. A publish produces the files a user gets. There are two shapes: framework-dependent, which is small and needs the .NET Desktop Runtime on the machine, and self-contained, which carries the runtime and is large. This lesson publishes the same form both ways and shows the real result of each, including the one the offline feed cannot do.
Two publish modes
- Framework-dependent: the default. The output holds the application's own assemblies and a .runtimeconfig.json that names the frameworks it needs. The machine must have the .NET Desktop Runtime installed, in a compatible version. The folder is about 128 kilobytes, as the run below shows.
- Self-contained: the output holds the runtime as well. It needs a runtime identifier, -r win-x64 for a 64-bit Windows desktop, and the publish downloads the runtime packs for that identifier. The folder is over a hundred megabytes and the application runs on a machine with no .NET at all.
- The apphost: in both modes the SDK writes an app.exe for Windows, a small native launcher that starts the runtime and the managed assembly. It is why the user double-clicks an exe and not dotnet app.dll.
- Single file and trimming are options of a publish, and lesson 067 covers them; both need a runtime identifier and both have limits for WinForms.
The choice is a deployment decision, not a code decision: the same project and the same source produce either. What changes is who installs the runtime, and whether the application can assume a machine it does not control.
The application
A small notes window, the same kind of form as lesson 005, built and not run:
using System;
using System.Drawing;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
ApplicationConfiguration.Initialize();
Application.Run(new Form1());
}
}
internal sealed class Form1 : Form
{
public Form1()
{
Text = "Notes";
ClientSize = new Size(420, 240);
Controls.Add(new TextBox { Dock = DockStyle.Fill, Multiline = true });
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The listing is built and not run. The project file is the one of lesson 002, and the publish below uses the same folder.
A framework-dependent publish
No options beyond the configuration and an output folder:
dotnet publish app.csproj -c Release -o publish
Determining projects to restore...
All projects are up-to-date for restore.
app -> /tmp/wf/wf/bin/Release/net10.0-windows/app.dll
app -> /tmp/wf/wf/publish/
The paths are this machine's; on a reader's machine the project folder is wherever the project is. The publish exited 0. What it wrote is five files:
ls publish
app
app.deps.json
app.dll
app.pdb
app.runtimeconfig.json
And the size of the folder:
du -sh publish
128K publish
Read the five names. app.dll is the application. app.deps.json lists its dependencies, which here are the framework assemblies and nothing else. app.runtimeconfig.json names the frameworks and versions the runtime must find, and it is what a missing desktop runtime is reported against in lesson 008. app.pdb holds the debug symbols: useful for a crash report, harmless for a user, and often left out of a release. app is this machine's native apphost; a publish on Windows writes app.exe instead, because the apphost is per platform.
The size tells the story: 128 kilobytes is the application, not the framework. The machine that runs this folder must have the .NET Desktop Runtime, and the version in app.runtimeconfig.json is the one it asks for.
A win-x64 publish with the offline feed
The self-contained publish needs the runtime packs for win-x64: the .NET runtime, the Windows Desktop runtime, the ASP.NET Core runtime (the desktop framework pulls it in) and the apphost pack. The offline feed of this course holds exactly one package, the targeting pack, and a targeting pack is not a runtime. The real result:
dotnet publish app.csproj -c Release -r win-x64 --self-contained true -o publish-win
Determining projects to restore...
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.NETCore.App.Runtime.win-x64. No packages exist with this id in source(s): local
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.WindowsDesktop.App.Runtime.win-x64. No packages exist with this id in source(s): local
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.AspNetCore.App.Runtime.win-x64. No packages exist with this id in source(s): local
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.NETCore.App.Host.win-x64. No packages exist with this id in source(s): local
Failed to restore /tmp/wf/wf/app.csproj (in 482 ms).
The publish exited 1, and the four errors name the four packs. NU1101 means "no package with this id in any configured source", and the source list is the single word local from the nuget.config of lesson 007. The restore failed before anything was compiled, so publish-win does not exist.
On a machine with network access the same command succeeds against nuget.org: the four packs are downloaded, the output is over a hundred megabytes, and it runs on a Windows machine with no .NET installed. That is a deployment fact the container cannot show, and the course does not pretend otherwise. The install route for a reader who wants to see it is to remove the nuget.config or add nuget.org to it, and run the same command on Windows or with a network.
What a user needs
For a framework-dependent publish, three things: the folder, the desktop runtime, and a shortcut. The runtime installer is the Windows Desktop Runtime for the major version the application targets, distributed by Microsoft; the folder can be copied to any path, because nothing in it depends on where it was built. That is the whole of an xcopy deployment, and it is still the simplest way to ship an internal tool.
For a self-contained publish, the folder alone. It is larger, it carries its own runtime, and an update replaces the folder. The price is the size and the need to publish for every platform and architecture: a win-x64 publish does not run on win-arm64, and there is no "any Windows" runtime identifier.
Neither is an installer. ClickOnce, MSIX and an MSI wrap the folder with a shortcut, an update mechanism and a signature; lesson 067 describes them and says what cannot be built here.
Exercises
- Publish the form with -p:DebugType=none and check that the pdb disappears from the folder.
- Read app.runtimeconfig.json and name the framework and version the application asks for.
- Explain why the apphost in the publish folder is called app here and app.exe on Windows.
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 require on the user's machine?
Answer
The .NET Desktop Runtime in a compatible version
The output holds the application, not the framework.
-
What does a self-contained publish require?
Answer
A runtime identifier such as win-x64
The runtime packs are chosen by the RID.
-
How large was the framework-dependent publish folder in the run?
Answer
128K
du printed 128K for the five files.
-
Which file names the frameworks the runtime must find?
Answer
app.runtimeconfig.json
It is the file the missing-runtime message is about.
-
Which file lists the dependencies?
Answer
app.deps.json
The deps file is the dependency graph.
-
Which package did the win-x64 publish fail on first?
Answer
Microsoft.NETCore.App.Runtime.win-x64
It is the first of the four NU1101 lines.
-
What does NU1101 mean?
Answer
No package with that id exists in the configured sources
The offline feed holds only the targeting pack.
-
Why does the offline feed not help a self-contained publish?
Answer
It holds the targeting pack, not the runtime packs
A targeting pack is for compiling, a runtime pack is for running.
-
What is the apphost?
Answer
The small native launcher that starts the runtime and the assembly
It is why a user double-clicks an exe.
-
Why is the published apphost named app and not app.exe in the run?
Answer
The apphost is per platform, and this publish ran on Linux
A publish on Windows writes app.exe.
Every listing on this page was built with the .NET SDK 10.0.303 for net10.0-windows against the targeting pack Microsoft.WindowsDesktop.App.Ref 10.0.15 from the offline feed, in a Docker container on Alpine Linux 3.24.3 (x86_64). The programs were built, not run on Linux: WinForms needs Windows. The publish commands were run here as shown, and the output above is their real output.
Article author: Arthur Isaev