Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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.
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.
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>
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>
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.
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:
DOTNET_BUNDLE_EXTRACT_BASE_DIR
environment variable is set to a path, the files are extracted to a directory under that path.$HOME/.net
.%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"
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.
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:
PrepareForBundle
that will be called before GenerateSingleFileBundle
<ItemGroup><FilesToBundle /></ItemGroup>
containing all files that will be bundledAppHostFile
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.
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.
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.
.NET feedback
.NET is an open source project. Select a link to provide feedback:
Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Publish an ASP.NET Core app - Training
Learn how to publish an ASP.NET Core app for deployment to a web server or cloud service.
Documentation
ReadyToRun deployment overview - .NET
Learn what ReadyToRun deployments are and why you should consider using it as part of the publishing your app with .NET 5 and .NET Core 3.0 and later.
Runtime roll forward for .NET Core self-contained app deployments. - .NET
Learn about dotnet publish changes for self-contained deployments.
Trim self-contained applications - .NET
Learn how to trim self-contained apps to reduce their size. .NET Core bundles the runtime with an app that is published self-contained and generally includes more of the runtime than is necessary.