Costura.Fody: embedding .NET dependencies as resources, and when it is the wrong tool

The problem Costura solves, and who is still meant to use it

A .NET build normally ships as an executable plus a folder of DLLs. If you want to hand someone one file, or if you are building a library that must not drag a chain of dependencies behind it, you need the dependencies inside the assembly. Costura does exactly that: it takes the assemblies marked Copy Local and the PDBs, embeds them as resources in the target assembly, and injects code that resolves a failed assembly load from those resources. The README describes the scope plainly: C# projects, library linking, exe linking, and Windows platforms. It also states that the maintainers have no experience with VB.NET and no intention of supporting it, and that Windows Services and non-Windows platforms are non-supported use cases. That list is not a marketing boundary, it is the set of cases the maintainers say they actually use, and they warn the list may become stricter over time.

How Costura embeds and resolves assemblies at module init

The mechanism is a combination of two ideas the README credits by name: Jeffrey Richter's suggestion of using embedded resources as a method of merging assemblies, and Einar Egilsson's suggestion of using Cecil to create module initializers. Concretely, the Fody task performs three changes. It takes every assembly and PDB marked Copy Local and embeds them as resources in the target assembly. It injects a module initializer that calls ILTemplate.Attach(), which the README shows as a static constructor calling into the template. And it injects the class from ILTemplate.cs (or ILTemplateWithTempAssembly.cs) so that when an assembly load fails, the assembly is loaded from the embedded resources instead. Embedded assemblies are compressed by default and decompressed when loaded, which is what DisableCompression turns off. The resolution hook is an event subscription: AppDomain.AssemblyResolve on .NET 4.x and AssemblyLoadContext.Resolving on .NET 6.0 and later. DisableEventSubscription removes that subscription, and the README restricts it to advanced scenarios such as plugins where only the host should resolve assemblies.

Installing Costura.Fody and getting a first embedded build

The README gives PowerShell package manager commands. Note its warning that Install-Package Fody is required separately, because NuGet defaults to the oldest version of any dependency.

PM> Install-Package Fody
PM> Install-Package Costura.Fody

After that, the weaver has to be listed in FodyWeavers.xml. The README shows the minimal file with an empty Costura node, which is the default configuration.

<Weavers>
  <Costura/>
</Weavers>

Build the project. According to the README, assemblies marked Copy Local are no longer included as part of the build output, because Costura treats them as embedded resources instead. If something else in your pipeline still expects those DLLs on disk, DisableCleanup turns that removal off. If a dependency expects to be loaded from a physical file rather than from memory, CreateTemporaryAssemblies copies the embedded files to disk before loading them; it defaults to false. Both are set as attributes on the Costura node, for example CreateTemporaryAssemblies='true'.

The configuration options that change behaviour most

UseRuntimeReferencePaths is the one most likely to surprise you, because its default is not the same everywhere. For a weaved assembly targeting .NET Framework it defaults to false; for .NET Core it defaults to true. The README walks through the consequence with a concrete example: the reference system.text.encoding.codepages\5.0.0\runtimes\win\lib\net461\System.Text.Encoding.CodePages.dll is embedded as costura.system.text.encoding.codepages.dll.compressed when the setting is false, so Costura loads it automatically. With the setting true it is embedded as costura.runtimes.win.lib.net461.system.text.encoding.codepages.dll.compressed, which the README says requires custom user code to load the embedded compressed assembly. IncludeRuntimeReferences controls whether the runtimes folder used by .NET Core is embedded at all and defaults to true. IgnoreSatelliteAssemblies defaults to false, meaning Costura treats assemblies named like resources.dll as satellite resources and prepends the output path; the README adds a specific warning that a DLL project whose assembly name ends in .resources will produce *.resources.dll and lead to errors when this flag is false. LoadAtModuleInit defaults to true; setting it to false means you must call CosturaUtility.Initialize() yourself.

Where Costura is the wrong tool

The README opens with a maintenance-mode notice and states that the value proposition of Costura is greatly diminished by two features that arrived in .NET Core 3: single-file executables and assembly linking. It strongly recommends trying those alternatives instead. That is the maintainers telling you to check the platform first. The second limitation is the supported-use-case list itself. VB.NET is out. Windows Services are out. Non-Windows platforms are out. If your project falls into one of those categories, the README offers no path. The third is subtler: because Costura resolves assemblies through an event subscription, DisableEventSubscription exists for plugin hosts where only the host should resolve assemblies, and the README marks that option for advanced scenarios only. If you are building a plugin that relies on the host's own resolution policy, the default behaviour is not what you want, and turning it off means the embedding is doing less work for you.

Costura against the .NET Core 3 single-file and assembly linking options

The real alternative is the one the README names: single-file executables and assembly linking in the .NET Core 3 tool set. The difference in approach matters. Costura is a Fody weaver, so it runs as an IL-weaving step inside your build and edits the assembly after compilation; it embeds Copy Local assemblies as resources and resolves them at runtime through an assembly-resolve event. The platform features are part of the tool set itself, so they are not a separate weaver you configure in FodyWeavers.xml and they are not tied to the Copy Local convention. Costura's configuration surface exists because it has to reconstruct runtime loading behaviour by hand: temporary assemblies on disk, runtime reference paths, compression, cleanup, satellite handling. The platform features do not carry that surface. If your target is .NET Core 3 or later and you are not constrained to the library-linking case, the README's own recommendation points away from Costura.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-27. The most recent release listed is 5.6.0 from 2021-09-08, preceded by 5.5.0 in 2021 and 5.1.0 in 2021. The README states plainly that the package is in maintenance mode and that Costura will be kept there for the supported use cases because the maintainers use them. Maintenance mode has a practical meaning for upgrades: the supported list can shrink, and the README says it may be updated and will become more strict over time. On licensing, the repository is MIT, and the README separately states that all developers using Fody are expected to become a Patron on OpenCollective, pointing to the Licensing/Patron FAQ in the Fody Home repository. Those are two different things: the MIT licence covers the code, the patronage request is a project expectation. Read the FAQ before you decide how that applies to you; this is not legal advice.

Editorial conclusion

Adopt Costura only if you are on a Windows C# project, you need a single assembly for library or exe linking, and you have accepted that the maintainers keep it in maintenance mode. Do not adopt it for VB.NET, Windows Services or non-Windows platforms, because the README lists all three as non-supported. Before wiring it into a build, verify three things in your own project: that every dependency you care about is marked Copy Local, that DisableCleanup is not needed because something else still expects the DLLs beside the binary, and that satellite resource assemblies behave as you expect given IgnoreSatelliteAssemblies.

Frequently asked questions

Official sources

1. Fody/Costura on GitHub
2. Issues
3. License: MIT
4. README
5. Releases