Sigourney

Sigourney is a lightweight toolkit that helps developers write .NET assembly weavers using Mono.Cecil.

Projects using Sigourney

At the moment, Sigourney is known to be used in two projects.

• Covarsky, a tool that brings generic covariance and contravariance in languages that don't support it like F#.
• Farkle, an LALR parsing library that uses Sigourney for its grammar precompiler.

If your project uses Sigourney, feel free to open a pull request to add it to the list. It would really help with understanding if and how third parties are using it, and managing breaking changes.

Why use Sigourney

Comparing Sigourney with Fody

When the words ".NET assembly" and "weaver" appear in the same sentence, most developers think of Fody. Sigourney is not Fody and is not meant to replace it. There are several differences between Sigourney and Fody:

• Fody runs all weavers in the same MSBuild task, while sharing the same versions of Mono.Cecil and Fody's core assemblies. By contrast in Sigourney, each weaver is distributed as a standalone package that runs in its own MSBuild task with its own set of dependencies. This loses Fody's benefit of having its weavers' dependencies updated without releasing a new version of them, but Sigourney's approach gives more stability and predictability over the code executed in the weaver. Also the dependency loading logic is handled by MSBuild, significantly reducing the complexity of the Sigourney codebase.
  • Sigourney's foundational MSBuild code is shared across weavers and shipped in a separate Sigourney.Build package that can be independently updated.
• Sigourney lacks a couple of features that Fody has, like integrated IL verification or in-solution weaving. They might be added in the future.
• Fody expects users to subscribe to Open Collective. This requirement is not mandatory though, and Fody is otherwise licensed under the MIT license. Sigourney does not have such expectation.
• Fody has a complicated configuration system that requires an additional FodyWeavers.xml file, an XML schema for that file, and up to three NuGet packages: one for Fody itself, one for the weaver, and one for the attributes that control its behavior. Sigourney keeps it simple and flexible. Only two packages are required to be referenced (the package with the weaver and Sigourney itself), configuration usually happens inside the project file, with any attributes being manually defined in the assembly to be weaved.
• Sigourney can be used as a standalone library without hooking it to MSBuild, which Fody cannot do.
• Fody has a large community and a variety of weavers developed with it, whereas Sigourney is a relatively new project whose community and variety of weavers are nearly nonexistent.

Comparing Sigourney with Mono.Cecil

In its essence, Sigourney is a thin layer over Mono.Cecil (Fody is arguably thicker). Using Sigourney is better than directly using Mono.Cecil because of facilities Sigourney provides that you would otherwise implement yourself, like the following:

• Assemblies weaved by Sigourney are marked with a type having a name like ProcessedByMyAwesomeWeaver. If your awesome weaver attempts to weave the same assembly more than once, Sigourney will do nothing.
• Sigourney provides easy MSBuild integration of your weavers, allowing them to run when you build your project, without any extra steps. More on that right below.
• Sigourney automatically updates the debug symbols of the assemblies, allowing them to still be debugged.

How to use

Using Sigourney with MSBuild

In most cases, using a weaver powered by Sigourney is as easy as installing a NuGet package. Consult the documentation of that package for more details.

Sigourney has a particular pattern for creating MSBuild-based weavers that can coexist with others in the same project and support incremental building. To learn how to create a weaver based on that pattern, this repository has a sample project in tests/Sigourney.TestWeaver1.

To easily disable all weavers that were implemented according to the standard pattern, add the following line inside a PropertyGroup in your project file:

<SigourneyEnable>false</SigourneyEnable>

Using Sigourney as a standalone library

Sigourney can also be used as a standalone library, as part of a bigger program that weaves .NET assemblies. Simply install Sigourney's NuGet package and use it like this:

using Mono.Cecil;
using Serilog.Core;
using Sigourney;

public class Test
{
    public bool DoWeave(AssemblyDefinition asm)
    {
        for (var t in asm.MainModule.Types)
        {
            // Do what you want with each type of the assembly.
        }
        return true;
    }

    public static void Main()
    {
        Weaver.Weave("MyAssembly.dll", "MyAssembly.weaved.dll", DoWeave, Logger.None, null, "MyAwesomeWeaver");
    }
}

To learn more, consult the documentation of the Weaver class.

Support policy

Sigourney is a .NET Standard 2.0 library, meaning that it will work in both .NET Framework and .NET Core-based editions of MSBuild (the former are used with the msbuild command or on Visual Studio for Windows, and the latter when using modern dotnet SDK commands). Unless an assembly with a weaver targets .NET Standard too, its author has to load the correct assembly using MSBuild's MSBuildRuntimeType property.

Weavers using Sigourney do not support NuGet clients older than 5.0, which was released with Visual Studio 2019. The Paket package manager is not tested.

Because Mono.Cecil treats assemblies in a framework-agnostic way, Sigourney should work with any framework version supported by your SDK.

Sigourney supports all currently supported versions of MSBuild greater than 16.0, and all currently supported versions of the .NET SDK. Only the latest version is tested though, but care is taken to not use anything that does not work in earlier versions. Please open an issue if something does not work in an earlier supported version.

Sigourney is tested with SDK-style projects only. Legacy .NET Framework projects (the big, unreadable ones) are not known whether they work or not. Projects that use packages.config to manage NuGet packages are not supported.

Like Mono.Cecil, Sigourney's version number will most likely stick in the 0.x.y range. Patch releases will not break code, although they might upgrade libraries. Minor releases are more likely to break stuff but such impact will be attempted to be kept at a minimum. Barring exceptional circumstances, breaking changes will be made after being announced in the previous release.

Known issues

• Strong-naming assemblies is not supported when you build your project using a .NET Core-based edition of MSBuild. Fixed in version 0.5.0.

• When you build a project with many weavers using a .NET Framework-based edition of MSBuild, each weaver's dependencies are not isolated. For example, if your project uses two weavers and each of them uses a different version of Sigourney, MSBuild will only use the version of Sigourney that the weaver that ran first used. This is an inherent limitation of the .NET Framework whose fix is not trivial and not planned for Sigourney.

  To work around this, ensure that all weavers are compiled with close enough versions of Sigourney, or build your projects with the dotnet CLI.

License

Sigourney is licensed under the MIT license.

The code that handles strong-named assemblies was originally copied from Fody. If you have any problem with this, do not strong-name your assemblies that are weaved by Sigourney. And why are you still strong-naming your assemblies?

Maintainers

• @teo-tsirpanis