.NET Core 3 Single-file Executables

In .NET Core 3.0, the support for single-file applications is added.

Build System Interface

Publishing to a single file can be triggered by adding the following property to an application's project file:

<PropertyGroup>
    <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>    

• The PublishSingleFile property applies to both frameworks dependent and self-contained publish operations.
• The PublishSingleFile property applies to platform-specific builds for a given runtime-identifier.
• The output of the build is a native binary for the specified platform.
• When PublishSingleFile is set to true, it is an error to leave RuntimeIdentifier undefined, or to set UseAppHost to false.
• Setting the PublishSingleFileproperty causes the managed app, managed dependencies, platform-specific native dependencies, configurations, etc. to be embedded within the native apphost.

By default, the symbol files are not embedded within the single-file but remain as separate files in the publish directory. This includes both the IL .pdb file, and the native .ni.pdb / app.guid.map files generated by ready-to-run compiler. Setting the following property causes the symbol files to be included in the single-file.

<PropertyGroup>
    <IncludeSymbolsInSingleFile>true</IncludeSymbolsInSingleFile>
</PropertyGroup>

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

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

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

<ItemGroup>
  <Content Update="*.xml">
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
  </Content>
</ItemGroup>

The dotnet publish command supports packaging your app into a platform-specific single-file executable.

• The executable is self-extracting and contains all dependencies that are required to run your app.
• When you run the application for the first time, the application is extracted to a directory based on the app name and build identifier.
• Startup is faster when the application is run again, the application doesn't need to extract itself a second time unless a new version was used.

To publish a single-file executable, set the PublishSingleFile in your project file as shown below.

<PropertyGroup>
  <RuntimeIdentifier>win10-x64</RuntimeIdentifier>
  <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>

Or you can run the dotnet publish from the command line as shown below.

dotnet publish -r win10-x64 -p:PublishSingleFile=true