16. Enhancement


As we have seen both Transparent Activation and Native Queries will produce correct results out-of-the-box.

To get your application to run as fast as possible with db4o, you will want to make sure that only required objects are loaded from the database and that Native Queries are optimized to use field indexes where this is possible.

Theoretically you could write all the necessary code by hand but you will save yourself a lot of time if you use automatic enhancement. Using the db4o enhancer tools you can automatically add code to your assemblies to make them work even better with db4o.

There are two possible strategies to enhance your assemblies:
Enhancement with MSBuild
Enhancement using Db4oTool


    16.1. Required Libraries


    The db4o enhancer requires the following assemblies in order to work:

    Cecil.FlowAnalysis.dll
    IL code flow analysis

    Db4objects.Db4o.dll
    db4o core engine

    Db4objects.Db4o.Instrumentation.dll
    IL code instrumentation

    Db4objects.Db4o.NativeQueries.dll
    Native Query Analyzer

    Db4oTool.exe
    commandline tool

    Db4oTool.MSBuild.dll
    MSBuild tasks   

    Mono.Cecil.dll
    IL code handling

    Mono.GetOptions.dll  
    helper library for Cecil



    16.2. Enhancement with MSBuild


    When csc (or Visual Studio, calling csc) compiles your assemblies, it uses the instructions in your csproj project files to know what to do. The "code" in csproj files is plain XML, it is very well readable and you can add your own tasks to the build by editing the files with your favourite (XML) editor.

    If you want the produced assemblies to be enhanced for db4o, you can add the db4o enhancer build task to your csproj files as an "AfterBuild" task.

    Db4oTool.MSBuild.dll contains the main MSBuild enhancer task:
    Db4oTool.MSBuild.Db4oEnhancerMSBuildTask

    For all possibilities of using this task see the  topics on transparent activation in the reference documentation.

    The simplest enhancer task does both: It optimizes Native Queries and it adds the IActivatable interface to your classes, making sure a persistent object is activated whenever any field is read. Here is a simple example of how such an addition to MSBuild task could look like:

    <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

      <!--
        Normal build code here   
      -->
      
      <UsingTask AssemblyFile="$(OutputPath)\Db4oTool.MSBuild.dll" TaskName="Db4oTool.MSBuild.Db4oEnhancerMSBuildTask" />
      <ItemGroup>
        <Db4oEnhance Include="$(TargetPath)" />
      </ItemGroup>
      <Target Name="AfterBuild">
        <Db4oEnhancerMSBuildTask Assemblies="@(Db4oEnhance)" />
      </Target>
      
    </Project>




    16.3. Enhancement using Db4oTool


    Db4oTool.exe is a top level command line interface to all enhancement tasks. You can either add it to your own build setup or you can directly integrate it from within Visual Studio.

    To get you an idea on how you can set things up, here is a step-by-step example how you could integrate Db4oTool.exe from Visual Studio.NET 2005 to do it's post-build tasks for a CompactFramework 2.0 project:

    - In Visual Studio, right click on the project you want to enable Native Query optimization for
    - Select 'Properties'
    - In the Properties Page select the Build Events tab
    - In the Post-build event command line text box insert the following text:
    /bin/Db4oTool.exe -ta -nq $(TargetPath) (replace with the correct path for your system)

    Db4oTool.exe offers different command line options for different setups. You can get a list of options directly from Db4oTool.exe by calling
    Db4oTool.exe -help


    Options may be grouped into 4 categories:

    Enhancement Modes
    Target types (classes) specification
    Output related options
    Misc Options



      16.3.1. Enhancement Modes


      With the options in this group you can specify which type of instrumentation you want to apply (either Transparent Activation or Native Queries Optimization or both)

           -ta : Add Transparent Activation Support
           -nq : Optimize Native Queries
           -instrumentation:PARAM : Use your own instrumentation type




      16.3.2. Target types (classes) specification


      When enhancing an assembly it's possible to enhance all or some of its types through the following options:

           -by-attribute:PARAM    Filter types to be instrumented by attribute
           -by-filter:PARAM        Custom type filter
           -by-name:PARAM            Filter types by name (with regular expression syntax)
           -not                    Negates the last filter

      Note that these filters specifies which types should be included in the enhancement process. enhanced. If you want to filter out (i.e, to not enhance some types) you can specify -notoption.

      -by-namefilter expects a regular expression and will include each type whose fully qualified name matches this regular expression.



      16.3.3. Output related options

          
      Output related options

           -debug                  Preserve debugging information
           -fake                   Fake operation mode, assembly won't be written




      16.3.4. Misc Options


           -case-sensitive         Case sensitive queries
           -? -help                Show this help list
           -usage                  Show usage syntax and exit
        -v -verbose                Verbose operation mode
        -V -version                Display version and licensing information
           -vv                     Pretty verbose operation mode



    16.4. Native Query Optimization


    The Native Query optimizer is still under development to eventually "understand" all valid C# constructs. Current optimization supports the following constructs well:

    - compile-time constants
    - simple member access
    - primitive comparisons
    - equality operator
    - #Contains()/#StartsWith()/#EndsWith() for Strings
    - boolean expressions
    - arbitrary method calls (including property accessors) on predicate fields (without any arguments)
    - candidate methods composed of the above
    - chained combinations of the above

    Note that the current implementation does not support polymorphism yet.

    If optimization is turned off or not possible for some reason, a Native Query will be executed by instantiating all objects, using SODA Evaluations. Naturally performance will not be as good in this case, but queries will still deliver correct results.


      16.4.1. Native Query Optimization on CompactFramework 2.0


      Due to some platform limitations, CompactFramework 2.0 users using the convenient delegate based Native Query syntax that want their queries to be optimized are required to run the Db4oTool.exe command line utility on their assemblies prior to deploying them.

      The Db4oTool.exe utility, which can be found in the /bin folder of this distribution is required because the CompactFramework API does not expose any of the delegate metadata needed by the Native Query optimizer.

      The tool can be easily integrated inside Visual Studio.NET 2005 as a Post Build tool by following the simple steps below:

      - Right click the project you want to enable Native Query optimization for
      - Select'Properties'
      - In the Properties Page select the'Build Events'tab
      - In the'Post-build event command line'text box insert the following text "/bin/Db4oTool.exe -nq $(TargetPath)" without the quotes and replacing to the correct value for your system.


      16.4.2. Monitoring optimization


      To monitor optimization you can attach event handlers to the IObjectContainer:

      NativeQueryHandler handler = ((ObjectContainerBase)container).GetNativeQueryHandler();
      handler.QueryExecution += OnQueryExecution;
      handler.QueryOptimizationFailure += OnQueryOptimizationFailure;




      www.db4o.com