What a bundle is
dotnet publish -p:PublishSingleFile=true turns an application into one executable. The file is not a .NET assembly: it is the apphost, a small native executable (a Mach-O file on macOS, an ELF file on Linux, a PE file on Windows; for a self-contained
application the host that also holds the runtime), with the files of the application written after it, then a bundle header and its manifest. The host finds the bundle through a marker inside itself and reads the manifest to learn which files it holds and where.
The assemblies are then loaded from the file without being extracted.
Layout
Apphostthe native executable, with the 8-byte bundle header offset and the 32-byte signature somewhere inside itfrom byte 0Filesthe application’s files one after another: assemblies, the.deps.jsonand.runtimeconfig.json, native libraries and content files, each stored as it is or Deflate-compressed; on macOS each starts on a page boundary (4096)offset in the manifestBundle headerthe version, the number of files, the bundle ID, the positions of the two JSON files and the flagsat the header offsetManifestone entry for each fileafter the headerTraileron macOS the code signature of the executableto the end
The marker in the apphost
The apphost template that the SDK starts from contains 40 bytes: 8 zero bytes and then the 32-byte SHA-256 hash of the text .net core bundle
(8B 12 02 B9 6A 61 20 38 72 7B 93 02 14 D7 A0 32 13 F5 B9 E6 EF AE 33 18 EE 3B 2D CE 24 B3 6A AE). Bundling writes the offset of the bundle header over the 8 zero bytes. A host that finds a zero there is not bundled. The explorer finds the marker by searching the whole file and reads the 8 bytes before it as a signed 64-bit offset.
An apphost with the marker and a zero offset is shown as an apphost without a bundle.
The header
| Field | Size | Meaning |
|---|---|---|
| Major version, minor version | 4 + 4 | 6 and 0 in every bundle made by .NET 6 and later (the 10.0 SDK writes 6.0) |
| File count | 4 | the number of entries in the manifest |
| Bundle ID | 1 + n | a length (7 bits at a time) and UTF-8, 12 characters in the files made here; when an application has to extract files, it extracts them into a folder of this name |
| Deps.json offset, size | 8 + 8 | where the .deps.json file is in the bundle (from format version 2 on) |
| Runtimeconfig.json offset, size | 8 + 8 | where the .runtimeconfig.json file is |
| Flags | 8 | bit 0: netcoreapp3 compatibility mode, in which every file is extracted to run (IncludeAllContentForSelfExtract) |
Each file entry of the manifest: the offset of the file in the bundle file (8 bytes), its size (8), from version 6 on its compressed size (8; 0 when the file is stored as it is), a type byte (0 unknown, 1 assembly, 2 native binary, 3 deps.json, 4 runtimeconfig.json, 5 symbols) and its path (a length and UTF-8,
with / as separator). A compressed file is a raw Deflate stream (EnableCompressionInSingleFile: in the two self-contained bundles made here with it every assembly is compressed, 175 files each, and no other file). Versions before 6 (.NET Core 3.x has 1.0, .NET 5 has 2.0) have no compressed size in the entries; the explorer follows that layout but no bundle of those versions was available to check it.
What the explorer shows
- The Apphost with the bundle header offset and the signature as nodes, each file as a node that opens as a file of its own (an assembly in the .NET viewer, JSON as text, a compressed file decompressed first), the bundle header with its fields and the manifest entry by entry, and what follows the bundle.
- The Bundle section (version, ID, flags, file counts and sizes) and the Files table.
Identify finds a bundle by its signature, which is how an extensionless executable (the usual name on macOS and Linux) is recognised. A Windows .exe is opened by the PE viewer first, which does not offer the bundle view yet.
Checked with bundles the .NET SDK wrote: 7 bundles (framework-dependent for macOS arm64, Windows x64 and Linux x64; self-contained with and without compression; with IncludeAllContentForSelfExtract), 553 file entries, 350 of them compressed. Every entry equals the file it was made from byte for byte (546 against the
build output or the runtime pack; the generated deps.json is checked as JSON naming the application), the 5 bundles that can run on this Mac (not the Windows and Linux ones) run and print what their code computes, and for the two published to be extracted the host’s own extraction (a folder named by the bundle ID, 184 files) equals our entries and our ID. The marker is also found in the SDK’s unbundled apphost with a zero offset.
Not described
Known, not yet covered
- Reference: bundle versions 1 and 2 (.NET Core 3.x and .NET 5) are read from the design documents but no such bundle could be made or found to check them; the native executable inside the bundle (Mach-O, ELF or PE) is not described here (see the executable viewers); the older single-file packers that merged assemblies with a tool such as ILMerge, and Mono AOT images, are other things.
- Viewer: the code signature at the end of a macOS executable is shown as bytes; a Windows bundle opens in the PE viewer first.
Unknown
- Reference: what the flag bits above 0 mean: the runtime’s headers define only bit 0 in the version the SDK writes.
Links
Reference
- Single-file bundler design – the runtime’s description of the bundle format
- Single-file deployment – how to publish one