Single file, trimming, ClickOnce and signing

Three things happen between a published folder and a program a user installs: the files are packed into one exe or left as a folder, the unused code is or is not removed, and the result is or is not signed. Each has a limit for WinForms, and two of them cannot be exercised in this container, because they need the Windows runtime packs and the Windows SDK. This lesson shows what it can and states the rest as the documented behaviour it is.

The application and its folder

A form that prints the two values every deployment changes: the product version the package declares and the folder the application runs from. 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 = "Where am I"; ClientSize = new Size(460, 120); var version = new Label { Text = $"Version {Application.ProductVersion}", Location = new Point(16, 16), AutoSize = true, }; var folder = new Label { Text = AppContext.BaseDirectory, Location = new Point(16, 48), AutoSize = true, }; Controls.Add(version); Controls.Add(folder); } }

dotnet build app.csproj

Build succeeded.
    0 Warning(s)
    0 Error(s)

The listing is built and not run. The version comes from the assembly metadata the SDK generates, and a package that declares its own version changes what the label shows. AppContext.BaseDirectory is the folder the runtime considers the application's own, and it is the property to use when a data file has to sit next to the program: it is right in a normal folder, in a single-file bundle and in a ClickOnce cache, while Application.ExecutablePath names the exe file itself and is not the base for data files in every deployment.

Single file

PublishSingleFile bundles the application, its dependencies and the runtime into one executable. It needs a runtime identifier, because the bundle contains native code for one platform. Without one, the SDK picks the current platform, and here that is linux-musl-x64, whose runtime packs the offline feed does not have:

dotnet publish app.csproj -c Release -p:PublishSingleFile=true -o publish-single

  Determining projects to restore...
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.NET.ILLink.Tasks. No packages exist with this id in source(s): local
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.NETCore.App.Runtime.linux-musl-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.linux-musl-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.linux-musl-x64. No packages exist with this id in source(s): local
  Failed to restore /tmp/wf/wf/app.csproj (in 461 ms).

The publish exited 1. The first line is the one to learn from: PublishSingleFile turns on the single-file analyzer, and the analyzer needs the ILLink task package, which the offline feed does not hold. The other three are the runtime packs of the current platform: with no runtime identifier the SDK infers the one it is running on. With -r win-x64 the same publish asks for the win-x64 packs instead, and on a machine with network access it produces a single app.exe of over a hundred megabytes.

Single file is a deployment convenience, not a code change. Two details matter to a WinForms application. The managed assemblies load from the bundle, but a native library is a separate file next to the exe unless IncludeNativeLibrariesForSelfExtract is set, in which case it travels inside the exe and is extracted to a temporary folder at run time; "one file" is literal on disk only in that second case, at the cost of a larger exe and a slower first start. And Assembly.Location is empty in a single-file bundle, so code that looks for a file next to the program uses AppContext.BaseDirectory.

Trimming and WinForms

The trimmer removes code the compiler can prove is unreachable. It follows calls and type references, and it cannot see through reflection: a type loaded by name, a property read by name, a method called by a string. A WinForms form is built on exactly that kind of reflection:

The .NET 10 SDK does allow PublishTrimmed for a WinForms application, and it reacts by switching off the features it cannot trim: data-binding support, the UI type editors, ActiveX, the design-time features, the MDI window dialogs and the image index converter all become feature switches that are turned off in the published runtime configuration. What survives is a form whose designer code and bindings may still fail at run time, which is why a designer-heavy application is rarely trimmed. The output here stops earlier, at the restore of the runtime packs:

dotnet publish app.csproj -c Release -r win-x64 -p:PublishTrimmed=true --self-contained true -o publish-trim

  Determining projects to restore...
/tmp/wf/wf/app.csproj : error NU1101: Unable to find package Microsoft.NET.ILLink.Tasks. No packages exist with this id in source(s): local
/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 486 ms).

The project has no network, so the run cannot reach the trimmer at all. On a machine with the packs the publish would continue, the trimmer would run, and the feature switches above would be off in the output. The answer for most applications is still PublishTrimmed=false, which is the default: a self-contained publish keeps the whole runtime, and a framework-dependent one is small anyway.

The one place where trimming can be enabled is a library that a WinForms application references, if the library is annotated for trimming and never reflects over the application. That is a decision for a library author, not a setting to switch on in the application's project file.

ClickOnce

ClickOnce is the installer-less deployment of the .NET Framework era, still supported for .NET on Windows. The user installs an application from a URL or a folder, gets a shortcut and a Start menu entry, and later starts get the new version automatically when it is published again. Nothing is built here: the tooling is the Microsoft.NET.Sdk.Publish targets and the MSBuild task GenerateDeploymentManifest, and it needs Windows and, for a smooth install, a signing certificate.

What a ClickOnce publish writes: an application manifest, a deployment manifest, the application files, and a setup.exe bootstrapper. The manifests describe the identity, the version and the files with their hashes, and the deployment manifest names the update location. The install lives in a per-user cache, not in Program Files, which is why it needs no administrator.

The limits are worth knowing before choosing it. The application runs from the cache, so writing next to the exe is not allowed; user data goes to %LOCALAPPDATA%. A framework-dependent ClickOnce app needs the desktop runtime, which the bootstrapper can install. And the manifests have to be signed, or the install prompts with an unknown publisher; a self-signed certificate works on the machine that trusts it and nowhere else.

MSIX

MSIX is the modern Windows package format: a signed container with an identity, an application manifest, the files, and a set of capabilities. It installs per user or per machine, updates through the package manager, and uninstalls cleanly. A WinForms application is packaged as an MSIX with a Windows Application Packaging Project in Visual Studio, or with MakeAppx from the Windows SDK; neither exists in this container.

What the package adds: a real identity (name, publisher, version) that the system enforces, a declared architecture, and a signature from a certificate the machine trusts. What it constrains: the install location is managed, writes to the package folder are virtualised, and some Win32 APIs are unavailable or need a capability. A desktop application that writes to its own folder has to be changed before it can be packaged, which is a design issue and not a packaging one.

MSIX and ClickOnce solve the same problem in different eras. ClickOnce is simpler and older and its update model is its own; MSIX is the system format, with a cleaner identity and uninstall, and a heavier toolchain. An internal tool that is copied to a folder is still a valid third option.

Code signing

A code signature is an Authenticode signature over the binary: a hash of the file, encrypted with the private key of a certificate, plus the certificate chain. Windows verifies it when the file runs, SmartScreen uses the reputation of the certificate and the file, and a signed installer shows the publisher instead of "Unknown publisher".

None of this can be run here: signtool is part of the Windows SDK and there is no certificate. The install route is the Windows SDK, a certificate, and the command above on the machine that publishes; the container can only build the unsigned files, which is what the publish of lesson 066 produced.

Exercises

  1. Add -p:IncludeNativeLibrariesForSelfExtract=true to the single-file command and explain which error changes.
  2. List three places in this course where a property is addressed by a string, and say why each is invisible to the trimmer.
  3. Explain the difference between what a signature proves and what SmartScreen reputation adds.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does a single-file publish need that a framework-dependent one does not?

    Answer

    A runtime identifier

    The bundle contains native code for one platform.

  2. Which package did the single-file publish ask for first?

    Answer

    Microsoft.NET.ILLink.Tasks

    Bundling includes a trimming step for the host.

  3. Which platform did the single-file publish target without a RID?

    Answer

    linux-musl-x64, the current platform

    The errors name linux-musl-x64 packs.

  4. Why does trimming fight WinForms?

    Answer

    Designer serialisation and binding address members by name, which the trimmer cannot see

    Reflection is the trimmer's blind spot.

  5. What does PublishTrimmed=true do to a WinForms application?

    Answer

    It turns off features the trimmer cannot see, such as data-binding support

    The SDK maps the unsupported features to off switches in the runtime configuration.

  6. Where does a ClickOnce application install?

    Answer

    A per-user cache, not Program Files

    That is why it needs no administrator.

  7. Which files does a ClickOnce publish write?

    Answer

    Application and deployment manifests, the files and a bootstrapper

    The two manifests are what make the install and the update work.

  8. What does an MSIX package add over a folder?

    Answer

    A signed identity, a declared architecture and a clean uninstall

    The system enforces the package identity.

  9. What does a code signature prove?

    Answer

    The file is the one the key holder signed and has not changed

    Safety and honesty are not properties of a signature.

  10. Why does a signature carry a timestamp?

    Answer

    The signature stays valid after the certificate expires

    The timestamp records when the signature was made.

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 error output above is their real output.

Article author: Arthur Isaev

Banner image