Single-file deployment

2024-10-15

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. 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 is large since it includes the runtime and the framework libraries. In .NET 6, you can publish trimmed to reduce the total size of trim-compatible applications. The single file deployment option can be combined with ReadyToRun and Trim publish options.

Important

To run a single file app on Windows 7, you must use .NET Runtime 6.0.3 or later.

Sample project file

Here's a sample project file that specifies single file publishing:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <PublishSingleFile>true</PublishSingleFile>
    <SelfContained>true</SelfContained>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  </PropertyGroup>

</Project>

These properties have the following functions:

PublishSingleFile. Enables single file publishing. Also enables single file warnings during dotnet build.
SelfContained. Determines whether the app is self-contained or framework-dependent.
RuntimeIdentifier. Specifies the OS and CPU type you're targeting. Also sets <SelfContained>true</SelfContained> by default.

Single file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth.

Runtime configuration files, such as *.runtimeconfig.json and *.deps.json, are included in the single file.

Publish a single file application using the dotnet publish command.

Add <PublishSingleFile>true</PublishSingleFile> to your project file.

This change produces a single file app on self-contained publish. It also shows single file compatibility warnings during build.
```
<PropertyGroup>
    <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>
```
Publish the app for a specific runtime identifier using dotnet publish -r <RID>

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

dotnet publish -r win-x64

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

dotnet publish -r linux-x64 --self-contained false

<PublishSingleFile> should be set in the project file to enable file analysis during build, but it's also possible to pass these options as dotnet publish arguments:

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

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

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

Add <PublishSingleFile>true</PublishSingleFile> to your project file.
On the Solution Explorer pane, right-click on the project you want to publish. Select Publish.

If you don't already have a publishing profile, follow the instructions to create one and choose the Folder target-type.
Choose Edit.
In the Profile settings dialog, set the following options:
- Set Deployment mode to Self-contained or Framework-dependent.
- Set Target runtime to the platform you want to publish to. Must be something other than Portable.
- Select Produce single file.
Choose Save to save the settings and return to the Publish dialog.
Choose Publish to publish your app as a single file.

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

Exclude files from being embedded

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

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

For example, to place some files in the publish directory but not bundle them in the 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're part of the 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>

Other considerations

Single file applications have all related PDB files alongside the application, not bundled by default. If you want to include PDBs inside the assembly for projects you build, set the DebugType to embedded. See Include PDB files inside the bundle.

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

Native libraries

Only managed DLLs are bundled with the app into a single executable. When the app starts, the managed DLLs are extracted and loaded in memory, avoiding the extraction to a folder. With this approach, the managed binaries are embedded in the single file bundle, but the native binaries of the core runtime itself are separate files.

To embed those files for extraction and get one output file, set the property IncludeNativeLibrariesForSelfExtract to true.

Specifying IncludeAllContentForSelfExtract extracts all files, including the managed assemblies, before running the executable. This may be helpful for rare application compatibility problems.

Important

If extraction is used, the files are extracted to disk before the app starts:

If the DOTNET_BUNDLE_EXTRACT_BASE_DIR environment variable is set to a path, the files are extracted to a directory under that path.
Otherwise, if running on Linux or macOS, the files are extracted to a directory under $HOME/.net.
If running on Windows, the files are extracted to a directory under %TEMP%/.net.

To prevent tampering, these directories shouldn't be writable by users or services with different privileges. Don't use /tmp or /var/tmp on most Linux and macOS systems.

Note

In some Linux environments, such as under systemd, the default extraction doesn't work because $HOME isn't defined. In such cases, it's recommended that you set $DOTNET_BUNDLE_EXTRACT_BASE_DIR explicitly.

For systemd, a good alternative is to define DOTNET_BUNDLE_EXTRACT_BASE_DIR in your service's unit file as %h/.net, which systemd expands correctly to $HOME/.net for the account running the service.

[Service]
Environment="DOTNET_BUNDLE_EXTRACT_BASE_DIR=%h/.net"

API incompatibility

Some APIs aren't compatible with single file deployment. Applications might require modification if they use these APIs. If you use a third-party framework or package, it's possible that they might 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.CodeBase`	Throws PlatformNotSupportedException.
`Assembly.EscapedCodeBase`	Throws PlatformNotSupportedException.
`Assembly.GetFile`	Throws IOException.
`Assembly.GetFiles`	Throws IOException.
`Assembly.Location`	Returns an empty string.
`AssemblyName.CodeBase`	Returns `null`.
`AssemblyName.EscapedCodeBase`	Returns `null`.
`Module.FullyQualifiedName`	Returns a string with the value of `<Unknown>` or throws an exception.
`Marshal.GetHINSTANCE`	Returns -1.
`Module.Name`	Returns a string with the value of `<Unknown>`.

We have some recommendations for fixing common scenarios:

To access files next to the executable, use AppContext.BaseDirectory.
To find the file name of the executable, use the first element of Environment.GetCommandLineArgs(), or starting with .NET 6, use the file name from ProcessPath.
To avoid shipping loose files entirely, consider using embedded resources.

Post-processing binaries before bundling

Some workflows require post-processing of binaries before bundling. A common example is signing. The dotnet SDK provides MSBuild extension points to allow processing binaries just before single-file bundling. The available APIs are:

A target PrepareForBundle that will be called before GenerateSingleFileBundle
An <ItemGroup><FilesToBundle /></ItemGroup> containing all files that will be bundled
A Property AppHostFile that will specify the apphost template. Post-processing might want to exclude the apphost from processing.

To plug into this involves creating a target that will be executed between PrepareForBundle and GenerateSingleFileBundle.

Consider the following .NET project Target node example:

<Target Name="MySignedBundledFile" BeforeTargets="GenerateSingleFileBundle" DependsOnTargets="PrepareForBundle">

It's possible that tooling will need to copy files in the process of signing. That could happen if the original file is a shared item not owned by the build, for example, the file comes from a NuGet cache. In such a case, it's expected that the tool will modify the path of the corresponding FilesToBundle item to point to the modified copy.

Compress assemblies in single-file apps

Single-file apps can be created with compression enabled on the embedded assemblies. Set the EnableCompressionInSingleFile property to true. The single file that's produced will have all of the embedded assemblies compressed, which can significantly reduce the size of the executable.

Compression comes with a performance cost. On application start, the assemblies must be decompressed into memory, which takes some time. We recommend that you measure both the size change and startup cost of enabling compression before using it. The impact can vary significantly between different applications.

Inspect a single-file app

Single file apps can be inspected using the ILSpy tool. The tool can show all of the files bundled into the application and can inspect the contents of managed assemblies.

Share via