Support Single-File Apps in .NET 5

[swaroop-sridhar]

The goal of this effort is enable .Net-Core apps to be published and distributed as a single executable.

Goals

The .Net 5.0 single file solution should be:

• Widely compatible: Apps containing IL assemblies, ready-to-run assemblies, composite assemblies, native binaries, configuration files, etc. can be packaged into one executable.
• Can run managed components of the app directly from bundle, without need for extraction to disk.
• Usable with debuggers and tools.

User Experience

Here's the overall experience for publishing a HelloWorld single-file app in .net 5:

• Framework-dependent

  • Publish command: dotnet publish -r win-x64 --self-contained=false /p:PublishSingleFile=true
  • Published files: HelloWorld.exe, HelloWorld.pdb

• Self-contained (Linux)

  • Publish command: dotnet publish -r linux-x64 /p:PublishSingleFile=true
  • Published files: HelloWorld, HelloWorld.pdb

• Self-contained (Windows):

  • Publish command: dotnet publish -r win-x64 /p:PublishSingleFile=true
  • Published files: HelloWorld.exe, HelloWorld.pdb, coreclr.dll, clrjit.dll, clrcompression.dll, mscordaccore.dll

• Self-contained (Windows) with bundled native components:

  • Publish command: dotnet publish -r win-x64 /p:PublishSingleFile=true /p:IncludeNativeLibrariesInSingleFile=true
  • Published files: HelloWorld.exe, HelloWorld.pdb

Design Document

A detailed discussion of the goals, non-goals, related-work, options, design decisions, and implementation details of supporting single-file apps is available in this design document

Tracking Progress

• Initial proposal and poll for customer response:
  • Poll on GitHub: Support single-file distribution #11201
  • Enterprise customer poll
• Propose staged implementation of the feature.
• Support single-file apps through extraction (.net core 3)
  • Self-Extractor Design.
  • SDK support for publishing apps as a single-file. Publish to Single-File sdk#3132
  • AppHost support for extracting contents of a single-file bundle at startup. AppHost: Support bundles (stage 1) core-setup#5742
• Support single-file apps running from bundle (.net 5)
  • HostModel library
    • Implement bundle format version 2. AppHost: Support bundles (stage 1) core-setup#5742
  • SDK
    • Implement support for publishing a few files when necessary for PublishSingleFile. Single-File: Update Bundler Invocation. sdk#11586
    • Implement optional settings for single-file publishing. Use SingleFileHost sdk#11797
    • Use SingleFileHost when publishing self-contained single-file apps. Use SingleFileHost for self-contained single-file apps sdk#11567 Use SingleFileHost sdk#11797
    • Trim the set of native dependencies used for single-file publish. Produce DropFromSingleFile annotations in RuntimeList.xml #36578 Use SingleFileHost sdk#11797
  • Host
    • Move bundle-processing from the host to the framework . Single-File: Process bundles in the framework #34274
    • Process deps.json and runtimeconfig.json files directly from bundle. Single-File: Process bundles in the framework #34274
    • Implement a callback for the runtime to probe the contents of the bundle. Single-File: Pass BUNDLE_PROBE property to the runtime #34845
  • Host Builds
    • Windows: Implement SingleFileHost with AppHost, HostFxr, and HostPolicy statically linked. Single-File: Implement statically linked apphost #32823 Build an apphost with hostfxr and hostpolicy linked in #36230
    • Linux: Implement SingleFileHost with host and runtime components statically linked.
      • Statically link CoreCLR and ClrJIT with SingleFileHost Single-File: Implement Linux SingleFileHost with statically linked runtime #37119 Host with coreclr linked in #36847
      • Statically link core native libraries with SingleFileHost SingleFile: Statically link core native libraries to Linux SingleFileHost #38304
  • Runtime
    • Load assemblies directly from bundle. Single-File: Implement loading assemblies from bundle #32822 Single-File: Run from Bundle #36052
    • Dependency resolution: Resolve assemblies from bundle. Single-File: Run from Bundle #36052
  • APIs
    • AppContext.BaseDirectory should return the location of the single-file executable Single-File: Process bundles in the framework #34274

Tagging subscribers to this area: @swaroop-sridhar
Notify danmosemsft if you want to be subscribed.

[YZahringer]

Single-File deployment support for IIS and Azure Web Apps is planned? Related to dotnet/aspnetcore#14473

[psmulovics]

Any chance of implementing this to be single file app for windows?

[swaroop-sridhar]

@YZahringer Loading single-file apps out-of-proc by IIS should be supported. However, loading single-file apps in-proc is not planned for .net 5.

In a single-file app, since host-components (hostfxr. hostpolicy) don't exist as real files on disk, in-process loading of such apps require a new build configuration. That is:

• ASP.NET would need to produce a unmanaged .dll that is a combination of the IIS module and the single file host.
• SDK would need to allow customization of the single file host to use.

[swaroop-sridhar]

Here's the Table of supported host configuration, thanks to @vitek-karas

FD = Framework Dependent
SD = Self-Contained

App	Normal FD	Normal SC	Single-File 3.1 FD	Single-File 3.1 SC	Single-File 5.0 FD	Single-File 5.0 SC
.exe app	Yes	Yes	Yes	Yes	Yes	Yes
Native hosting app (IIS scenario)	Yes	Yes	Not Planned	Not Planned (complex)	Not Planned	Not Planned (needs new build config)
Native hosting component (assembly) (COM server, plugins, …)	Yes	No (desire exists)	Not Planned	Not Planned	Not Planned	Not Planned
Load a plugin	Yes	Yes	Yes	Yes	Yes	Yes

[swaroop-sridhar]

@psmulovics: Are you asking about Asp.net/IIS issue, or Windows single-file apps in general?
Yes this feature is planned for Windows. Please see the notes in the "User Experience" section, and this design doc. Thanks.

[YZahringer]

@swaroop-sridhar thank you for the answer and the details. This is not blocking, but the structure of the deployed files is not very "clean" at the moment.

When deployed in Self-contained mode, I have 313 .NET Framework files at root folder of my AzureWebApp/IIS website. It's a bit messy and it can cause human errors during updates or complicate the editing of configuration files like appsettings.json and web.config. Previously with ASP.NET 4, these files are in a bin folder, no binary at the root and more clean.

It might be cleaner/magic with a Single-File deployed 😉

[davidfowl]

@YZahringer unfortunately IIS in process doesn't support single file. Out of process does.