Introduction to AspectDNG in Details.

Return to Contents

5. Introduction to AspectDNG in Details.

5.1 What’s the Use of AspectDNG?

AspectDNG is a .NET aspect weaver, that's to say a tool that can "transplant" code into an existing assembly. This transplant is made after the standard .NET compilation, which means that both aspect and the so called "base" code (the one the transplant will be operated on) can be developed in any programming language that is compatible with .NET CLS. Another way to say that: AspectDNG works on assemblies (EXE or DLL) that may have been created out of C#, VB.NET, Eiffel.NET, Managed C++...

5.2 How Does AspectDNG Work?

• First, the base assembly and the one containing aspects to be weaved are disassembled. What we mean by disassembled is that their binary representation (CIL or Common Intermediary Language, aka ECMA-335) is translated into a higher level language, easier to work on. This language is based on XML, we call it ILML.
• Second, the base assembly ILML representation is transformed (through XSLT) so that aspect ILML instructions are added in the right place (what we call transplant zones or pointcuts). Each XSLT transform creates a new ILML document, which means you can chain as many transforms as you want (of course, you'll wait longer)
• Then, the last ILML document must be transformed back into a binary assembly (EXE or DLL): this process is symmetrical to the disassembly process. Let's call it reassembly.

5.3 Configuration Language

AspectDNG uses an XML based configuration language. Each configuration XML file must be valid towards AspectDNG.xsd. There are two most important nodes – AspectDNGConfig and Advice. Below is the structure of these two nodes (snapshot from XmlSpy):

In configuration files, advices can either be written together with AspectDNGConfig or in separately advice configuration files and just including the file paths into the AdviceFiles node of AspectDNGConfig node. All the sub nodes of Advice inherit from the Pointcut node type as pointcuts.

AspectDNGConfig Example

<?xml version="1.0" encoding="utf-8"?>
<AspectDngConfig
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="AspectDNG.xsd"
    xmlns="http://www.dotnetguru.org/AspectDNG/Config.xsd"
    debug="false"
    checkAdvice="true">
    
    <BaseAssembly>../Base/bin/debug/base.exe</BaseAssembly>
    <AspectsAssembly>bin/debug/aspects.dll</AspectsAssembly>
    
    <AdviceFiles>
        <AdviceFile>Advice/Advice-Statistics.xml</AdviceFile>
        <AdviceFile>Advice/Advice-Traces.xml</AdviceFile>
        <AdviceFile>Advice/Advice-MakeClonable.xml</AdviceFile>
        <AdviceFile>Advice/Advice-Delete.xml</AdviceFile>
    </AdviceFiles>
</AspectDngConfig>

Advice Example

<Advice xmlns="http://www.dotnetguru.org/AspectDNG">
    <Insert 
        aspectXPath="//Type[@name = 'AroundTest']"
        targetXPath="//Module"/>
    
    <AroundBody 
        aspectXPath="//Method[@name='AroundWrapper']"
        targetXPath="//Method[@name = 'Parler']"/>
</Advice>

5.4 Command Line Usage

• AspectDNG.exe -w path_to_AspectDNG.xml : do weaving according to configuration
• AspectDNG.exe -d Assembly.dll (or .exe) Assembly.ilml : disassembly of an assembly into an ILML document
• AspectDNG.exe -a Assembly.ilml Assembly.dll (or .exe) : reassembly of an assembly from an ILML document

5.5 Integrated with NAnt

If you want to integrate the weaving into a whole software construction process, you'll probably use NAnt. AspectDNG offers 3 NAnt tasks, which correspond to the three actions you can launch in a command prompt.

Install

Copy AspectDNGTasks.dll into NAnt install folder

Usage

In your NAnt files, you'll be able to use those three tasks:

<aspectdng-weave config="path_to_AspectDNG.xml"/>

<aspectdng-disassemble inputAssembly="xxx.dll (or .exe)" outputAssembly="xxx.ilml"/>

<aspectdng-assemble inputAssembly="xxx.ilml" outputAssembly="xxx.dll (or .exe)"/>

NAnt doesn't require registering tasks any more (with load-tasks). NAnt understands that AspectDNGTasks.dll is an assembly that contains NAnt tasks.

5.6 Advice Options

In advice nodes, we can define lots of AOP operations target to specific assembly. All the available option names have been listed in the node structure picture above, and I give some descriptions for them here.

5.6.1 Delete & Insert

To delete existing code in an assembly or insert (introduce) nearly any kind of element in the base assembly, such as inserting a class, an interface or any other type in the assembly itself or else adding a field or a method to any class or struct.

5.6.2 Warning & Error

To add throwing warnings or errors to existing method body when executing.

5.6.3 MakeSerializable

To make the target class or struct’s isSerializable property true. This processing equals adding the “[Serializable]” attribute to a class or struct in design time.

5.6.4 SetBaseType

To set the base type of an existing type another given type. If the existing type already has a base type, this operation will replace it with the given one, or it just set the given type as the base type of the existing type.

5.6.5 InlineXXX

The InlineXXX like options give the abilities to add advice code to join points such as constructors, methods, and properties’ body codes or activity events like when calling a constructor, when calling a method, when accessing a field, and even when executing a specific IL instruction. And generally, advices can be added either at the before or after of join points.

5.6.6 AroundCall & AroundBody

To replace existing specific method calling instructions or even method body codes with new give ones defined in aspect assembly.

5.6.7 GenericAroundXXX

The GenericAroundXXX like options give the abilities to replace existing method calling, method bodies, or field reading/writing with new give ones defined in aspect assembly. And specially, the signatures of fields or methods here must match:

object XXX::YYY(object targetObject, System.Reflection.FieldInfo targetField)

or

object XXX::YYY(object[] params, System.Reflection.MethodInfo targetOperation).