DOCSEARCHbyAlgolia
Submit Docs

Costura.Fody Documentation

repository·develop·Indexed 25 days ago

https://github.com/fody/costura

A Fody add-in that embeds dependencies and PDBs marked as 'Copy Local' as embedded resources within a single assembly. It simplifies application distribution by reducing the number of required files and provides configuration options for handling runtimes, mixed-mode/unmanaged assemblies, and native libraries via FodyWeavers.xml.

Tokens
1.7K
Snippets
9
Records
11
Agent score
32%

What's inside Costura

  1. How Costura works: Embedding assemblies as resources

    develop
    Costura embeds all assemblies and PDBs marked as "Copy Local" into your target assembly as embedded resources. It then injects a module initializer into your assembly that calls ILTemplate.Attach(). This code, along with injected ILTemplate classes, ensures that if an assembly load fails, it is automatically loaded from the embedded resources.

  3. Install Costura.Fody via NuGet

    develop

    To use Costura, you must install both the Fody and Costura.Fody NuGet packages. It is important to install Fody explicitly to ensure you get a recent version rather than a default older version.

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

  4. Include native libraries

    develop

    To include native libraries, add them to your project as an Embedded Resource in a folder named according to the target platform:

    • costuraX86
    • costuraX64
    • costuraArm64

    You can also specify the loading order using the PreloadOrder option.

    <Costura>
  <PreloadOrder>
    Foo
    Bar
  </PreloadOrder>
</Costura>

  5. Include/Exclude specific assemblies

    develop

    You can control which assemblies are embedded by using ExcludeAssemblies or IncludeAssemblies. These options accept assembly names without the .dll or .exe extension. You can use wildcards at the end of a name for partial matching (e.g., System.*).

    Note: You cannot use IncludeAssemblies if you have already defined ExcludeAssemblies (and vice versa).

    <Costura>
  <ExcludeAssemblies>
    Foo
    Bar
  </ExcludeAssemblies>
</Costura>

  6. Handle mixed-mode/unmanaged assemblies

    develop

    Mixed-mode assemblies cannot be loaded like managed assemblies. To help Costura identify them and determine the correct environment, include their names in UnmanagedWinX86Assemblies, UnmanagedWinX64Assemblies, or UnmanagedWinArm64Assemblies.

    <Costura
    UnmanagedWinX86Assemblies='Foo32|Bar32' 
    UnmanagedWinX64Assemblies='Foo64|Bar64' 
    UnmanagedWinArm64Assemblies='FooArm64|BarArm64'/>

  7. Include specific runtimes

    develop

    By default, Costura embeds all available runtimes. To restrict this to specific platforms, use the IncludeRuntimes option. Common values include win, win-x86, win-x64, win-arm64, and unix.

    <Costura IncludeRuntimes='win-x64|win-arm64' />

  9. Configure Costura for Unit Testing

    develop

    Most unit test frameworks require physical .dll files to discover tests. If your testing assembly is being affected by Costura, you may need to configure it to create temporary assemblies and disable cleanup in your testing project's FodyWeavers.xml.

    <Weavers>
    <Costura ExcludeAssemblies='TargetExe|TargetExeTest'
             CreateTemporaryAssemblies='true'
             DisableCleanup='true'/>
</Weavers>

  10. Manually initialize Costura with CosturaUtility

    develop

    If you disable automatic loading via LoadAtModuleInit='false', or if you are working in a scenario where module initializers do not work (such as in libraries or Mono), you must manually call CosturaUtility.Initialize() as early as possible in your code.

    class Program
{
    static Program()
    {
        CosturaUtility.Initialize();
    }

    static void Main(string[] args) { ... }
}

  11. Reference: Costura configuration options

    develop

    The following configuration options are available for the <Costura> node in FodyWeavers.xml:

    OptionDefaultDescription
    CreateTemporaryAssembliesfalseCopies embedded files to disk before loading. Useful if assemblies expect a physical file path.
    IncludeDebugSymbolstrueControls if .pdb files for reference assemblies are embedded.
    IncludeRuntimeReferencestrueControls whether the runtimes folder (used by .NET Core) is embedded.
    UseRuntimeReferencePathsfalse (Framework) / true (Core)If true, runtime assemblies are embedded with their full path.
    DisableCompressionfalseDisables the default compression of embedded assemblies.
    DisableCleanupfalsePrevents Costura from removing embedded assemblies from the build process.
    DisableEventSubscriptionfalseDisables subscribing to AppDomain.AssemblyResolve or AssemblyLoadContext.Resolving. Use only for advanced plugin scenarios.
    LoadAtModuleInittrueIf false, you must manually call CosturaUtility.Initialize() in your code.
    IgnoreSatelliteAssembliesfalseDisables the automatic handling of assemblies named like resources.dll.
    ExcludeAssembliesN/AList of assembly names (no .dll/.exe) to exclude. Supports wildcards at the end (e.g., System.*).
    IncludeAssembliesN/AList of assembly names to include. Supports wildcards at the end.
    IncludeRuntimesN/AList of runtimes to include (e.g., win, win-x64, unix).
    UnmanagedWinX86AssembliesN/AList of mixed-mode/unmanaged assemblies for Win x86.
    UnmanagedWinX64AssembliesN/AList of mixed-mode/unmanaged assemblies for Win x64.
    UnmanagedWinArm64AssembliesN/AList of mixed-mode/unmanaged assemblies for Win Arm64.
    PreloadOrderN/ADefines the order in which preloaded assemblies are loaded.

    Note: ExcludeAssemblies and IncludeAssemblies can be defined as child elements with newline-delimited names or as attributes using the pipe | delimiter.

    <!-- Example using child elements -->
<Costura>
  <ExcludeAssemblies>
    Foo
    Bar
  </ExcludeAssemblies>
  <IncludeAssemblies>
    Baz
  </IncludeAssemblies>
</Costura>

<!-- Example using attributes -->
<Costura ExcludeAssemblies='Foo|Bar' IncludeAssemblies='Baz' />