Aspect Injector

An Advice Effect is code that can be injected into a method, property, or event.

To define advice, create a class (an aspect) containing methods marked with the [Advice] attribute. The attribute requires a Kind parameter to determine when the code executes relative to the target method.

Advice Kinds

• Kind.Before: Executed before the method begins. For constructors, this runs after the base class constructor but before the target constructor body.
• Kind.After: Executed after the method ends.
• Kind.Around: Executed instead of the target method. You can optionally call the original method within this advice. Note: Around advice must return an object that can be cast to the target method's return type. If the target returns void, the advice must return null. Around advice cannot be applied to constructors.

    [Advice(Kind.Before)]
    public void LogEnter() {
        Console.WriteLine("Entering ...");
    }

    [Advice(Kind.After)]
    public void LogExit() {
        Console.WriteLine("Leaving ...");
    }

    [Advice(Kind.Around)]
    public object LogAndMeasureTimings(...) {
        // ... implementation ...
    }
}

Mixins allow you to add new logic or properties to a target object by automatically implementing interfaces. When an aspect contains a mixin, it creates members on the target object that match the interface's members and proxies them back to the aspect instance.

To use a Mixin, follow these steps:

1. Define an interface describing the features you want to add.
2. Create an aspect that implements that interface and is decorated with the [Mixin] attribute pointing to the interface type.
3. Apply the aspect to the target class or a specific member of the target class.

Note: You do not need to apply the aspect to the class itself; applying it to any member of the class is sufficient to trigger the injection.

// 1. Define the interface
public interface IHaveProperty
{
  string Data { get; set; }
}

// 2. Create the aspect implementing the interface
[Aspect(Scope.Global)]
[Injection(typeof(MyAspect))]
[Mixin(typeof(IHaveProperty))]
public class MyAspect : Attribute, IHaveProperty 
{
  public string Data { get; set; }
}

// 3. Apply to the target
[MyAspect]
public class Target
{
  public void Do() {}
}

In AspectInjector, injection is performed by applying a trigger attribute to a target (class, method, etc.).

To implement this, you must follow two steps:

1. Define an Aspect: Create a class and mark it with the [Aspect] attribute.
2. Define a Trigger: Create a .NET attribute class and mark it with the [Injection] attribute, passing the type of the aspect you want to trigger.

Note that a trigger is only an "attempt" to inject. The aspect itself decides whether to execute based on its internal logic (e.g., if an aspect is configured to only target public members, applying its trigger to a private member will result in no injection).

// 1. Defining the aspect
[Aspect(Scope.Global)]
class LogAspect {}

// 2. Defining the trigger
[Injection(typeof(LogAspect))]
class Log : Attribute {}

// 3. Applying the trigger to a target
class TestClass {
    [Log]
    public void DoSomething() {}
}

AspectInjector is a compile-time Aspect-Oriented Programming (AOP) framework. Unlike runtime AOP frameworks that use reflection or proxies at execution time, AspectInjector modifies your assembly during compilation.

This means the 'weaving' of aspects into your code happens before the application runs, resulting in zero performance overhead during execution. The framework injects direct calls to the aspect instances into your methods, making the cross-cutting concerns as efficient as manual code.

// Before compilation (User Code):
[Aspect(Scope.Global)]
[Injection(typeof(Log))]
class Log : Attribute
{
    [Advice(Kind.Before, Targets = Target.Method)]
    public void OnEntry([Argument(Source.Name)] string name)
    {
        Console.WriteLine($"Entering method {name}");
    }
}

class TestClass
{
    [Log]
    public void Do()
    {
        Console.WriteLine($"Done");
    }
}

// After compilation (What actually runs):
[Aspect(Scope.Global)]
[Injection(typeof(Log))]
class Log : Attribute
{
    public static readonly Log __a$_instance;

    [Advice(Kind.Before, Targets = Target.Method)]
    public void OnEntry([Argument(Source.Name)] string name)
    {
        Console.WriteLine($"Entering method {name}");
    }

    static Log()
    {
        __a$_instance = new Log();
    }
}

internal class TestClass
{
    [Log]
    public void Do()
    {
        Log.__a$_instance.OnEntry("Do");
        Console.WriteLine($"Done");
    }
}