My feelings on magic

(Feel free to skip this section if you couldn’t care less about my thoughts on automagic)

I am not the biggest fan of automagical behavior. For that reason, up until now, Glue has not automatically created new objects when you map. You have to instantiate the object to map to (and all nested objects within that object). The reason for this is that I want the developer to explicitly decide when it comes to how objects are to be created. Personally I like to be in control, so that problems do not arise at inconvenient times (like at runtime in a production environment).

In addition, I come from the OO school. I believe that objects should be, yes, objects, and not just data containers (a typical data container is a class containing only properties, and little or no logic). I believe objects should be relevant, individual, and contain logic. This often means that constructing them is not something you let a framework do (unless it is a framework specialized for that kind of job). Because constructing them often means making decisions, like what dependencies these objects should have.

The “General purpose” mapping framework

One of the driving forces for creating Glue was to create a general purpose mapping framework. Meaning it should support different scenarios, not just the ones I liked the most. In addition, using Glue extensively myself, I have found that there are (quite a lot of) times when having Glue create objects for me are both convenient, and low risk.

Automagical and Strict mode

So, with version 0.9 of Glue, I introduce the “Automagical” mode where Glue tries to instantiate objects whenever necessary. In addition, the existing behavior (making you create all the objects) is now named “Strict” mode. Choosing between the modes is simply done by choosing the right overload of the Mapper.Map-method. Intellisense will guide you.

Examples can be found here

(What is Glue?)

Download Glue 0.9 binaries here

- Tore Vestues

Also no doubt, we have not had such excellent package management system in the .Net-sphere. So why not just make RubyGems work for .Net as well? That’s exactly what Dru Sellers have done with Nu.

This is a great idea, so I decided right away to make a Gem out of Glue.

To use it, start your favorite windows shell and type:

gem install gluemapping

Then go to your project directory (if you’re not already there) and type

nu install gluemapping

That’s it! The newest Glue-assemblies will be put in the lib-folder in your project directory.

Requirements:

1. You will need to install ruby. Download the latest rubyinstaller, and install it.
2. Install Nu:

gem update --system
gem install nu


You can find more information on Nu here.

The Gem is hosted at RubyGems, you can find information about it here.

- Tore Vestues

There are many ways to use reflection, and the performance on them vary a lot. What we did was to try out every method and timing them to measure performance. These are the methods we tested: Normal property access, normal reflection, compiling and invoking a compiled expression, using Emit to create, compile and run the statement.

Normal property access

To compare the other methods, we measured the performance on accessing a property the normal way:

1

Run("Normal property access", () => { var city = address.City; });

It was no surprise that this was the fastest method.

Normal reflection (250 times slower than normal property access)

1
2

var cityPropertyInfo = typeof (Address).GetProperty("City");
Run("With reflection", () => cityPropertyInfo.GetValue(address, new object[0]));

This is what most of us think about when talking about reflection. This is also the by far most common method of reflection used in Glue. Although about 250 times slower than normal property access, this method has very strong sides compared to the other methods.

Invoking compiled expressions (twice as slow as normal property access)

1
2
3

Expression<Func<Address, string>> expression = x => x.City;
var func = expression.Compile();
Run("Invoke compiled expression", () => func.Invoke(address));

Using compiled expressions is another way of dynamically invoking members on objects. Due to the syntax exposed in the api in Glue, most mapping specifications enter Glue as (uncompiled) expressions. The fact that it is only about twice as slow than normal property access, is very promising. But there is a catch, a big one. In order to invoke this way, the expression must be compiled. It is not compiled when it enters Glue, so we have to include the time it takes to compile the expression as well.

Compile Expression and invoke it (51700 times slower than normal property access)

1
2
3
4
5

RunLong("Compile Expression and invoke", () =>
             {
                 var compiledFunction = expression.Compile();
                 compiledFunction.Invoke(address);
             });

Yes, if you have to compile an expression before invoking it, it takes about 200 times longer to do the operation than with normal reflection. Leaving this a unattractive method to use with Glue.

Using Emit, invoking a compiled expression (4 times slower than normal property access)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

private Func<Address, string> GetEmitDelegate()
{
    var dm = new DynamicMethod("TestMethod", typeof(String), new [] {typeof(Address) }, typeof(Address).Module);
 
    MethodInfo getCity = typeof(Address).GetProperty("City").GetGetMethod();
 
    ILGenerator il = dm.GetILGenerator();
    il.Emit(OpCodes.Ldarg_0);
    il.EmitCall(OpCodes.Call, getCity, null);
    il.Emit(OpCodes.Ret);
 
    return (Func<Address, String>)dm.CreateDelegate(typeof(Func<Address, String>));
}
 
var emitDelegate = GetEmitDelegate();
Run("Emit: run compiled statement", ()=>emitDelegate(address));

My guess is that using Emit is not something you will be doing a lot. But, we had to try. Again, executing a compiled expression was fast. But as with expressions, the problem comes when you have to compile before running.

Using Emit, create statement, compile it and run (39000 times slower than normal property access)

1

RunLong("Emit: Create statement, compile, run",()=>Emit(address));

As we can see, this is also horribly slow.

Conclusion

Unless you can create an expression/emit statement and compile it and then run the compiled version more than 200 times, in the app’s lifetime, using normal reflection is by far the preferred way to go when you have to dynamically invoke members on objects.

- Tore Vestues

Thanks to Åsmund Eldhuset.

Here’s the source

I’m actively developing it. I’m also actively using it. In this post I’ll share my experience as a user of Glue, and how easy it is to set up the mappings using TDD.

The example

We want to create a mapping between DomainPerson and GuiPerson, listed here.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public class DomainPerson
{
    public int Id { get; private set; }
    public String Name { get; set; }
    public DomainAddress Address { get; set; }
}
 
public class DomainAddress
{
    public String StreetAddress { get; set; }
    public int ZipCode { get; set; }
    public String City { get; set; }
    public String Country { get; set; }
}
 
public class GuiPerson
{
    public int Id { get { return 0;} set { return;} }
    public String Name { get; set; }
    public String StreetAddress { get; set; }
    public int ZipCode { get; set; }
    public String City { get; set; }
    public String Country { get; set; }
}

Making sure all properties are related

What I test first is that all the properties are related (or actively ignored). This makes it easy to later detect changes in the classes we map between. It also makes it easy for us to see what properties we have to handle.

But first, in traditional TDD style, lets start with writing a failing test. The test should verify that all properties on GuiPerson are either related or actively ignored. The test looks like this:

1
2
3
4
5

[Fact]
public void AsserAllPropertiesRelated()
{
	mapping.GetRelationsVerification().AssertAllPropertiesRelated<GuiPerson>();
}

and, as this will not compile, let’s create the actual mapping:

1

mapping = new Mapping<DomainPerson, GuiPerson>();

It compiles, but as expected, it fails. We have created a mapping, but nothing is related. A nice feature with Glue is that it tries to be as informative as possible when it fails. Look at the exception we receive when running this test:

Not all properties are related (or ignored): Id, Name, StreetAddress, ZipCode, City, Country

It tells us what properties we need to handle. This makes my job easy. I’ll just have to relate (or ignore) all the properties reported in the exception:

1
2
3
4
5
6
7

mapping.Relate(domain=>domain.Id,gui=>gui.Id);
mapping.Relate(domain => domain.Name, gui => gui.Name);
 
var addressMapping = new Mapping<DomainAddress, GuiPerson>();
addressMapping.AutoRelateEqualNames();
 
mapping.Flatten(domain=>domain.Address,addressMapping);

Running the test, I get another Exception:

Glue.GlueException : The relation between ‘Id’ and ‘Id’ has atleast one readonly property, and can not be related TwoWays

Ah, fair enough, it went a bit fast there. I related all properties, but I didn’t check if any where readonly. Luckily, Glue tells us this early. I’ll make this change:

1

mapping.RelateTowardsRight(domain => domain.Id, gui => gui.Id);

And when I run the test again, it goes green. Now all properties are related, and we are protected from future changes.

Make sure the mapping actually works

But will it really work? We can also easily check if the actual values can be set on the target object. You should do this. I always do. So, lets start with another test:

1
2
3
4
5

[Fact]
public void AssertMappingWorks()
{
    mapping.GetMapperVerification().AssertMapsCorrectlyTowards(new GuiPerson());
}

Running this test, we get an Exception:

Glue.GlueException : Failed properties: Id (Failed to set value)

Ah, it detected that Id on GuiPerson is totally unable to set. Ok, lets say that this is supposed to be this way. That means we should not map Id towards GuiPerson. That means that we must remove this:

1

mapping.RelateTowardsRight(domain => domain.Id, gui => gui.Id);

Running the tests again makes AssertMappingWorks gets green, but now AsserAllPropertiesRelated got red again. That is because we have not related Id on GuiPerson. But since we do not want to relate it, we ignore it, to signal that we actively have made that choice. We do it like this:

1

mapping.IgnoreTowards<GuiPerson>(gui=>gui.Id);

Running the tests, they both are green, and now we know that we have a working mapping, which also are protected from failing on future changes.

Note that this example only tests the mapping and relations towards GuiPerson, in a bidirectional mapping scenario I advice to write the same two tests towards DomainPerson.

This is how I do it, and it works great for me. Hope you liked it. To learn more about Glue, and to download it, go to the Glue homepage at Codeplex

- Tore Vestues

You’ll find examples and code here: http://glue.codeplex.com

Glue is a general purpose, bidirectional automatic mapping for the .Net platform, with strong verification and testing tools.

I’ve seen quite a lot of less than optimal handling of mapping issues in quite a few projects over the years. Again and again mapping seems to be just a task we have to do, and a bit too small for automating. It becomes clearer and clearer to me that mapping is both an important task in many projects, and it is always a repetitive and boring task. In addition far to often subtle annoying bugs tend to sneak into mapping code. This motivated me to create Glue. And this is what I need from a mapping framework:

a) a way to automate mapping, mostly because it is boring, and that makes it error prone,
b) a way to automatically test the mapping, I’ve found that manual written test code for mapping is seldom done in a good way,
c) a way to prevent future changes making my mappings obsolete. When people make changes, they rarely focus on mapping (and honestly they should not either). They should be told when they have to update the mapping.

Now, you could argue that there is already a mapping framework available on the .Net plattform. And when I started this work, I actually started with that framework, thinking I could just make a few extensions to fulfil my needs. I actually spent some time in the source code to try to implement it, but sadly I realized that our needs differed too much. So, I created Glue, and these where the driving forces:

General purpose

Glue is a general purpose mapper. We realize that in the real world there are a lot of different solutions, and not all of them follow “the one true pattern”. In fact, mapping is often used to map to and from subsystems that are far from well designed. Subsystems we try to hide in a layer because we do not want it to leak into the other layers. Thus, we believe a mapper must support quite a few different scenarios. The goal is to promote good coding practices, but not to ignore the fact that there is a lot of legacy code out there that forces us to work a bit differently at times.

Bidirectional

I would say that in many mapping scenarios we need to map in both directions. First we get data from an object in a layer, and map it to an object in the layer above. When that layer is done with manipulating that object, we often want to map it back to down to the layer where it all came from. I have noticed not all mapping frameworks see it this way, and this was one of the reasons why I started working on Glue instead of trying to extend existing frameworks.

Strong verification and testing tools

I want to be absolutely certain that my mapping works. I also want to make sure that it is very hard to break it later. Manually writing tests for mapping is even more tedious than writing manual mapping. Glue automates this. Future changes has a sad reputation of breaking mapping code. Glue helps you detect this. Tools for helping the mapping is very important to me. And more tools will be available in future releases.

Simplicity

Mapping should be simple. Glue tries to simplify both the mapping process, and the verification and testing. You should not have to state the obvious, and Glue support relating properties automatically based on names.

Explicitness

Although Glue enables you to automate much of the mapping process, it also gives you the opportunity to be explicit about the mapping. So if you want to describe every relation in detail, you can. When it comes to understandable code this can be a good thing. Taking difficult to understand implicit mappings, and stating them explicitly can sometimes make things much easier to understand.

Current version and the future

The current version is 0.2.0 Alpha. It is still in Alpha because if we find good ways to improve the API, we do not want to lock ourselves to it just yet, before we get more feedback. I’m guessing the next release will be Beta.

I am currently using Glue on the project I am working on, and in about a month it will reach production. This somewhat guarantees that it will continue to evolve as our needs expand, and that we will find bugs sooner, and they will be fixed sooner.

Looking into the future we have some exciting ideas on tools to help with the mapping, and we are also working hard to make Glue as easy as possible to use, so expect simplifications. In addition we want Glue to serve a broad set of needs, so feedback is highly appreciated and if you explain your special needs, we might just implement it.

You’ll find examples and code here: http://glue.codeplex.com

- Tore Vestues

In my last project we used the ASP.NET MVC framework along with StructureMap, which made us create our own controller factory. I just blogged about it here.

If it was a good design decision or not I am not completely certain anymore, but we added some more framework logic to the controller factory, including checking state on the HttpRequest-object. This, it turned out, was a path to trouble. After a while we had unexpected behavior in our system, sometimes it leaked information between HttpRequests it seemed! But since this only happened during stress testing, it was hard to find the cause.

What we found was that the RequestContext.HttpContext-object was not all the way thread safe. When a request hits our custom controller, and the request goes to sleep to serve another request, the HttpContext of the factory changes to the second requests HttpContext. This means that the first request will work on the second requests HttpContext when it wakes up. This is bad news if you are dependent on the HttpContext in your custom controller factory.

The lesson is this: you have to do at least one of the two actions below if you want to access the HttpContext in your custom controller factory.

1)

The problem occurs when you set your controller factory like this (normally in the global.asax file)

1

ControllerBuilder.Current.SetControllerFactory(new CustomControllerFactory());

If you send in an instance lik this, it will be the only instance of your controller factory, and this is where the HttpContext-concurrency issues arrive in the first place. What you can do, which will take away all the concurrency issues is to send in the type instead of an instance, like this:

1

ControllerBuilder.Current.SetControllerFactory(typeof(CustomControllerFactory));

The drawback to sending in the type is a) your controller factory will be instantiated for every request and b) you cannot send in anything to your instance (since you’re not instantiating it). This might not be a problem, and if not, you’re good to go.

2)

If you have to use one instance only of your controller factory, and you need to access the HttpContext for a request, you MUST use the HttpContext.Current-instance and not the RequestContext.HttpContext. The HttpContext.Current is as far as I’ve tested thread safe.

Not thread safe:

1

RequestContext.HttpContext

The thread safe alternative:

1

HttpContext.Current

I just found out that this is a bug

- Tore Vestues

The ASP.NET MVC framework has a default controller factory (DefaultControllerFactory) that requires all controllers to have a parameterless constructor. So, if you want to inject your dependencies to the constructor, you can’t do it. In addition, Microsoft suggests the following pattern to mock out the dependencies when testing:

The Microsoft way of testing

(Example from www.asp.net/mvc)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

//The Microsoft way...
public class GroupController : Controller
{
    private IContactManagerService _service;
 
    public GroupController()
    {
        _service = new ContactManagerService(new ModelStateWrapper(this.ModelState));
    }
 
    public GroupController(IContactManagerService service)
    {
        _service = service;
    }
    //...
}

In other words, create one constructor for the actual application, and one constructor for testing. It works, you get to test it, it’s not all that bad, but it just doesn’t sit well with me.

Take control of your controllers!

Don’t you like this either? Well, there is an easy way out of it. One of the really good things about ASP.NET MVC is that it is easy to configure. You can create your own controller factory and take control of the whole process. It might sound like a complex task, but it isn’t.

Let’s start with our controller, it has a dependency that is injected through the constructor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

public class HomeController : Controller
{
    private readonly Speaker speaker;
 
    public HomeController(Speaker speaker)
    {
        this.speaker = speaker;
    }
    public ActionResult Index()
    {
        ViewData.Model = speaker;
        return View();
    }
}

Running the website now, trying to reach this controller, will make the framework crash (”No parameterless constructor defined for this object.”). We need our own controller factory to make this work:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

public class StructureMapControllerFactory : DefaultControllerFactory
{
    private readonly IContainer container;
 
    public StructureMapControllerFactory(IContainer container)
    {
        this.container = container;
    }
 
    protected override IController GetControllerInstance(Type controllerType)
    {
        return (IController)container.GetInstance(controllerType);
    }
}

This controller takes in a StructureMap.IContainer and uses it to create all the controllers. It inherits from the DefaultControllerFactory and overrides the GetControllerInstance-method that is used to create controllers.

Now all we have to do is to tell the ASP.NET MVC framework that it should use our controller factory. To do that simply add this line in the Application_Start() method in the Global.asax file:

1

ControllerBuilder.Current.SetControllerFactory(new StructureMapControllerFactory(new Container()));

(Notice that we do not need to configure StructureMap since our dependencies are so easy to resolve. In a real world app you will most probably need to configure the container)

There you go. Using StructureMap with the ASP.NET MVC framework is easy!

Download the complete example here

-Tore Vestues

Børge Hansen from Microsoft is the man behind the camera.

- Tore Vestues

One of the nice things (there are several others!) about dynamic languages like Python is that the code feels much cleaner. It is not bloated with type declarations all over. This clean feel was also the goal of the language Boo, and even though it is a static language, Boo really gives you that dynamic feel.

The question is the of course: Is the C# getting more dynamic?

Well to be honest I do not think so. Having to declare a type at all (even if the declaration is “dynamic”) feels quite static, and the code bloats like static languages. Most of the time. I think it is wrong to think that C# is a more dynamic language due to the dynamic keyword, and I feel you are not using the right tools if you try to use C# as a dynamic language. If you want to write dynamic code, use a dynamic language.

But when we get the dynamic keyword, lets find things to use it for. When I am introduced to new features I am not that interested in all the fancy things you can do with it, I want real value. And I think I have found an example of real value in the dynamic keyword. I’ll give you an example, other than in com-interop, where the dynamic keyword will help you keep your code nice and clean, where otherwise you’d have to write a whole lot of ugly code.

The Quick Xml Reader

The funny thing is that I have already implemented a nice xmlreader in Boo (using the IQuackFoo-interface). When the dynamic keyword was introduced in C# 4 and you’ve got the IDynamicObject from the DLR, I figured I can do the exact same thing in C#. That’s just cool!

So what did I do? Here’s the comment from the Boo code file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

class XmlReader(IQuackFu):
"""
Represents an xmldocument using "dynamic typing". 
Can be used to retrieve single values from the xml-document.
There is no support for retrieving lists.
 
Language: 
 Element: Both nodes and leaves
 Node: an element containing sub-elements
 Leaf: An element that represents a value (in xml this is an attribute or a node with nodetype text)
 
use method names to retrieve nodes, and properties to retrieve leaves
example:
<myXml stat="ok">
	<user id="123" nsid="123">
	    <username>Tore</username>
	    <password>foo</password>
	</user>
</myXml>
 
myXml as duck = XmlReader(xmlString)
myXml //will fail since "myXml" is no leaf
myXml() // will return a new XmlReaderrepresenting the rsp-node with children
myXml().stat // will return "ok"
myXml().user().username // will return "Tore"
"""

How cool is that? This is dynamic, resolved at run time, and it can now be done in C# as well. The point with parsing xml is that you won’t catch errors in the xml structure at compile time anyway. So why not just do the code dynamic?

So, our Xml reader let’s you easily get values from an xml structure without having to declare all the types and without having to worry about all the details of the xml-parsing that normally is a bit complex and frankly, boring. In addition the code is much more readable than normal xml-parsing code.

Xml reading in C#

So, how do we do this in C#? Our XmlReader is a class where you can use any method name or property name on it, and it will still compile. For example, This will compile:

1
2

dynamic ourReader = new XmlReader(xmlString);
ourReader.WhateverMethodNameYouLike();

To do this, the XmlReader needs to inherit the IDynamicObject, and it has to implement the method GetMetaObject that returns a MetaObject.

Simplifying the MetaObject

To implement a MetaObject and do some useful stuff you actually have to understand how to build a Linq expression tree that describes the action to be taken. If people are going to use this, it should be as simple as possible. Building Linq expression trees is not as simple as possible IMHO. So, I’ll make a generic base class that hides the whole MetaObject with its Linq expression trees, and let you override some methods in your XmlReader class instead.

I will not go into details on how I have done this, but if you’re interested, you can look at the source (there’s a link at the end). The ‘magic’ is within the MetaBaseDynamicObject. Together with the BaseDynamicObject these can be reused for different tasks that needs on the fly interpreting of property and method calls.

All you have to do is to inherit the BaseDynamicObject, and override any of these methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public class BaseDynamicObject:IDynamicObject
{
    /// <summary>
    /// If a method on this object is called run time, this method will be called.
    /// </summary>
    /// <param name="action">Information on the method that has been called</param>
    /// <param name="args">parameters on the method call</param>
    /// <returns>The return value for the originally called method</returns>
    public virtual Object Call(CallAction action, object[] args)
 
    /// <summary>
    /// If a property is set on this object run time, this method will be called.
    /// </summary>
    /// <param name="action">Information on the property which value is attemted set</param>
    /// <param name="value">the value that the property is attemted set with</param>    
    public virtual void SetMember(SetMemberAction action, object value)
 
    /// <summary>
    /// If a property is called on this object run time, this method will be called.
    /// </summary>
    /// <param name="action">Information on the property which is being called</param>
    /// <returns>The return value for the property that has been called</returns>
    public virtual Object GetMember(GetMemberAction action) //, MetaObject[] args)
}

Implementing the XmlReader

So what we have to do here is to create a class (XmlReader), inherit the BaseDynamicObject, and override Call and GetMember. We will not bother with SetMember now, as we do not want to support updating the xml. This is what it looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

public class XmlReader:BaseDynamicObject
{
    private readonly XmlElement element;
 
    public XmlReader(string xmlText) {
        var doc = new XmlDocument();
        doc.LoadXml(xmlText);
        element = doc.DocumentElement;
    }
 
    public XmlReader(XmlElement xmlelement)
    {
        element = xmlelement;
    }
 
    public override object Call(CallAction action, object[] args)
    {
        var elements = element.SelectNodes(action.Name);
        if (elements.Count == 0) 
            throw new Exception("Element '" + action.Name + "' doesn't exist in xml");
        if (IsLeaf((XmlElement)elements[0]))
            throw new Exception("Element '" + action.Name + "' is a Leaf and cannot be fetched as a Node");
        return new XmlReader((XmlElement)elements[0]);
    }
 
    public override object GetMember(GetMemberAction action)
    {
        var elements = element.SelectNodes(action.Name);
        if (elements.Count > 0) {
            if (IsLeaf((XmlElement)elements[0]))
                return elements[0].InnerText;
            else
                throw new Exception("Element '"+action.Name+"' is not a Leaf and cannot be fetched one");
        }
 
        var attribute = element.GetAttributeNode(action.Name);
        if (attribute == null)
            throw new Exception("Element '"+action.Name+"' doesn't exist in xml");
        return attribute.Value;
    }
 
    private bool IsLeaf(XmlElement leafElement)
    {
        return leafElement.ChildNodes.Count == 1 &&
            leafElement.ChildNodes[0].NodeType == XmlNodeType.Text;
    }
}

This class now does all the xml-handling. So that means you can do stuff like this:

1
2
3
4
5
6
7
8
9
10
11
12

string xmlString = 
	"<?xml version=\"1.0\" encoding=\"utf-8\" ?>" +
	"<myXml stat=\"ok\">" +
		"<user id=\"321\" nsid=\"123\">" +
		    "<username>Tore</username>" +
		    "<password>foo</password>" +
		"</user>" +
	"</myXml>";
dynamic myXml = new XmlReader(xmlString);
Console.WriteLine(myXml.stat); // "ok"
Console.WriteLine(myXml.user().username); // "Tore"
Console.WriteLine(myXml.user().nsid); // "123"

This is a real declarative and easy way to handle xml, and since xml will only fail run time anyway, there is no argument that you lose compile time checking either.

I hope that has triggered you a bit on some exciting possibilities on using the dynamic type.

Here’s the source. Please remember you will need C# 4.0 to make this work.

Thanks to this and this blog for giving me information and ideas.

-Tore Vestues

Before you read on, these posts might be useful to read:

• Boo Getting Started
• Boo extensions explained
• Boo AstAttributes explained

To create a Macro, you simply have to create a class that inherits from AbstractAstMacro and overrides the Expand-method. In addition your class name must end with “Macro”.

Let’s demonstrate with my DevNull-macro:

1
2
3
4
5
6

import Boo.Lang.Compiler
import Boo.Lang.Compiler.Ast
 
class DevNullMacro(AbstractAstMacro):
	override def Expand(macro as MacroStatement):
		pass

How do you use it? In your code (in a different assembly than where DevNullMacro is situated) you can write something like this:

1
2
3

def DoTheMath(x as int) as int:
	devNull:
		x>0

Here you send in a “Block” to the macro (”X>0″). You can actually also send arguments:

1
2
3

def DoTheMath(x as int) as int:
	devNull x,10,"Hello":
		x>0

So, a Macro can take any number of arguments, and then it takes a block (which can be as big as you like).

Now why did I call this macro DevNull? I did it to demonstrate how the macros work. The point is if you choose to do nothing in the Expand method, nothing will happen. The compiler will actually remove the macro with its arguments and its Block. Meaning that since it is only our macro that handles the code inside the block sent into the macro we can send in whatever we’d like.

This code actually compiles:

1
2
3
4

def DoTheMath(x as int) as int:
	devNull x,10,"Hello":
		x>0
		I_can_write_whatever_here_actually

Ok, so when the compiler hits a macro statement in the compiling code, it finds the macro implementation (in this case the DevNullMacro), and sends it both the arguments and the code block. The compiler then removes all that code, and continues.

(I know this might seem a little confusing. When I started learning Boo it helped quite a lot to look at the compiled code using a tool like Reflector. You should try to write this code and look at it. It will clear up a few things, believe me.)

So what is the point then? The point is that within the macro, you can add code to the code structure. You can of course add whatever you like, but normally you add something based on the input to the macro.

To demonstrate something useful, I will show you how to implement Design By Contract. I have previously demonstrated it in several talks I’ve held, but then I have implemented it as AstAttributes like this:

1
2
3
4
5
6
7
8

class Account:	
	public Balance as int
 
	[Require(amount>=0)]
	[Ensure(Balance == originalBalance + amount)]
	def Deposit(amount as int):
		originalBalance = Balance
		Balance += amount

I will not go into details about this, but I’m pretty sure you will manage to do it yourself after reading my post about AstAttributes.

Now I want to implement Design By Contract as macros, in the same way it is implemented in Eiffel, the language that introduced it. I want to write my assertions like this:

1
2
3
4
5
6
7
8
9
10
11
12

class Account:
 
	public Balance as int
 
	def Deposit(amount as int):
		requires:
			amount>=0
		body:
			originalBalance = Balance
			Balance += amount
		ensures:
			Balance == originalBalance + amount

We have three macros here: requires, body, and ensures. I’m going to show you in detail how to implement the requires-part of the code, then I’ll add the source for both body and ensures as well. When we hit the requires macro in the code, we’re going to replace it with some actual code that forces those requirements. So, where we find this code in our Deposit-method,

1
2

requires:
	amount>=0

we want, at compile time, to put something like this to the output assembly:

1
2

if not (amount>=0):
	raise Exception("Some suitable error message")

To add code where the macro statement is situated, we simply return a Statement from our Expand-method. What we want to make is a Block (which is a derived type of Statement):

1
2
3

override def Expand(macro as MacroStatement) as Statement:
	blockToReturn = Block()
	return blockToReturn

Still nothing happens, since we’re just returning an empty Block. We have to fill the return block with something. So for each assertion (which turns out as Statements) in our code, we want to assert it. Let’s loop all our statements:

1
2
3
4
5
6
7
8
9

override def Expand(macro as MacroStatement) as Statement:
	blockToReturn = Block()
 
	for statement in macro.Block.Statements:
		expression as BinaryExpression = TryMakeBinaryExpression(statement)
		blockToReturn.Add(
			CreateAssertblockFromBinaryExpression(expression))
 
	return blockToReturn

In addition to the looping, which is pretty straight forward, we’re doing two new things here. We’re trying to turn every statement into a BinaryExpression, and we’re creating blocks for each BinaryExpression.

Let’s look at our TryMakeBinaryExpression first. The point is that if we want to assert something, we have to make sure they resolve to either true or false. First we need all the Statements to be ExpressionStatements. If you for instance had written an if-statement in you macro like this:

1
2
3

requires:
	if 1==1:
		do_something

This will not be an ExpressionStatement, it is an IfStatement (you should look into the Boo class-hierarchy, use Visual studio or Reflector).

So, when we have assured us it is all ExpressionStatements we have to deal with, we also want to ensure they are all BinaryExpressions. They all have to resolve into either true or false. Both of these checks are run here:

1
2
3
4
5
6
7
8
9
10

def TryMakeBinaryExpression(statement as Statement) as BinaryExpression:
	expression = statement as ExpressionStatement 
	if expression is null:
		RaiseNotBinaryException(statement.ToString())
 
	binaryexpression = expression.Expression as BinaryExpression 
	if binaryexpression is null:
		RaiseNotBinaryException(expression.Expression.ToString())
 
	return binaryexpression

Ok, now we either have a BinaryExpression or it has already failed. Let’s make it into a block:

1
2
3
4
5
6
7

def CreateAssertblockFromBinaryExpression(expression as BinaryExpression) as Block:
	exceptionText = "Voilated precondition: " + expression.ToString()
	return [|
			block:
				if not $(expression):
					raise Exception($exceptionText)
		|].Block

Here we’re using quasiquotations again. It’s understandable and easy to both read and write.

And that’s the complete macro. So now for every BinaryExpression written, the macro will assert its correctness. Here’s the complete code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

import System
import Boo.Lang.Compiler
import Boo.Lang.Compiler.Ast
 
class RequiresMacro(AbstractAstMacro):
 
	override def Expand(macro as MacroStatement) as Statement:
		blockToReturn = Block()
		for statement in macro.Block.Statements:
			expression as BinaryExpression = TryMakeBinaryExpression(statement)
			blockToReturn.Add(
				CreateAssertblockFromBinaryExpression(expression))
		return blockToReturn
 
	def CreateAssertblockFromBinaryExpression(expression as BinaryExpression) as Block:
		exceptionText = "Voilated precondition: " + expression.ToString()
		return [|
				block:
					if not $(expression):
						raise Exception($exceptionText)
			|].Block
 
	def TryMakeBinaryExpression(statement as Statement) as BinaryExpression:
		expression = statement as ExpressionStatement 
		if expression is null:
			RaiseNotBinaryException(statement.ToString())
 
		binaryexpression = expression.Expression as BinaryExpression 
		if binaryexpression is null:
			RaiseNotBinaryException(expression.Expression.ToString())
 
		return binaryexpression
 
	def RaiseNotBinaryException(typeInfo as String):
		raise Exception("Not a binary expression: " + typeInfo)

The other two macros, BodyMacro and EnsuresMacro are listed here:

1
2
3
4
5
6
7
8

import System
import Boo.Lang.Compiler
import Boo.Lang.Compiler.Ast
 
class BodyMacro(AbstractAstMacro):
 
	override def Expand(macro as MacroStatement) as Statement:
		return macro.Block

Here we only need to return the actual code written within the macro.

And here’s the EnsuresMacro:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import System
import Boo.Lang.Compiler
import Boo.Lang.Compiler.Ast
 
class EnsuresMacro(AbstractAstMacro):
 
	override def Expand(macro as MacroStatement):
		ancestor as Method = macro.GetAncestor(NodeType.Method)
 
		oldBody as Block = ancestor.Body
		ensuresBody as Block = RequiresMacro().Expand(macro)
		newBody = [|
			block:
				try:
					$oldBody
				ensure:
					$ensuresBody
		|].Block
 
		ancestor.Body = newBody

Here we take all the code in the method containing the macro, and surrounds it with a try-clause to ensure that we always run the ensures-part of the code. Notice also that we’re using the RequireMacro, since it creates the assert-block exactly the way we want it.

A helping hand:
When you explore this, I actually advice you to write some of your macro code in C#, as it gives you a lot more intellisense-help, then when you have found out what you want, write them back in Boo, as it is often much more readable, especially with the nice quasiquotation which you do not have in C#.

Hope it helps!

- Tore Vestues