Pygmalions.Nebula.Proxying 0.1.1

Nebula Proxying

Fundamental library of Pygmalions' Nebula Framework.

This library provides proxy interfaces, a proxy class generator and aspect handler mechanism.

Concepts

Proxy Class

A proxy class is the class type generated by proxy generator, which overrides virtual methods marked with Proxy attribute.

When those generated method are invoked, they will firstly trigger the Invoking event, then invoke the Invoker action delegate, which will invoke the proxied method by default, and finally trigger the Triggered event.

Aspect Handler

The generator will generate a ProxyEntry for each proxied method, when these proxy entries are initialized in the constructor, the generator will pass them to the registered aspect handlers. And then, the aspect handlers can add event subscribers to the proxy entry, or change the invoker of it, in order to dynamically change the behavior of the proxy method.

The proxy entry will be passed the aspect handlers of the corresponding aspects marked on the proxied method.

An aspect is a attribute class inherited from AspectTrigger class. You can declare aspects in the [AspectHandler] attribute marked on aspect handler classes. Then, proxy entries which has a the corresponding aspect attribute marked on its proxied method will be passed to this aspect handler.

How to Use

Proxy

This code shows how to get the arguments and returning value of an invocation on the proxy method:

var refraction = Proxies.Get<SampleObject>();
var testSample = Activator.CreateInstance(refraction) as SampleObject;
var provider = testSample as IProxyObject;
var proxy = provider!.GetProxy(typeof(SampleObject).GetMethod(nameof(SampleObject.AddNumber))!);
bool invokingTriggered = false, invokedTriggered = false;
var argument = -1;
proxy!.Invoking += context =>
{
    invokingTriggered = true;
    if (context.Arguments[0] is int parameter)
        argument = parameter;
    context.Arguments[0] = 5;
};
var returningValue = -1;
proxy.Invoked += context =>
{
    invokedTriggered = true;
    if (context.Result is int value)
        returningValue = value;
    context.Return(10);
};
var initialNumber = testSample!.Number;
var result = testSample.AddNumber(3);

This is a sample aspect handler, which will record all proxy entries.

[AspectHandler(typeof(ProxyAttribute))]
public class SampleGeneratorPlugin : AspectHandler
{
    public static List<ProxyEntry> GeneratedProxies { get; } = new();

    public override void Handle(ProxyEntry proxy)
    {
        GeneratedProxies.Add(proxy);
    }
}

Remarks

This library is under rapid development, thus its API may be very unstable, DO NOT use it in the production environment, until its version reaches 1.0.0.