<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<link rel="stylesheet" type="text/css" href="docs.css">
<!--[if gte IE 5]>
<link href="docs_ie.css" rel="stylesheet" type="text/css">
<![endif]-->
</head>
<body><div id="pagecontainer"><table><tr><td width="5"> </td><td><a name="Enhancement"></a><br>
<a name="outline232"></a><br><h1>17. Enhancement</h1><br>
As we have seen both <a href="TransparentActivation.html#TransparentActivation">Transparent Activation</a> and <a href="Query.html#NativeQueries">Native Queries</a> will produce correct results out-of-the-box.<br>
<br>
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.<br>
<br>
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.<br>
<br>
There are two possible strategies to enhance your assemblies:<br>
<a href="Enhancement.html#EnhancementMSBuild">Enhancement with MSBuild</a><br>
<a href="Enhancement.html#EnhancementDb4oTool">Enhancement using Db4oTool</a><br>
<br>
<ul>
<a name="outline233"></a><br><h2>17.1. Required Libraries</h2><br>
The db4o enhancer requires the following assemblies in order to work:<br>
<br>
<b>Cecil.FlowAnalysis.dll</b><br>
IL code flow analysis<br>
<br>
<b>Db4objects.Db4o.dll</b><br>
db4o core engine<br>
<br>
<b>Db4objects.Db4o.Instrumentation.dll</b><br>
IL code instrumentation<br>
<br>
<b>Db4objects.Db4o.NativeQueries.dll</b><br>
Native Query Analyzer<br>
<br>
<b>Db4oTool.exe</b><br>
commandline tool<br>
<br>
<b>Db4oTool.MSBuild.dll</b><br>
MSBuild tasks <br>
<br>
<b>Mono.Cecil.dll</b><br>
IL code handling<br>
<br>
<b>Mono.GetOptions.dll</b> <br>
helper library for Cecil<br>
<br>
<a name="EnhancementMSBuild"></a><br>
<a name="outline234"></a><br><h2>17.2. Enhancement with MSBuild</h2><br>
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.<br>
<br>
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.<br>
<br>
Db4oTool.MSBuild.dll contains the main MSBuild enhancer task:<br>
Db4oTool.MSBuild.Db4oEnhancerMSBuildTask<br>
<br>
For all possibilities of using this task see the <a href="http://developer.db4o.com/Documentation.aspx" target="_blank"> topics on transparent activation</a> in the reference documentation.<br>
<br>
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:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code><Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"><br>
<br>
<!--<br>
Normal build code here <br>
--><br>
<br>
<UsingTask AssemblyFile="$(OutputPath)\Db4oTool.MSBuild.dll" TaskName="Db4oTool.MSBuild.Db4oEnhancerMSBuildTask" /><br>
<ItemGroup><br>
<Db4oEnhance Include="$(TargetPath)" /><br>
</ItemGroup><br>
<Target Name="AfterBuild"><br>
<Db4oEnhancerMSBuildTask Assemblies="@(Db4oEnhance)" /><br>
</Target><br>
<br>
</Project></code></td></tr></table>
<br>
<br>
<a name="EnhancementDb4oTool"></a><br>
<a name="outline235"></a><br><h2>17.3. Enhancement using Db4oTool</h2><br>
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.<br>
<br>
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:<br>
<br>
- In Visual Studio, right click on the project you want to enable Native Query optimization for<br>
- Select <b>'Properties'</b><br>
- In the Properties Page select the <b>Build Events</b> tab<br>
- In the <b>Post-build event command line</b> text box insert the following text:<br>
<b><path-to-your-db4o-installation>/bin/Db4oTool.exe -ta -nq $(TargetPath)</b> (replace <path-to-your-db4o-installation> with the correct path for your system)<br>
<br>
Db4oTool.exe offers different command line options for different setups. You can get a list of options directly from Db4oTool.exe by calling<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>Db4oTool.exe -help</code></td></tr></table>
<br>
<br>
Options may be grouped into 4 categories:<br>
<br>
<a href="Enhancement.html#EnhancementModes">Enhancement Modes</a><br>
<a href="Enhancement.html#TargetTypeSpecification">Target types (classes) specification</a><br>
<a href="Enhancement.html#OutputMode">Output related options</a><br>
<a href="Enhancement.html#MiscOptions">Misc Options</a><br>
<br>
<a name="EnhancementModes"></a><br>
<ul>
<a name="outline236"></a><br><h2>17.3.1. Enhancement Modes</h2><br>
With the options in this group you can specify which type of instrumentation you want to apply (either <a href="TransparentActivation.html#TransparentActivation">Transparent Activation </a>or <a href="Enhancement.html#NQOptimization">Native Queries Optimization</a> or both)<br>
<br>
-ta : Add Transparent Activation Support<br>
-nq : Optimize Native Queries<br>
-instrumentation:PARAM : Use your own instrumentation type <br>
<br>
<br>
<a name="TargetTypeSpecification"></a><br>
<a name="outline237"></a><br><h2>17.3.2. Target types (classes) specification</h2><br>
When enhancing an assembly it's possible to enhance all or some of its types through the following options:<br>
<br>
-by-attribute:PARAM Filter types to be instrumented by attribute<br>
-by-filter:PARAM Custom type filter<br>
-by-name:PARAM Filter types by name (with regular expression syntax)<br>
-not Negates the last filter<br>
<br>
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 <b>-not</b>option.<br>
<br>
<b>-by-name</b>filter expects a regular expression and will include each type whose fully qualified name matches this regular expression. <br>
<br>
<a name="OutputMode"></a><br>
<a name="outline238"></a><br><h2>17.3.3. Output related options</h2> <br>
Output related options<br>
<br>
-debug Preserve debugging information<br>
-fake Fake operation mode, assembly won't be written<br>
<br>
<br>
<a name="MiscOptions"></a><br>
<a name="outline239"></a><br><h2>17.3.4. Misc Options</h2><br>
-case-sensitive Case sensitive queries<br>
-? -help Show this help list<br>
-usage Show usage syntax and exit<br>
-v -verbose Verbose operation mode<br>
-V -version Display version and licensing information<br>
-vv Pretty verbose operation mode<br>
<br>
<a name="NQOptimization"></a><br>
</ul>
<a name="outline240"></a><br><h2>17.4. Native Query Optimization</h2><br>
The Native Query optimizer is still under development to eventually "understand" all valid C# constructs. Current optimization supports the following constructs well:<br>
<br>
- compile-time constants<br>
- simple member access<br>
- primitive comparisons<br>
- equality operator<br>
- #Contains()/#StartsWith()/#EndsWith() for Strings<br>
- boolean expressions<br>
- arbitrary method calls (including property accessors) on predicate fields (without any arguments)<br>
- candidate methods composed of the above<br>
- chained combinations of the above<br>
<br>
Note that the current implementation does not support polymorphism yet.<br>
<br>
If optimization is turned off or not possible for some reason, a Native Query will be executed by instantiating all objects, using <a href="Evaluations.html#Evaluations">SODA Evaluations</a>. Naturally performance will not be as good in this case, but queries will still deliver correct results.<br>
<br>
<ul>
<a name="outline241"></a><br><h2>17.4.1. Native Query Optimization on CompactFramework 2.0</h2><br>
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. <br>
<br>
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.<br>
<br>
The tool can be easily integrated inside Visual Studio.NET 2005 as a Post Build tool by following the simple steps below:<br>
<br>
- Right click the project you want to enable Native Query optimization for<br>
- Select<b>'Properties'</b><br>
- In the Properties Page select the<b>'Build Events'</b>tab<br>
- In the<b>'Post-build event command line'</b>text box insert the following text <b>"<path-to-your-db4o-installation>/bin/Db4oTool.exe -nq $(TargetPath)"</b> without the quotes and replacing <path-to-your-db4o-installation> to the correct value for your system.<br>
<br>
<a name="outline242"></a><br><h2>17.4.2. Monitoring optimization</h2><br>
To monitor optimization you can attach event handlers to the IObjectContainer:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>NativeQueryHandler handler = ((ObjectContainerBase)container).GetNativeQueryHandler();<br>
handler.QueryExecution += OnQueryExecution;<br>
handler.QueryOptimizationFailure += OnQueryOptimizationFailure;</code></td></tr></table>
<br>
<br><br><div id="footer"><p align="center">Do you have any questions, suggestions or feedback? Ask your questions in the <a href="http://developer.db4o.com/Forums.aspx" target=_top>db4o forums</a>. Join the <a href="http://developer.db4o.com" target=_top>db4o community</a> for addional resources and news.<br><br><a href="http://www.db4o.com/" target=_top><small>www.db4o.com</small></a></p>.</div><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br></td></tr></table></div></body></html>
