Sigourney 0.4.1

dotnet add package Sigourney --version 0.4.1                
NuGet\Install-Package Sigourney -Version 0.4.1                
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.4.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Sigourney --version 0.4.1                
#r "nuget: Sigourney, 0.4.1"                
#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.4.1

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

Sigourney

NuGet CI 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 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 supports strong-named assemblies easily (with a caveat), abstracting away most of the logic behind finding the .snk files.
  • 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/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: Since all known weavers are first-party, backwards compatibility is not a top priority of Sigourney. Upgrade your SDK often. Breaking changes are avoided but inevitable. Expect them 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 (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.

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

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

  • 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 use the same version of Sigourney, or use a .NET Core-based edition of MSBuild. If you can't do that because you are are using Visual Studio on Windows, [please upvote this feedback item](https://developercommunity.visualstudio.com/t/Allow-building-SDK-style-projects-with-t/1331985).

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.1 1,962 9/2/2021
0.4.0 358 9/2/2021
0.3.3 528 7/18/2021
0.3.2 655 4/16/2021
0.3.1 804 11/14/2020
0.3.0 724 11/2/2020
0.2.1 547 10/7/2020
0.2.0 390 10/4/2020
0.1.1 454 4/8/2020
0.1.0 445 4/6/2020

Sigourney's build-time assets were moved to a new package, https://nuget.org/packages/Sigourney.Build, resulting in smaller download sizes and less dependencies. Weavers will need to be updated to publicly reference Sigourney.Build instead, as seen in the test weavers.

Legacy code that was supporting weavers targeting versions of Sigourney prior to 0.3.0 was removed.

Version 4.0.1 fixed a bug where Sigourney did not run on F#.