Burn packages, payloads and containers.

shipping containersIn my previous blog post where I introduced some of the features of Burn the question whether Burn would work as a single self extracting executable was asked a few times. The answer is, "Of course!" but there is actually more to it than that.

I debated listing "containers" as a feature in the previous blog post. Looking at the comments, it's pretty clear I should have. The "container" concept is still under some design tweaks but it is shaping up to be quite a powerful concept (and it addresses the question many asked).

So let me walk you through the list of primitives that Burn will process and how they stack together.


A package is a unit of change (install, repair, patch, uninstall) for the bootstrapper. Packages are members of a chain that the bootstrapper manages. There must be at least one package or the bootstrapper has no work to do. Each package has an implicit payload that is the entry point for the change (for example, an .MSI file or .EXE file). Additional payloads and containers may be referenced by a package.


A payload is a file that contains data required by a package. The bootstrapper treats payloads as opaque blobs therefore there are no bootstrap related requirements for payloads. Payloads may be found as loose files outside the bootstrapper or combined with zero or more payloads in a container.


Containers are a way of combining one or more payloads into a single file. Usually containers are used compress the contained payloads to make the total distribution size smaller. Sometimes containers are used simply to minimize the number of files that must be distributed with the bootstrapper. The bootstrapper controls the format of the containers and is responsible for extracting payloads out of the containers during the cache phase.

The ideal container file format will optionally compress various file types well, support digital signatures and scale to very large file sizes while containing many payloads.

Attached container

An attached container is found at a specified offset in the bootstrapper itself. The container is called attached instead of embedded because it is found at the end of the bootstrapper, after all of the executable code and resources. There can be only one attached container. When the bootstrapper is signed the attached container is included in that signature.

It is expected many small products (< 300 MB when compressed) will distribute a single file bootstrapper where all of the product's payloads are compressed into the attached container.

Detached containers

A detached container exists as a file outside the bootstrapper. The bootstrapper manifest can reference any number of detached containers. Detached containers are highly recommended when the combined size of the bootstrapper plus attached container would exceed 300 MB. Larger executable files experience poor start up performance on Windows leading to a less than ideal user experience.

Detached containers can also be used to optimize download scenarios because the bootstrapper will only request the containers referenced by packages being cached. For example, a very small bootstrapper would provide the optimal download + start up user experience then provide a custom user interface while the minimal number of detached containers are downloaded from the Internet.

Also note that if there are very few payloads and they are already compressed, it may be optimal to forego the use of detached containers completely. Containers do add overhead because they must first be downloaded before the payloads are extracted which requires more disk space and file I/O than simply caching the payloads directly.


The goal in Burn is to provide enough flexibility to meet everyone's needs. The WiX toolset will ship the tools necessary to create and bundle these primitives together. Ultimately, the decision how to organize your content into packages, payloads and containers is up to you.

I know there are many other questions about Burn. I'll get to them as soon.


FireGiant provides dedicated support for the WiX toolset. Ever wish you could get your WiX questions answered immediately with the technical detail that you find in the blog posts here? You can with FireGiant!

Send a comment

Thank you for sending your comment.