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:
These properties have the following functions:
PublishSingleFile. Enables single file publishing. Also enables single file warnings during
SelfContained. Determines whether the app is self-contained or framework-dependent.
RuntimeIdentifier. Specifies the OS and CPU type you're targeting. Also sets
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. If an extra configuration file is needed, you can place it beside the single file.
Publish a single-file app
Publish a single file application using the dotnet publish command.
<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.
Exclude files from being embedded
Certain files can be explicitly excluded from being embedded in the single file by setting the following metadata:
For example, to place some files in the publish directory but not bundle them in the file:
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:
For example, add the following property to the project file of an assembly to embed the PDB file to that assembly:
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
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.
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
IncludeAllContentForSelfExtract extracts all files, including the managed assemblies, before running the executable. This may be helpful for rare application compatibility problems.
If extraction is used, the files are extracted to disk before the app starts:
- If the
DOTNET_BUNDLE_EXTRACT_BASE_DIRenvironment 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
- If running on Windows, the files are extracted to a directory under
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.
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
systemd, a good alternative is to define
DOTNET_BUNDLE_EXTRACT_BASE_DIR in your service's unit file as
systemd expands correctly to
$HOME/.net for the account running the service.
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.
|Returns an empty string.
|Returns a string with the value of
<Unknown> or throws an exception.
|Returns a string with the value of
We have some recommendations for fixing common scenarios:
To access files next to the executable, use AppContext.BaseDirectory.
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
PrepareForBundlethat will be called before
<ItemGroup><FilesToBundle /></ItemGroup>containing all files that will be bundled
- A Property
AppHostFilethat 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
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.