Decorators, Interceptors, and Activators #

Lamar v5 finally added the full complement of interceptors that users have grown to expect from .Net IoC containers. To differentiate between the three terms, Lamar now supports:

1. Decorators - the classic Gang of Four Decorator pattern where at runtime Lamar will "wrap" a concrete decorator object around the registered service
2. Interceptors - in a user supplied Lambda, get a chance to work with the newly built object or even return a different object with a possibly dynamic proxy
3. Activators - a user supplied Lambda that is called right after an object is created by Lamar, but before it is returned to the caller

Decorators #

If you look in the Lamar codebase, you'll find dozens of tests that use a fake type named IWidget that does something:

public interface IWidget
{
    void DoSomething();
}

^{snippet source | anchor}

Let's say that we have service registrations in our system for that IWidget interface, but we want each of them to be decorated by another form of IWidget like this to perform some kind of cross cutting concern before and/or after the call to the specific widget:

public class WidgetDecorator : IWidget
{
    public WidgetDecorator(IThing thing, IWidget inner)
    {
        Inner = inner;
    }

    public IWidget Inner { get; }

    public void DoSomething()
    {
        // do something before 
        Inner.DoSomething();
        // do something after
    }
}

^{snippet source | anchor}

We can configure Lamar to add a decorator around all other IWidget registrations with this syntax:

var container = new Container(_ =>
{
    // This usage adds the WidgetHolder as a decorator
    // on all IWidget registrations
    _.For<IWidget>().DecorateAllWith<WidgetDecorator>();

    // The AWidget type will be decorated w/ 
    // WidgetHolder when you resolve it from the container
    _.For<IWidget>().Use<AWidget>();

    _.For<IThing>().Use<Thing>();
});

// Just proving that it actually works;)
container.GetInstance<IWidget>()
    .ShouldBeOfType<WidgetDecorator>()
    .Inner.ShouldBeOfType<AWidget>();

^{snippet source | anchor}

Activators #

An activator gives you the chance to make some kind of call against an object that has just been built by Lamar, but before that object is passed to the original service requester.

As an example, let's say that you have some sort of service in your system that is responsible for polling an external web service for more information. If you're like me, you really don't like to perform any kind of work besides putting together necessary state in a constructor function, so you likely have some kind of Start() method on the polling service to actually start things up like this class:

public class Poller : IPoller
{
    public void Dispose()
    {
        // stop polling
    }

    public void Start()
    {
        // start the actual polling
    }
}

^{snippet source | anchor}

When we register the class above with Lamar, we can supply a Lambda function to start up Poller like this:

var container = new Container(x =>
{
    x.For<IPoller>().Use<Poller>()

        // This registers an activator on just this
        // one registration
        .OnCreation(poller => poller.Start());
});

^{snippet source | anchor}

In the sample above, we registered an activator on one and only one service registration. Lamar will also let you apply an activator across service registrations that implement or inherit from a common type. Back to the polling example, what if we introduce a new marker interface to denote objects that need to be started or activated like this:

public interface IStartable : IDisposable
{
    void Start();
}

^{snippet source | anchor}

public interface IStartable
{
    bool WasStarted { get; }

    void Start();
}

^{snippet source | anchor}

public interface IStartable
{
    bool WasStarted { get; }

    void Start();
}

^{snippet source | anchor}

Now, let's create a new StartablePoller:

public class StartablePoller : IPoller, IStartable
{
    public void Dispose()
    {
        // shut things down
    }

    public void Start()
    {
        // start up the polling
    }
}

^{snippet source | anchor}

And going back to the IPoller registration, we could now do this:

var container = new Container(services =>
{
    // Remember that Lamar natively understands .Net
    // DI registrations w/o any adapter
    services.AddSingleton<IPoller, StartablePoller>();

    // Other registrations that might include other 
    // IStartable types

    services.For<IStartable>()
        .OnCreationForAll(x => x.Start());
});

^{snippet source | anchor}

The call to For<T>().OnCreationForAll(Action<T>) will apply to any registrations of type T or any registrations where the implementation type can be cast to T. So in th case above, the activator will be applied to the StartablePoller type.

As a last example, you also have an overload to use the constructing container in an activator if you need access to other services. Let's say that for some kind of diagnostic in our system, we want to track what IStartable objects have been created and floating around in our system at any time with this simple class:

public class StartableTracker
{
    public List<IStartable> Startables { get; } = new();
}

^{snippet source | anchor}

Now, we'd like our IStartable objects to both Start() and be tracked by the class above, so we'll use an activator like this:

var container = new Container(services =>
{
    services.AddSingleton<IPoller, StartablePoller>();

    // Other registrations that might include other 
    // IStartable types

    services.AddSingleton<StartableTracker>();

    services.For<IStartable>()
        .OnCreationForAll((context, startable) =>
        {
            var tracker = context.GetInstance<StartableTracker>();
            tracker.Startables.Add(startable);

            startable.Start();
        });
});

^{snippet source | anchor}

Interceptors #

Interceptors are similar to activators, but with two differences:

1. Interceptors allow you to return a different object than the one initially created by Lamar
2. Because of the potential to return a new object, interceptors are applied at the service type level

Here's a sample from the unit tests:

[Fact]
public void intercept_a_single_instance()
{
    var container = new Container(x =>
    {
        x.For<IWidget>().Add<ActivatedWidget>()
            .Named("yes")
            .OnCreation(w => new DecoratedWidget(w));

        x.For<IWidget>().Add<ActivatedWidget>().Named("no");
    });

    container.GetInstance<IWidget>("yes")
        .ShouldBeOfType<DecoratedWidget>()
        .Inner.ShouldBeOfType<ActivatedWidget>();

    container.GetInstance<IWidget>("no")
        .ShouldBeOfType<ActivatedWidget>();
}

^{snippet source | anchor}

Just like activators, there is the option to only use the original object or the ability to use the original object and the constructing container.