Sigourney 0.4.1

Sigourney

Sigourney 是一个轻量级的工具包，帮助开发者编写 weaver，这些工具可以修改使用 Mono.Cecil 的其他 .NET 程序集。

使用 Sigourney 的项目

到目前为止，已知有两个项目使用 Sigourney，这两个项目都由 Sigourney 的作者开发。

• Covarsky，一个在类似 F# 这样的语言中引入协变（或反协变）的工具。
• Farkle，一个使用 Sigourney 进行 语法预编译器 的 LALR 解析库。

如果你的项目使用 Sigourney，请随时打开一个 pull request 将其添加到列表中。这将真的有助于了解第三方如何以及是否使用它，并管理破坏性更改。

为什么使用 Sigourney

将 Sigourney 与 Fody 进行比较

当 ".NET 程序集" 和 "weaver" 出现在同一个句子中时，大多数开发者会想到 Fody。

Sigourney 是 Fody 的竞争对手，但不是 替代品。Fody 是一个更先进、成熟且经过实战考验的工具，但它存在两个问题

• Fody 采用了一个非常独特的授权模式，要求每一个使用者都必须订阅 Open Collective 或 Tidelift。不过，这一要求并非强制性，Fody 其他情况下遵循 MIT 许可协议。但如果你像 Sigourney 开发者一样，宁愿不使用 Fody 而不为此付费，Sigourney 可以作为替代方案。

• Fody 拥有复杂的配置系统，需要额外的 FodyWeavers.xml 文件、该文件的 XML 架构，以及通常 三个 NuGet 包：一个用于 Fody 本身，一个用于编织器，一个用于控制其行为属性的包。Sigourney 则保持简单和灵活，只需引用两个包（包含编织器和 Sigourney 本身的包），配置通常在项目文件内部进行，任何属性都需在要编织的程序集中手动定义。

相对而言，Fody 拥有一个更大的社区和与之配套的多种编织器，而 Sigourney 是一个比较新的项目，其社区和可用的编织器种类几乎不存在。

Sigourney 还可以用作独立库，而无需连接到 MSBuild；这是 Fody 无法做到的。

将 Sigourney 与 Mono.Cecil 进行比较

本质上，Sigourney 是在 Mono.Cecil（Fody 可以说是更厚重的）之上添加了一层薄薄的抽象层。使用 Sigourney 比直接使用 Mono.Cecil 更好，因为 Sigourney 提供了一些你或许需要自己实现的便利性，如以下内容

• Sigourney 编织的程序集会标记上名为 ProcessedByMyAwesomeWeaver 的类型。如果你的优秀编织器尝试多次编织同一个程序集，Sigourney 不会进行任何操作。
• Sigourney 提供了方便的 MSBuild 集成，允许编织器在你构建项目时运行，无需额外的步骤。更多关于这一点，请参见下面的内容。
• Sigourney 可以轻松支持强命名程序集（但有一个小警告），隐藏了搜索 .snk 文件的逻辑。
• Sigourney 自动更新程序集的调试符号，允许进行调试。

如何使用

使用 Sigourney 与 MSBuild

在大多数情况下，使用由 Sigourney 驱动的编织器就像安装一个 NuGet 包一样简单。更多详细资料，请参考该包的文档。

Sigourney 有一种特别的模式，可以创建与 Sigourney 的标准模式兼容并在同一项目中共存的 MSBuild-based 编织器，并且支持增量构建。如何基于这种模式创建编织器的示例项目可以在这个仓库找到：tests/testweaver-1。

想要禁用所有遵循标准模式的编织器，请在你项目文件中的 PropertyGroup 内添加以下行：

<SigourneyEnable>false</SigourneyEnable>

将 Sigourney 作为独立库使用

Sigourney 也可以用作独立库，作为更大程序的一部分，用于编织 .NET 程序集。只需安装Sigourney 的 NuGet 包，并按照以下方式使用它：

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");
    }
}

更多资料，请参考Weaver 类的文档。

支持的版本策略

TL;DR：由于所有已知的编织器都是第一方，向后兼容性不是 Sigourney 的首要任务。经常更新你的 SDK。破环性更改可能无法避免，但会尽力规避。在版本更新中而非补丁版本中预期它们。

Sigourney 是一个 .NET Standard 2.0 库，这意味着它在 .NET Framework 和基于 .NET Core 的 MSBuild 版本中都能运行（前者可通过 msbuild 命令或 Windows 的 Visual Studio 使用，后者则在使用现代 dotnet SDK 命令时使用）。除非有编织器以 .NET Standard 为目标，否则其作者必须使用 MSBuild 的 MSBuildRuntimeType 属性来加载正确的程序集。

使用 Sigourney 的编织器不支持低于 5.0 的 NuGet 客户端，该版本随 Visual Studio 2019 一起发布。包管理器 Paket（https://fsprojects.github.io/Paket）未经测试。

由于 Mono.Cecil 对程序集采取框架无关的处理方式，Sigourney 应该支持您 SDK 支持的任何框架版本。

没有明确定义支持或不支持的 MSBuild 版本，但 Sigourney 仅针对最新版本进行了测试。早期版本可能支持，也可能不支持。

Sigourney 仅针对 SDK 风格的项目进行测试。传统的 .NET Framework 项目（那些大而难以阅读的项目）是否可以工作尚不清楚。

与 Mono.Cecil 类似，Sigourney 的版本号很可能会保持在 0.x.y 范围内。修复版本的发布不会破坏代码，尽管它们可能会升级库。次要版本的发布更有可能破坏某些东西，但此类影响将尽量控制在最小。

已知问题

• 当您使用基于 .NET Core 的 MSBuild 版本构建项目时，不支持对程序集进行强命名。

• 当您使用基于 .NET Framework 的 MSBuild 版本构建使用多个编织器的项目时，每个编织器的依赖项不会隔开。例如，如果您的项目使用两个编织器，并且每个编织器都使用 Sigourney 的不同版本，那么 MSBuild 将仅使用运行在首位的编织器所使用的 Sigourney 版本。这是 .NET Framework 的固有限制，其解决方案既不简单也不打算在 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).

许可证

Sigourney 采用 MIT 许可证，没有任何附加条件。

处理强命名程序集的代码最初是从 Fody 复制过来的。如果您对此有任何问题，请不要对 Sigourney 编织的程序集进行强命名。那么，您为什么还要强命名您的程序集呢？

维护者

• @teo-tsirpanis