Single file deployment and executable

Bundling all application-dependent files into a single binary provides an application developer with the attractive option to deploy and distribute the application as a single file. This deployment model has been available since .NET Core 3.0 and has been enhanced in .NET 5.0. Previously in .NET Core 3.0, when a user runs your single-file app, .NET Core host first extracts all files to a temporary directory before running the application. .NET 5.0 improves this experience by directly running the code without the need to extract the files from the app.

Single File deployment is available for both the framework-dependent deployment model and self-contained applications. The size of the single file in a self-contained application will be large since it will include the runtime and the framework libraries. The single file deployment option can be combined with ReadyToRun and Trim (an experimental feature in .NET 5.0) publish options.

API incompatibility

Some APIs are not compatible with single-file deployment and applications may require modification if they use these APIs. If you use a third-party framework or package, it's possible that they may also use one of these APIs and need modification. The most common cause of problems is dependence on file paths for files or DLLs shipped with the application.

The table below has the relevant runtime library API details for single-file use.

API Note
Assembly.Location Returns an empty string.
Module.FullyQualifiedName Returns a string with the value of <Unknown> or throws an exception.
Module.Name Returns a string with the value of <Unknown>.
Assembly.GetFile Throws IOException.
Assembly.GetFiles Throws IOException.
Assembly.CodeBase Throws PlatformNotSupportedException.
Assembly.EscapedCodeBase Throws PlatformNotSupportedException.
AssemblyName.CodeBase Returns null.
AssemblyName.EscapedCodeBase Returns null.

We have some recommendations for fixing common scenarios:

Attaching a debugger

On Linux, the only debugger which can attach to self-contained single-file processes or debug crash dumps is SOS with LLDB.

On Windows and Mac, Visual Studio and VS Code can be used to debug crash dumps. Attaching to a running self-contained single-file executable requires an extra file: mscordbi.{dll,so}.

Without this file Visual Studio may produce the error "Unable to attach to the process. A debug component is not installed." and VS Code may produce the error "Failed to attach to process: Unknown Error: 0x80131c3c."

To fix these errors, mscordbi needs to be copied next to the executable. mscordbi is published by default in the subdirectory with the application's runtime ID. So, for example, if one were to publish a self-contained single-file executable using the dotnet CLI for Windows using the parameters -r win-x64, the executable would be placed in bin/Debug/net5.0/win-x64/publish. A copy of mscordbi.dll would be present in bin/Debug/net5.0/win-x64.

Other considerations

Single-file doesn't bundle native libraries by default. On Linux, we prelink the runtime into the bundle and only application native libraries are deployed to the same directory as the single-file app. On Windows, we prelink only the hosting code and both the runtime and application native libraries are deployed to the same directory as the single-file app. This is to ensure a good debugging experience, which requires native files to be excluded from the single file. There is an option to set a flag, IncludeNativeLibrariesForSelfExtract, to include native libraries in the single file bundle, but these files will be extracted to a temporary directory in the client machine when the single file application is run.

Single-file application will have all related PDB files alongside it and will not be bundled by default. If you want to include PDBs inside the assembly for projects you build, set the DebugType to embedded as described below in detail.

Managed C++ components aren't well suited for single-file deployment and we recommend that you write applications in C# or another non-managed C++ language to be single-file compatible.

Exclude files from being embedded

Certain files can be explicitly excluded from being embedded in the single-file by setting following metadata:

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

For example, to place some files in the publish directory but not bundle them in the single-file:

<ItemGroup>
  <Content Update="Plugin.dll">
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
  </Content>
</ItemGroup>

Include PDB files inside the bundle

The PDB file for an assembly can be embedded into the assembly itself (the .dll) using the setting below. Since the symbols are part of the assembly, they will be part of the single-file application as well:

<DebugType>embedded</DebugType>

For example, add the following property to the project file of an assembly to embed the PDB file to that assembly:

<PropertyGroup>
  <DebugType>embedded</DebugType>
</PropertyGroup>

Publish a single file app - CLI

Publish a single file application using the dotnet publish command. When you publish your app, set the following properties:

  • Publish for a specific runtime: -r win-x64
  • Publish as a single-file: -p:PublishSingleFile=true

The following example publishes an app for Windows as a self-contained single file application.

dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained true

The following example publishes an app for Linux as a framework dependent single file application.

dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false

For more information, see Publish .NET Core apps with .NET Core CLI.

Publish a single file app - Visual Studio

Visual Studio creates reusable publishing profiles that control how your application is published.

  1. On the Solution Explorer pane, right-click on the project you want to publish. Select Publish.

    Solution Explorer with a right-click menu highlighting the Publish option.

    If you don't already have a publishing profile, follow the instructions to create one and choose the Folder target-type.

  2. Choose Edit.

    Visual studio publish profile with edit button.

  3. In the Profile settings dialog, set the following options:

    • Set Deployment mode to Self-contained.
    • Set Target runtime to the platform you want to publish to.
    • Select Produce single file.

    Choose Save to save the settings and return to the Publish dialog.

    Profile settings dialog with deployment mode, target runtime, and single file options highlighted.

  4. Choose Publish to publish your app as a single file.

For more information, see Publish .NET Core apps with Visual Studio.

Publish a single file app - Visual Studio for Mac

Visual Studio for Mac doesn't provide options to publish your app as a single file. You'll need to publish manually by following the instructions from the Publish a single file app - CLI section. For more information, see Publish .NET Core apps with .NET Core CLI.

See also