This is the fifth, and for now, last, of my series of posts on AspectMap. If you’re new to AspectMap, I’d recommend you start at the beginning and work your way through the tutorials:

• AspectMap 1 Released!
• Part 1 - Getting Started
• Part 2 - An Exception Handling Helper
• Part 3 - A Retry Aspect (or, Inspecting the Source Attribute)
• Part 4 - Multicast Attribuites

Aspect Nesting

This is a fairly easy concept to grasp. When you add an aspect to a method you are wrapping its logic with that of the attribute handler. If you add a second aspect to the same method you are wrapping both the logic of the method and the first attribute handler within the second – nesting them.

We’ll illustrate this with a simple example and a couple of unit tests. Firstly create a new test class:

[TestClass]
public class NestingTests
{
  private static string _output;
}

Notice the _output variable, this will be used to pass information between the aspects and the tests. All the following classes should be created inside the test class. Next up are our attributes and handlers:

public class NestingLevel1Attribute : Attribute {}
public class NestingLevel2Attribute : Attribute {}

public class Level1Handler : AttributeHandler
{
  public override Action<IInvocation> Surround(Action<IInvocation> invocation,
      Attribute sourceAttribute)
  {
    return i =>
    {
      _output += "Level1 Entered\n";
      Console.WriteLine("Level1 Entered");
      invocation(i);
      _output += "Level1 Exited\n";
      Console.WriteLine("Level1 Exited");
    };
  }
 }

public class Level2Handler : AttributeHandler
{
  public override Action<IInvocation> Surround(Action<IInvocation> invocation,
      Attribute sourceAttribute)
  {
    return i =>
    {
      _output += "Level2 Entered\n";
      Console.WriteLine("Level2 Entered");
      invocation(i);
      _output += "Level2 Exited\n";
      Console.WriteLine("Level2 Exited");
    };
  }
}

Nothing complicated, we simply add text to both the _output variable and write it to the console (for ease of testing). Next up a really simple test class:

public interface ITestClass
{
  void DoSomething();
}

public class ItemWithMultipleAttributes : ITestClass
{
  [NestingLevel1]
  [NestingLevel2]
  public void DoSomething()
  {
    _output += "DoSomething\n";
    Console.WriteLine("DoSomething");
  }
}

The DoSomething method just writes to the _output variable, and applies both of our aspects. The final stage of setup is a registry to wire it all together:

public class NestingRegistry : AspectsRegistry
{
  public NestingRegistry()
  {
    ForAspect<NestingLevel1Attribute>().HandleWith<Level1Handler>();
    ForAspect<NestingLevel2Attribute>().HandleWith<Level2Handler>();
    For<ITestClass>().Use<ItemWithMultipleAttributes>().
        EnrichWith(AddAspectsTo<ITestClass>);
  }
}

It’s worth pausing at this point to go through how AspectMap will order your aspects by default. From now on I will use the terms closer and further away for this – closer means that the aspect wraps closer to the source method, further away is at a further remove, wrapping the method and other aspects. All control over this prioritisation occurs in your registry, not in the classes, although I plan to add priorities at this level in a future release.

When writing your ForAspect declarations, those that appear first will be applied closer to the source method. We can confirm this with a test:

[TestMethod]
public void NestingUsesCorrectOrder()
{
  ObjectFactory.Initialize(x => x.AddRegistry(new NestingRegistry()));

  ITestClass testClass = ObjectFactory.GetInstance<ITestClass>();
  _output = "";

  testClass.DoSomething();

  Assert.AreEqual("Level2 Entered\nLevel1 Entered\nDoSomething\nLevel1 Exited\nLevel2 Exited\n", _output);

  ObjectFactory.ResetDefaults();
}

If you run this and look in your results window you should see the following from the Console.WriteLine statements:

Level2 Entered
Level1 Entered
DoSomething
Level1 Exited
Level2 Exited

Prioritising

Great. But what about situations where you’d like to define which aspect has priority? You can control this with the WithPriority method in your registry:

ForAspect<NestingLevel1Attribute>().WithPriority(1).HandleWith<Level1Handler>();
ForAspect<NestingLevel2Attribute>().WithPriority(2).HandleWith<Level2Handler>();

Aspects with a higher priority will be applied closer to the source method. You can confirm this by making the change above and re-running your test. It will fail, but the console will now read:

Level1 Entered

Level2 Entered
DoSomething
Level2 Exited
Level1 Exited

Awesome. You should now have all the skills you need to use AspectMap in any of your applications!

This is it from me on AspectMap for a while – I’ll be concentrating on adding a few new features for a 1.5 release in the fairly near future, and the source will be available on codeplex this week. I’m totally open to input as to what is in this next release so feel free to get in touch on here or through twitter, or even better, get involved when I open source it.  Thanks for reading!

After reading this post from Sayed (a great blogger by the way!) I downloaded and installed the VS2010 Web Publish Updates. All was well until I realised that all my WiX projects were now showing as unavailable in solution explorer. The system is failing looking for a .wpp.targets file which does not exist. I've tried all sorts of things including:

• creating the file it wants (it still thinks it doesn't exist)
• overriding the publish profile properties in the wixproj file (no change)
• using alternative targets (no change)

After 4hrs of digging around in the 10.5 targets files I'm drawing a blank on all fronts. I'll keep working on it but in the meantime I'd recommend staying off the upgrade.

If you're a brave soul and want to help me fix this, I'm keeping a question on StackOverflow updated with my attempts, get involved!

This is part 4 of my series of posts on AspectMap. If you’re new to AspectMap I’d recommend you start at the beginning and work your way through the tutorials:

• AspectMap 1 Released!
• Part 1 - Getting Started
• Part 2 - An Exception Handling Helper
• Part 3 - A Retry Aspect (or, Inspecting the Source Attribute)

What Is Multicasting?

Multicasting is most often associated with networking, where it refers to the delivery of a message to multiple destinations at once from a single source. We are using the same concept here to describe the application of a single aspect to multiple methods, using a single attribute declaration. Let’s skip to an example:

public class AnImportantClass : IDoesImportantStuff
{
  [Auditable]
  public void DoSomething()
  {
    // Does something important
  }

  [Auditable]
  public void DoSomethingMoreImportant()
  {
    // Does something more important
  }
}

We have a couple of methods here, both marked with the AuditableAttribute, which we can wire up in an AspectsRegistry as normal to do some auditing stuff. AspectMap will allow you to wire this up via a single attribute at the class level:

[Auditable]
public class AnImportantClass : IDoesImportantStuff
{
  public void DoSomething()
  {
    // Does something important
  }

  public void DoSomethingMoreImportant()
  {
    // Does something more important
  }
}

This will do the equivalent of applying the attribute to every single method on the class. This works fine for attributes without properties, but what about a scenario this, where you are passing configuration information with the attribute?

public class AnImportantClass : IDoesImportantStuff
{
  [Auditable(15)]
  public void DoSomething()
  {
    // Does something important
  }

  [Auditable(15)]
  public void DoSomethingMoreImportant()
  {
    // Does something more important
  }

  [Auditable(20)]
  public void AnExtraImportantMethod()
  {
    // This requires more detailed auditing
  }
}

You can actually define a default attribute at class level, and then override it on methods which need something more specific:

[Auditable(15)]
public class AnImportantClass : IDoesImportantStuff
{
  public void DoSomething()
  {
    // Does something important
  }

  public void DoSomethingMoreImportant()
  {
    // Does something more important
  }

  [Auditable(20)]
  public void AnExtraImportantMethod()
  {
    // This requires more detailed auditing
  }
}

Quick and easy. I hope all this information is useful to some of you, and the post on nesting and prioritising aspects will be up in the next few days.

This is part 3 of my series of posts on using AspectMap – an aspect oriented framework for StructureMap. If you’re new to AspectMap I’d recommend starting at the beginning and working through the series:

• AspectMap 1 Released!
• Part 1 - Getting Started
• Part 2 - An Exception Handling Helper

In this post we’ll create a retry aspect which will allow you to retry the functionality of a method a specified number of times for a certain exception. For instance you could set a method up to try some SQL operation up to 4 times if it receives timeout exceptions. This will introduce you to the technique for inspecting the attribute that kicked off your handler.

We’ll start with the attribute:

public class RetryAttribute : Attribute
{
  public RetryAttribute(int maxTries, Type targetException)
  {
    MaxTries = maxTries;
    TargetException = targetException;
  }

  public int MaxTries { get; set; }
  public Type TargetException { get; set; }
}

Notice that it has two properties, populated through the constructor. TargetException is the exception which will trigger a retry, and MaxTries is the maximum number of attempts that will be made. This would be specified on a method like this:

[Retry(3, typeof(TimeoutException))]
public void CompleteLongRunningOperation()
{
  // Long running code which could throw a TimeoutException
}

So this will allow two retries of a TimeoutException before finally throwing it. Any other exception will be thrown as usual.

So, how do we implement the handler? Create a new RetryAttributeHandler inheriting from AttributeHandler and put the following code into its Surround method:

if (!(sourceAttribute is RetryAttribute))
  throw new ArgumentException("Unable to handle retries for attribute '" +
    sourceAttribute.GetType() + "'.");

RetryAttribute attribute = (RetryAttribute)sourceAttribute;

Fairly simple, we only want to deal with RetryAttributes. Next comes the important bit:

return i =>
{
  for (int count = 1; count <= attribute.MaxTries; count++)
  {
    try
    {
      invocation(i);
      return;
    }
    catch (Exception ex)
    {
      if (ex.GetType() != attribute.TargetException ||
                   count == attribute.MaxTries)
        throw;
    }
  }
};

We loop until MaxTries, and if an exception is thrown we check if we are on the last try, or the exception is not of the expected type. If so we throw it, otherwise we continue around the loop. The return statement ensures that if invocation(i) run’s successfully that we don’t continue round and do it again!

That’s pretty much it, you wire up your registry just like we did in previous posts:

ForAspect<RetryAttribute>().HandleWith<RetryAttributeHandler>();
For<ITestClass>().Use<MyClass>().EnrichWith(AddAspectsTo<ITestClass>);

One thing which I hope is becoming clear now is that there never seems to be much actual code involved – if you can think of a concern cross cutting enough, it will generally be generic enough to make the coding of it trivial. Which I see as a great thing!

Next up I’ll discuss nesting and prioritisation of handlers, at which point you’ll have all the major skills you need to go out and start creating some really funky stuff. Thanks for reading!

Welcome back to my series on using AspectMap – an aspect oriented framework for StructureMap. If you’re new then take a look at the earlier posts on the subject:

• Aspect Map 1 Released!
• Part 1 - Getting Started

In this post I’ll walk you through the setup of a generic exception handler which can be assigned to any code you like with the addition of a single attribute. Let’s get started!

Keeping it generic, the first thing we’ll create is a new interface for handling any exception:

public interface IExceptionHandler
{
  void HandleException(Exception ex);
}

You can create your own implementation of this which can do anything you like, log to Elmah, redirect to an error web page, send an email, whatever. Next we will create a new AttributeHandler called ExceptionAttributeHandler:

public class ExceptionAttributeHandler : AttributeHandler
{
  public ExceptionAttributeHandler(IExceptionHandler exceptionHandler)
  {
    ExceptionHandler = exceptionHandler;
  }

  public IExceptionHandler ExceptionHandler { get; set; }

  public override Action<IInvocation> Surround(Action<IInvocation> invocation,
    Attribute sourceAttribute)
  {
    throw new NotImplementedException();
  }
}

Notice the ExceptionHandler attribute and constructor, which allows us to inject our custom handler via StructureMap. Next, in the Surround method, replace the NotImplementedException with:

return i =>
{
   try
  {
    invocation(i);
  }
  catch (Exception ex)
  {
    ExceptionHandler.HandleException(ex);
    throw;
  }
};

This is just like we did with the LoggingHandler except that this time we’re nesting the invocation call within other code, and farming out the actual logic of what happens when an exception occurs to our custom IExceptionHandler class. After handling the exception, we continue to throw it.

Which is a problem.

Think about it, let’s say you are logging to Elmah and are quite happy to have the application fail after the error is logged. You will get the error logged at every point down your call stack where this aspect is applied, for a single error. We’ll fix this by creating a new HandledException class:

public class HandledException : Exception
{
  public HandledException(Exception innerException) :
    base(innerException.Message, innerException)
  {}
}

And checking the exception type in the catch block of the Surround method:

catch (Exception ex)
{
  if (!(ex is HandledException))
  {
    ExceptionHandler.HandleException(ex);
    throw new HandledException(ex);
  }
  throw;
}

Great, now you’ll handle the exception once, and get a HandledException raised by the application.

All we need to do now is create an attribute to use for the mapping:

public class ExceptionHandleAttribute : Attribute
{}

That is all the handler setup done, but we still need to wire it up to your application. Ensure that your registry inherits from AspectsRegistry and add the following lines, replacing the items in capitals with your own classes:

ForAspect<ExceptionHandleAttribute>().HandleWith<ExceptionAttributeHandler>();
For<IExceptionHandler>().Use<YOUREXCEPTIONHANDLER>();

For<IYOURCLASS>().Use<YOURCLASS>().EnrichWith(AddAspectsTo<IYOURCLASS>);

Now any methods you mark with the ExceptionHandle attribute in YOURCLASS will be automatically handled for you by your IExceptionHandler implementation.

Next time I’ll cover either a code security handler which will go into inspecting the attribute which triggered the handler code, or how to nest and prioritise multiple handlers. If you want one before the other, leave me a message in the comments and I’ll get to it. All the handlers I’m creating here will be included out of the box in a new AspectMap release some point soon too.