Permalink
Find file Copy path
252 lines (142 sloc) 10.1 KB

AppVeyor Chat on Gitter NuGet Status Patrons on Open Collective

Extensible tool for weaving .net assemblies

Manipulating the IL of an assembly as part of a build requires a significant amount of plumbing code. This plumbing code involves knowledge of both the MSBuild and Visual Studio APIs. Fody attempts to eliminate that plumbing code through an extensible add-in model.

This is the codebase of core Fody engine. For more information on the larger Fody project see https://github.com/Fody/Home.

Already a Patron? skip past this section

Community backed

Fody requires significant effort to maintain. As such it relies on financial contributions from the community and sponsorship to ensure its long term viability. It is expected that all developers using Fody become a Patron on OpenCollective.

Go to licensing FAQ for more information.

Platinum Sponsors

Support this project by becoming a Platinum Sponsor. A banner with your company logo will be added here with a link to your website. A "Sponsored by" text and link will be added to the description of the NuGet Package for the life of your sponsorship. You also get 1 hour of remote support per month.

Gold Sponsors

Support this project by becoming a Gold Sponsor. A large company logo will be added here with a link to your website.

PostSharp

Silver Sponsors

Support this project by becoming a Silver Sponsor. A medium company logo will be added here with a link to your website.

Particular Software

Bronze Sponsors

Support this project by becoming a Bronze Sponsor. The company avatar will show up here with a link to your OpenCollective Profile.

Patrons and sponsors

Thanks to all the backers and sponsors! Support this project by becoming a patron.

Licensing/Patron FAQ

Moved to Fody/Home: Licensing/Patron FAQ

Usage

Install using NuGet. See Using the package manager console for more info.

Fody ships in two parts:

  1. The core "engine" shipped in the Fody NuGet package
  2. Any number of "addins" or "weavers" which are all shipped in their own NuGet packages.

The below examples will use Virtuosity.

Install Fody

Since NuGet always defaults to the oldest, and most buggy, version of any dependency it is important to do a NuGet install of Fody after installing any weaver.

Install-Package Fody

Subscribe to Fody on Libraries.io to get notified of releases of Fody.

Add the nuget

Install the package in the project:

Install-Package WeaverName.Fody

e.g.

Install-Package Virtuosity.Fody

Add FodyWeavers.xml

To indicate what weavers run and in what order a FodyWeavers.xml file is used at the project level. It needs to be added manually. It takes the following form:

<?xml version="1.0" encoding="utf-8" ?>
<Weavers>
  <WeaverName/>
</Weavers>

e.g.

<?xml version="1.0" encoding="utf-8" ?>
<Weavers>
  <Virtuosity/>
</Weavers>

See Configuration in the wiki for additional options.

Supported Visual Studio Versions

To build a project using Fody you will need:

  • Visual Studio 2017 or later
  • .Net >= 4.6

Older versions of Visual Studio may still work, but are not actively supported. We do our best to not break backward compatibility, but can't guarantee this forever.

Supported Runtimes

No explicit code is in place to check for non supported versions, and throw an error. As such earlier versions of .net may work as a side effect. It's all up to the individual weavers that you use and what version they are able to support.

Any bugs found must be reproduced in a supported version.

Downstream plugins are recommended to follow the above guidelines.

Reasons

While it may seam trivial to "implement support for earlier versions of .net" the long term support implications are too costly. For example to support earlier versions of .net require

  • Custom VMs to verify problems.
  • Added complexity to setting up build environment.
  • Bugs in unsupported versions in .NET may be manifest as bugs in Fody.

Edit and continue

Edit and continue is not supported. There is no extension point to re-weave an assembly after the edit part.

Project formats

The following are not supported

To tell the difference between the old and new csproj formats.

The old format starts with

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

The new format starts with

<Project Sdk="Microsoft.NET.Sdk">

For all these scenarios is it instead recommended to move to the new VS 2017 SDK style projects.

References

The plumbing tasks Fody handles

  • Injection of the MSBuild task into the build pipeline
  • Resolving the location of the assembly and pdb
  • Abstracts the complexities of logging to MSBuild
  • Reads the assembly and pdb into the Mono.Cecil object model
  • Re-applying the strong name if necessary
  • Saving the assembly and pdb

Fody Uses Mono.Cecil and an add-in based approach to modifying the IL of .net assemblies at compile time.

  • No install required to build
  • No attributes required
  • No references required

Addins List

Moved to Fody/Home: Addins

More Info

Contributors

This project exists thanks to all the people who contribute. [Contribute].