Metalama.Extensions.Interceptors.Redist 2027.0.4-preview

Metalama.Extensions.Interceptors.Redist

This package contains the API of Metalama.Extensions.Interceptors, which lets aspects and fabrics intercept the uses of methods: it replaces a call, or a method group converted to a delegate or to a function pointer, with a use of an interceptor method.

Reference this package from a library whose aspects or fabrics register interceptors. The package Metalama.Extensions.Interceptors, which contains the engine, must be referenced by the project in which the interception happens.

An interception is registered with InterceptMethods, whose delegate describes it as a chain of immutable values. The chain sets where the call sites are, selects the intercepted methods, chooses how the calls are intercepted, and sets the options of a synthesized method:

builder.InterceptMethods( b => b
    .Type( typeof(Console) ).Methods( "WriteLine" )
    .RedirectToSynthesizedMethod( nameof(this.Log) )
    .WithGranularity( InterceptorGranularity.Member ) );

Each method returns a new value and leaves the value on which it is called unchanged. A value that the delegate creates and does not use, for instance a call of WithGranularity whose result is not assigned, is reported as an error when the delegate returns. The calls can be redirected to an existing method with RedirectToExistingMethod, to a method synthesized from a template with RedirectToSynthesizedMethod, or decided for each call site with ForEachSite. Its delegate receives the call site, an IMethodInterceptionSite, which describes the site and creates its result, for instance site => site.Caller.IsInAsyncFunction ? site.Skip() : site.RedirectToSynthesizedMethod( "Log" ).

Only call sites written in the source code are intercepted. A call that the compiler, the runtime or a library makes on behalf of the code is not intercepted, because no call exists at the site. For instance, ToString cannot be intercepted reliably: an interpolated string, a string concatenation, Console.WriteLine( object ) and StringBuilder.Append( object ) call it inside the runtime. The same applies to Equals and GetHashCode called by collections, to Dispose called by a using statement, and to GetEnumerator called by a foreach statement.

Interceptor methods synthesized from templates, and the classes that contain them, are added when the code is linked, after all aspects have executed. They are not visible in the code model to aspects, in any stage of the pipeline, and they are not in the code that the IDE generates. A delegate given to ITemplateInterception.Configure shapes the synthesized method through IInterceptorMethodBuilder.Method, which is a detached method builder: its declaring type does not list it.

The placement of the synthesized method is set with ITemplateInterception.PlaceInStaticClass, PlaceInCallingType or PlaceInType, and its granularity with ITemplateInterception.WithGranularity. By default, the method is synthesized in the class MetalamaInterceptors with the Global granularity, so it is shared by all the call sites that have the same template, arguments, tags and signature. The engine does not detect what the template depends on: the template is expanded once, for the first of these call sites in the order of the file paths and positions, and with the aspect instance of that call site, as when several instances of an aspect target one declaration. A template that reads the calling type, the calling member or the call site through the meta.Interception property needs the Type, Member or CallSite granularity, and a template that depends on the state of its aspect instance needs the Owner granularity.

A delegate given to ITemplateInterception.Configure can add type parameters to the synthesized method, after the type parameters that come from the intercepted method, and give their type arguments at each call site with the IInterceptorMethodBuilder.SetTypeArgument method. The IInterceptorMethodBuilder.SetArgument method likewise gives the value of an added parameter at each call site, from the context of the call site. The type arguments are not part of the deduplication key, so the call sites whose arguments have different types can share one generic interceptor method, even when the template is not generic.