Sigourney 0.3.3

There is a newer version of this package available.
See the version list below for details.
dotnet add package Sigourney --version 0.3.3                
NuGet\Install-Package Sigourney -Version 0.3.3                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sigourney" Version="0.3.3" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Sigourney --version 0.3.3                
#r "nuget: Sigourney, 0.3.3"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Sigourney as a Cake Addin
#addin nuget:?package=Sigourney&version=0.3.3

// Install Sigourney as a Cake Tool
#tool nuget:?package=Sigourney&version=0.3.3                

Sigourney

NuGet .NET Build Status

Sigourney is a lightweight toolkit that helps developers write weavers, tools that modify other .NET assemblies using Mono.Cecil.

Projects using Sigourney

At the moment, Sigourney is known to be used by two projects, both developed by Sigourney's author.

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 a competitor but not a replacement for Fody. Fody is a more advanced, mature and battle-tested tool, but there are two problems with it:

  • Fody has an unusual licensing model where every user of it is expected to subscribe to either Open Collective or Tidelift. This requirement is not mandatory though, and Fody is otherwise licensed under the MIT license. But for the people (like Sigourney's author) who prefer to not use Fody at all instead of paying, Sigourney is an alternative.

  • Fody has a complicated configuration system that requires an additional FodyWeavers.xml file, an XML schema for that file, and typically 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.

Fody on the other hand has a much larger community and variety of weavers developed with it, whereas Sigourney is a relatively new project whose community and variety of weavers are nearly nonexistent.

Sigourney can also be used as a standalone library without hooking it to MSBuild; something that Fody cannot do.

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 for the following reasons:

  • 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. In Mono.Cecil you would have to implement such logic by yourself.
  • 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 supports strong-named assemblies easily, abstracting away most of the logic behind finding the .snk files.

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/testweaver-1.

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.

Supported versions policy

TL;DR: Sigourney's author does not care very much about backwards compatibility. Upgrade your SDK often. Expect breaking changes in minor releases but not in patch releases.

Sigourney is a .NET Standard 2.0 library, meaning that it will work in both .NET Framework and .NET Core-based editions of MSBuild. Unless an assembly with a weaver targets .NET Standard too, its author has to load the correct assembly using MSBuild's MSBuildRuntimeType property.

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

No MSBuild version is explicitly supported or unsupported, but Sigourney is only tested against the latest one. Earlier ones might be supported, or maybe not.

Sigourney is tested with SDK-style projects only. Legacy .NET Framework projects (the big, unreadable ones) are not known whether they work or not.

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.

Known issues

  • <s>Sigourney's MSBuild integration does not fully support incremental builds on projects that use more than one weaver.

Since Sigourney already supports incremental weaving through the ProcessedBy classes, fixing this issue has a low priority. Anybody interested can feel free to propose a solution.</s> This problem was fixed in Sigourney 0.3.0.

  • Strong-naming assemblies is not supported when you build your project with a .NET Core-based edition of MSBuild.

License

Sigourney is licensed under the MIT license, with no strings attached.

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

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.4.2 35 12/7/2024
0.4.1 2,152 9/2/2021
0.4.0 383 9/2/2021 0.4.0 is deprecated because it has critical bugs.
0.3.3 577 7/18/2021
0.3.2 700 4/16/2021
0.3.1 844 11/14/2020
0.3.0 763 11/2/2020
0.2.1 587 10/7/2020
0.2.0 411 10/4/2020
0.1.1 478 4/8/2020
0.1.0 468 4/6/2020

This release fixes some minor bugs, updates dependencies and adds a new API intented for some very limited scenarios.

It is not urged, but weavers will have to be updated and re-released to fully take advantage of this version's features.