Metalama 1.0 / / Metalama Documentation / Aspect API / Metalama.​Framework.​Aspects

Namespace Metalama.Framework.Aspects

This is namespace allows you to build aspects. Aspects are an algorithmic representation of a code transformation or validation.

For instance, adding logging to a method, or implementing INotifyPropertyChanged, can to a great extent be expressed as an algorithm and therefore implemented as an aspect.

Conceptual Documentation

See Creating Aspects.

Overview

To create an aspect, create a class that derives from Attribute and implement the IAspect<T> interface. Alternatively, you can use one of the following classes, which already XX derive from Attribute, have the proper AttributeUsageAttribute, and implement the IAspect<T> interface:

Class Diagrams

Aspect builders

classDiagram class IAspect { BuildAspect(IAspectBuilder) } class IAspectBuilder { SkipAspect() TargetDeclaration AdviceFactory } class IAdviceFactory { Override(...) Introduce*(...) AddInitializer*(...) } class IDiagnosticSink { Report(...) Suppress(...) } IAspect --> IAspectBuilder : BuildAspect() receives IAspectBuilder --> IAdviceFactory : exposes IAspectBuilder --> IDiagnosticSink : exposes

Scope custom attributes

classDiagram CompileTimeAttribute --|> ScopeAttribute : derives from CompileTimeAttribute --|> ScopeAttribute : derives from RunTimeOnlyAttribute --|> ScopeAttribute : derives from TemplateAttribute --|> CompileTimeAttribute : derives from AdviceAttribute --|> TemplateAttribute : derives from IntroduceAttribute --|> AdviceAttribute : derives from InterfaceMemberAttribute --|> TemplateAttribute : derives from class CompileTimeAttribute class RunTimeOnlyAttribute

Adding child aspects and validators

classDiagram IAspect --> IAspectBuilder : receives class IAspectBuilder { } class IDeclarationSelector { With() } IAspectBuilder --|> IDeclarationSelector : derives from class IDeclarationSelection { AddAspect() AddAnnotation() RegisterValidator() RequireAspect() } IDeclarationSelector --> IDeclarationSelection : creates

IAspectInstance, IAspectPredecessor

The IAspectPredecessor facility allows aspects to access their parent (i.e. the artifact that created them): a parent aspect, a fabric, or a custom attribute.

classDiagram IAspect --> IAspectBuilder : receives class IAspect { BuildAspect(IAspectBuilder) } class IAspectBuilder { AspectInstance } class IAspectState { } class IAttribute { ContainingDeclaration Type Constructor ConstructorArguments NamedArguments } IAspectBuilder --> IAspectInstance : exposes IAttribute --|> IAspectPredecessor : derives from IFabricInstance --|> IAspectPredecessor : derives from class IAspectPredecessor { } class IFabricInstance { Fabric TargetDeclaration } IAspectInstance --|> IAspectPredecessor : derives from class IAspectInstance { Aspect AspectClass IsSkipped Procecessors SecondaryInstances State TargetDeclaration } IAspectInstance --> IAspectState : exposes IAspectInstance --> IAspect : exposes IAspect --> IAspectState : reads & writes IAspectInstance *-- AspectPredecessor : has class AspectPredecessor { Kind Instance } AspectPredecessor --> IAspectPredecessor : exposes AspectPredecessor --> AspectPredecessorKind : has class AspectPredecessorKind { <<enum>> Attribute ChildAspect RequiredAspect Inherited Fabric }

Namespace members

Classes

Aspect

A base class from aspects that can be applied as custom attributes. Aspects must implement a specific generic instance of the IAspect<T> interface, or derive from TypeAspect, MethodAspect, ConstructorAspect, FieldOrPropertyAspect, EventAspect or CompilationAspect.

AspectOrderAttribute

Custom attribute that specifies the order of run-time execution of aspects or aspect layers.

AspectPredecessor

Represents the relationship that an object (attribute, fabric, aspect) has created or required another aspect or validator. These relationships are exposed on Predecessors.

AspectPredecessorExtensions

Extension methods for IAspectPredecessor.

AspectPredecessorKind

Kinds of AspectPredecessor.

CompilationAspect

A base class for aspects that can be applied the compilation as custom attributes (using the [assembly: MyAspect] syntax).

CompiledTemplateAttribute

This custom attribute is internal to the Metalama infrastructure and should not be used in user code. It is added by Metalama when an aspect is compile to store the original characteristics of the template because some are changed during compilation.

CompileTimeAttribute

Attribute that means that the target declaration (and all children declarations) can only be called from compile-time code and, therefore, not from run-time code. See RunTimeOrCompileTimeAttribute for declarations that can be called both from compile-time and run-time code.

ConstructorAspect

A base class for aspects that can be applied to constructors as custom attributes.

ContractAspect

A base aspect that can validate or change the value of fields, properties, indexers, and parameters.

ContractDirection

Directions of the data flow to which the contract applies.

DeclarativeAdviceAttribute

A base class for attributes that define declarative advice members.

EventAspect

A base class for aspects that can be applied to events as custom attributes.

ExcludeAspectAttribute

Custom attribute attribute that, when applied to a declaration, specifies that this declaration and all its members must not be the target of aspects of given types, unless the aspect is explicitly specified as a custom attribute.

FieldAspect

A base class for aspects that can be applied to fields as custom attributes.

FieldOrPropertyAspect

A base class for aspects that can be applied to fields or properties as custom attributes.

GetterTemplateSelector

Specifies the templates that must be used for the get accessor by the IAdviceFactory.OverrideAccessors advice.

InheritedAttribute

Custom attribute that, when applied to an aspect class, means that instances of this aspect are inherited from the base class or interface to derived classes, from base methods to method overrides, from interface methods to method implementations, and so on.

InitializerKind

InterfaceMemberAttribute

Custom attribute that applied to a member of an aspect class and means that this aspect member is a template implementing a member of an interface implemented by ImplementInterface(INamedType, INamedType, OverrideStrategy, Object).

InterfaceMemberOverrideStrategy

Member conflict behavior of interface introduction advice.

IntroduceAttribute

Custom attribute that can be applied to any member of an aspect class and that means that this member must be introduced to the target class of the aspect.

IntroductionScope

Scope of introduction advice.

InvalidAdviceParametersException

InvalidTemplateSignatureException

An exception thrown by IAdviceFactory when compile-time code attempts to add a template to a target declaration and the template is not compatible with the advice and the target declaration.

LayersAttribute

Custom attribute that, when applied to an aspect class, means that this aspect class uses several layers, and defines the name and the order of execution of these layers. In multi-aspect layers, the BuildAspect(IAspectBuilder<T>) method is called several times, once for each layer. The current layer is exposed in the Layer property.

LiveTemplateAttribute

Custom attribute that, when applied to an aspect class, means that this aspect can be used interactively, at design time, as a live template.

meta

The entry point for the meta model, which can be used in templates to inspect the target code or access other features of the template language.

MethodAspect

A base class for aspects that can be applied to methods as custom attributes.

MethodTemplateSelector

Specifies the templates that must be used by the IAdviceFactory.Override(IMethod) advice.

OverrideEventAspect

A base aspect that overrides the implementation of an event.

OverrideFieldOrPropertyAspect

A base aspect that overrides the implementation of a method.

OverrideMethodAspect

A base aspect that overrides the implementation of a method.

OverrideStrategy

Conflict behavior of introduction advice.

ParameterAspect

A base class for aspects that can be applied to parameters as custom attributes.

PropertyAspect

A base class for aspects that can be applied to properties as custom attributes.

RequireAspectWeaverAttribute

Custom attribute that, when applied an an aspect class, means that this aspect class is implemented by a low-level built with Metalama SDK. When the RequireAspectWeaverAttribute is added to a type, the BuildAspect(IAspectBuilder<T>) method is not invoked.

RunTimeOrCompileTimeAttribute

Attribute that means that the target declaration (and all children declarations) can be called both from compile-time and run-time code. See CompileTimeAttribute for declarations that cannot be called from run-time code.

ScopeAttribute

A base class for all custom attributes that influence the scope (compile-time or run-time) of the code or its role in an aspect.

TemplateAttribute

The base class for all custom attributes that mark a declaration as a template.

TemplateKind

Enumeration of the kind of templates that were specified by the user using GetterTemplateSelector or TemplateKind. A MethodTemplateSelector represents the intention of the user, not a characteristic of the declaration used as a template.

TypeAspect

A base class for aspects that can be applied to types as custom attributes.

TypeParameterAspect

A base class for aspects that can be applied to type parameters (i.e. generic parameters) as custom attributes.

Interfaces

IAdviceAttribute

IAnnotation

An annotation is an object that can be applied to a declaration and that provides information to an aspect. Annotations are exposed by the Annotations<T>(IDeclaration) extension method of the IDeclaration interface. This interface must not be implemented directly by users. Users should implement the strongly-typed IAnnotation<TTarget, TAspect> interface. (Not implemented.)

IAnnotation<TTarget, TAspect>

An annotation is an object that can be applied to a declaration and that provides information to an aspect. Annotations are exposed by the Annotations<T>(IDeclaration) extension method of the IDeclaration interface. (Not implemented.)

IAnnotationList

A list of IAnnotation.

IAspect

The base interface for all aspects. A class should not implement this interface, but the strongly-typed variant IAspect<T>.

IAspect<T>

The base interface for all aspects, with the type parameter indicating to which types of declarations the aspect can be added.

IAspectBuilder

An object used by the BuildAspect(IAspectBuilder<T>) method of the aspect to provide advice, child aspects and validators, or report diagnostics. This is the strongly-typed variant of the IAspectBuilder interface.

IAspectBuilder<TAspectTarget>

An object used by the BuildAspect(IAspectBuilder<T>) method of the aspect to provide advice, child aspects and validators, or report diagnostics. This is a weakly-typed variant of the IAspectBuilder<TAspectTarget> interface.

IAspectClass

Represents the metadata of an aspect class.

IAspectInstance

Represents an instance of an aspect. The instance of the IAspect itself is in the Aspect property.

IAspectPredecessor

Base interface for objects that can cause aspects to be added to a compilation. Predecessors are exposed on the Predecessors property.

IAspectReceiver<TDeclaration>

Represents a set of declarations and offers the ability to add aspects, annotations to them. It inherits from IValidatorReceiver<TDeclaration>, which allows to add validators.

IAspectReceiverSelector<TTarget>

An interface that allows aspects and fabrics to register aspects and validators for current compilation version.

IAspectState

An empty interface that must be implemented by objects assigned to the AspectState property of the IAspectBuilder interface.

IMetaTarget

IObjectReader

Exposes as a dictionary the tags passed to an advise.

ITemplateAttribute

ITemplateProvider

Base interface for types that define template members, which must be annotated with TemplateAttribute. To use an instance of this type, use the WithTemplateProvider(ITemplateProvider) method of the IAdviceFactory.