Code Generation Chronicles

Note: this post is published also at OzCode's blog.

As part of my new year resolutions, I've decided to put more effort in learning code generation techniques. This is the first blog post in a series exploring code generation.

Fody

Fody is an open source library for IL weaving. It generates and manipulates IL code during build time. Depending on Fody is easy - it is available as a Nuget Package and it doesn't require any installation/modification to the build system. One of Fody's benefits is it footprints - there are none. Since IL weaving is done during build time, there aren't any Fody-related assemblies needed at runtime, which could be important if you are worried about the number of assemblies you ship with your product. On top of that Fody is highly extensible and it has an active open source community around it. One example for how Fody can save development time is the following extension: "PropertyChanged"�which by placing a ImplementPropertyChanged attribute over a class, it generates all of the code necessary to fully implement the INotifyPropertyChanged interface in that class. More are available here.

Using Fody to add WCF's KnownType attributes

In one of the projects I've been working on, we've used a client that were using�.Net Remoting to communicate with services. At some point, we wanted to exchange .Net Remoting with the more modern�WCF. The thing is- A lot of the code base was unmaintainable-legacy code, and we wanted to perform as little changes as possible, while reusing as much of the existing architecture as possible. One of the challenges resided in a WCF quirk, were by default it doesn't allow passing a derived type of the DataContract type that is defined in the OperationContract. The way to make derived classes work is done in WCF by adding a KnownType attribute on the base type for each derived type we use. As an example, if we have a class A and two derived classes B and C, we would have to add two KnownType attributes over class A; one for Class B and one for Class C. Since this scenario was common in the current architecture, we were looking for a way to solve this issue without manually adding KnownType attributes, since it would be easy to miss some or to forget adding the attribute over new derived classes in the future. In the end we've managed to save time and replace the communication layer easily by using Fody for automatically adding KnownType attributes for all derived types on their base classes during build time.

Implementing a Fody extension

If you want to write Fody extension start by cloning the BasicFodyAddin repository. This repository is maintained by the open source community and it simplifies both the implementation and the deployment of the extension as a Nuget Package. BasicFodyAddin source code contains a Solution with four C# projects:
  1. BasicFodyAddin which will contain the extension
  2. Nuget which is for deploying a Nuget package
  3. Tests for writing unit tests
  4. AssemblyToProcess that is used as a target assembly for testing your mew�Fody�extension.
We will focus on BasicFodyAddin. In the BasicFodyAddin project there is a file called ModuleWeaver.cs�Go ahead and replace it content with the following code: This is the class we will use to implement the extension.�The ModuleDefinition property will be populated during build time by Fody and it will contain the target Module for the IL Weaving. As you have probably noticed, the property is of type ModuleDefinition. ModuleDefinition is a class representing a MSIL Module in Mono.Cecil which is a library Fody relies on to generate and manipulate IL code. In addition to ModuleDefinition we will use more types it defines such as TypeDefinition. When using Fody your ModuleWeaver�class must be implemented according the following:
  • Be public, instance and not abstract.
  • Have an empty constructor.
  • Have a ModuleDefinition property that will be populated during build.
  • Have an Execute method.

The KnownTypeAttributeWeaver class has three main methods:

  • Execute - Entry point. It calls other methods for performing the IL weaving.
  • AddKnownTypeAttributes - Decorates base types with KnownType attributes.
  • RemoveKnowsDeriveTypesAttribute�- Removes KnowsDeriveTypes attributes from base types
Note: A few helper methods will be added down the road.   Now create another a new class called�KnowsDeriveTypesAttribute. This attribute is for explicitly specifying the base types we want to decorate with KnownType attributes. We could have added KnownType attributes over every base class in the assembly, but we wanted the extra control.

Implementing Execute

In Execute we locate all the types decorated with KnowsDeriveTypesAttribute, and we decorate them with KnownType attributes according to their sub types. After that is done, we remove the KnowsDeriveTypesAttribute as it isn't necessary anymore.

Implementing AddKnownTypeAttributes

Let's break it down. In the code above we are performing three steps:
  1. Finding and retrieving all derived types of the given base type.
  2. Creating a TypeDefinition instance for the KnownType attribute.
  3. Finding and retrieving a constructor for the KnownType attribute.
The first step is done using a helper method called GetDerivedTypes.
Given a module and a type it returns an array of TypeDefinitions, containing all of the types in the given module that derive from the given type
The second step is done using a helper method called GetTypeDefinition.
Given an assembly name and a type name, it returns a TypeDefinition for that type.
The third step is done using a helper method called GetConstructorForKnownTypeAttribute.
Given a ModuleDefinition and a TypeDefinition it returns a the first constructor for that type.
Let's continue and break down the last part of AddKnownTypeAttributes. In this part of the code we add a KnownType attribute to the base type for each derived type we previously found. We are using the KnownType attribute's constructor that expects the System.Type of the sub class.

Implementing RemoveKnowsDeriveTypesAttribute

This part is straight forward. We locate and then remove the KnowsDeriveTypes attribute from the base type.

Unit Tests & Debugging

Unit Tests are always important, especially when writing Fody extensions. We had a good code coverage in the final product, but for this blog post I'll use Unit Tests solely for debugging purposes, as I will be able to debug the extension by running the Unit Tests in debug mode. For this post I've created two Unit Tests. One for testing the addition of the KnownType attributes and one for testing the removal of the KnowsDeriveTypes attribute. You can view the Unit Tests file here. I've also went ahead and added three classes to the AssemblyToProcess project for testing the IL Weaving process. Even though Fody has a basic logging capability it isn't always easy to find and view logs in the output window. Fortunately, at debug time we can use OzCode's Trace Points feature. I've added a trace point at the line which adds a KnownType attribute over base types. After running The Unit Tests in debug mode, add a breakpoint at the line above and then create a new Trace Point as follow: Trace Point menu You can customize your reports by writing expressions inside curly brackets: Configuring Trace Points After you run the tests, you can view the results by opening the following menu: Finding Trace Points The results: Trace Points report As a decisive test we can open the output assembly in a Decompiler and view the final results. Fortunately, the Unit Tests have created a new version of the AssemblyToProcess.DLL containing the changes done by the IL Weaving. The DLL is called AssemblyToProcess2.DLL and you can find it at the AssemblyToProcess bin directory. For example, opening the DLL using JetBrain's DotPeek decompiler yields the following result: Final results Fody and Mono.Cecil didn't only add KnownType attributes for the derive types, but also removed the KnownDeriveTypes attribute and added a reference to System.Runtime.Serialization in which the KnownType attribute is defined in.

Deployment

To use and distribute your Fody extension you will need to create a NuGet package. I will write a dedicated blog post on how this is done and on how we can publish Nuget Packages, including the one for this extension.

Summary

Fody is a powerful tool. It runs during the build's pipeline and it manipulate the code of assemblies using Mono.Cecil's IL Weaving capabilities. As the examples in this post and in the official list of Fody Addins, we can clearly see that Fody can be a pretty handy tool. But it is really important to keep the following lesson in mind: Use it wisely and try not to shoot your foot ;) You can view/clone/fork the code for this extension from this Github repository.