Telerik OpenAccess ORM

OpenAccess ORM tools, i.e., VEnhance and VSchema can be used with the MSBuild framework.

The MSBuild integration can be used as an alternative to the Microsoft Visual Studio integration and is useful while using the command-line build environment. It is targeted for serving build servers and build processes that are done using MSBuild and/or TFSBuild

Usage

In order to use the OpenAccess ORM MSBuild Integration you must import the OpenAccess.targets file in your project file(s) or TFS build file. This file contains the proper declarations for the OpenAccess ORM tasks and their dependencies. The OpenAccess.targets file is already installed in the $(MSBuildExtensionsPath) directory for your convenience. The import statement must be added after the import statement for the Microsoft C#/VB targets file in your project file.

Additionally, a section that contains the OpenAccess ORM user settings for the current project must be made in the project file (if it was not previously enhanced). These settings control whether enhancement and database migration is done during the build process, and it also specifies which database needs to be used.

The following example given below shows the user settings required and how to incorporate the task defined for OpenAccess ORM into your .csproj file. You can use Visual Studio to generate the custom settings section (using our visual wizards):

.csproj

Copy Code

... Head of .csproj file omitted here ...  <ItemGroup>    <Reference Include="Telerik.OpenAccess, Version=2009.1.520.1, Culture=neutral,     PublicKeyToken=7ce17eeaf1d59342, processorArchitecture=x86">       <SpecificVersion>False</SpecificVersion>       <HintPath>C:\Program Files\Telerik\OpenAccess ORM\bin\Telerik.OpenAccess.dll       </HintPath>    </Reference>    <Reference Include="System" />    <Reference Include="System.Data" />    <Reference Include="System.Xml" />  </ItemGroup>  <ItemGroup>    <Compile Include="MyClass.cs" />    <Compile Include="Properties\AssemblyInfo.cs" />  </ItemGroup>  <ItemGroup>    <None Include="App.config" />  </ItemGroup>  <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />  <!-- THE FOLLOWING LINE IMPORTS THE TASKS AND DEPENDENCIES FROM OPENACCESS. -->  <Import Project="$(MSBuildExtensionsPath)\OpenAccess.targets" />  <ProjectExtensions>     <VisualStudio>        <UserProperties                 OpenAccess_UseMSBuild="True"                 OpenAccess_EnhancementOutputLevel="1"                 OpenAccess_UpdateDatabase="True""                 OpenAccess_Enhancing="True"                 OpenAccess_ConnectionId="DatabaseConnection1"                 OpenAccess_ConfigFile="App.config" />     </VisualStudio>  </ProjectExtensions> </Project>

MSBuild tasks

The OpenAccess ORM integration into the MSBuild framework consists of two tasks, which can be used directly as well (instead of the targets provided in the OpenAccess.targets file). These tasks encapsulate the two tools used additionally for enhancing projects and database schema preparation:

These tasks are declared in a MSBuild .target file named OpenAccess.targets, which is placed in the $(MSBuildExtensionsPath) directory.

OpenAccessEnhancer Task

The OpenAccessEnhancerTask wraps the Telerik OpenAccess ORM enhancer ( implemented in the venhance.exe assembly) for MSBuild.

In order to use the OpenAccessEnhancer, the task must be declared as follows:

	Copy Code
<UsingTask TaskName="OpenAccessEnhancer" AssemblyFile="$(OpenAccess ORM_SDK_Directory)/venhance.exe"/>

This declaration is already contained in the OpenAccess.targets file installed under $(MSBuildExtensionsPath).

For more information about VEnhance, its various parameters and usage examples, please refer to The OpenAccess ORM Enhancer.

The MSBuild Integration of the enhancer tool has additional parameters (to the ones mentioned in The OpenAccess ORM Enhancer section), which have been listed below:

Example:

The following example uses the OpenAccessEnhancer task to enhance an assembly:

	Copy Code
<OpenAccessEnhancer   Assembly="@(IntermediateAssembly->'%(FullPath)')"   References="@(ReferencePath)"   ProjectReferences="@(ProjectReference)"   <Output TaskParameter="Version" PropertyName="OpenAccessEnhancerVersion" /> </OpenAccessEnhancer>

To enhance a signed assembly with this task, enable the SignAssembly attribute and specify the AssemblyKeyFileAttribute somewhere in the code:

	Copy Code
[assembly: AssemblyKeyFileAttribute("Key.snk")]

	Copy Code
<OpenAccessEnhancer   Assembly="@(IntermediateAssembly->'%(FullPath)')"   References="@(ReferencePath)"   ProjectReferences="@(ProjectReference)"   SignAssembly="true"   <Output TaskParameter="Version" PropertyName="OpenAccessEnhancerVersion" /> </OpenAccessEnhancer>

OpenAccessSchemaTool Task

The schema tool is an OpenAccess ORM helper tool, which is used for creating or migrating a relational database schema. The OpenAccessSchemaToolTask wraps the OpenAccess ORM VSchema tool (implemented in the vschema.exe assembly) for MSBuild.

In order to use the OpenAccessSchemaTool, the task must be declared as follows:

	Copy Code
<UsingTask TaskName="OpenAccessSchemaTool" AssemblyFile="$(OpenAccess ORM_Runtime_Directory)/ vschema.exe"/>

This declaration is already contained in the OpenAccess.targets file installed under $(MSBuildExtensionsPath).

The OpenAccessSchemaTool can be used for four different purposes:

• To generate a new database without a schema: DatabaseCreate=true
• To generate a new schema in a database: Create=true
• To migrate a database schema: Migrate=true
• To execute SQL statements on a database: ExecuteSql=true

Exactly one of the four purposes must be indicated by using the respective parameter.

For more information about VSchema, its various parameters and usage examples, please refer to The VSchema Tool.

The MSBuild Integration of the schema tool has additional parameters (to the ones mentioned in The VSchema Tool section), which have been listed below:

The following two parameters are additional in the MSBuild Integration for the -create switch:

Example:

The following example uses the OpenAccessSchemaTool task to migrate a relational database schema:

Copy Code

<OpenAccessSchemaTool   Migrate="true"   Assembly="@(MainAssembly->'%(FullPath)')"   Config="@(ConfigFile->'%(FullPath)')"   ConnectionId="$(ConnectionId)"   Direct="true"   OutputDir="@(OutputPath)"   References="@(ReferencePath)">   <Output TaskParameter="ScriptName" PropertyName="OpenAccessGeneratedScriptFileName"/>   <Output TaskParameter="DatabaseURL" PropertyName="DB_URL"/> </OpenAccessSchemaTool>

While using the MSBuild integration, you can get explanations for errors/warnings of the OpenAccessEnhancer and the OpenAccessSchemaTool by pressing "F1" in Visual Studio on the error line.

© 2002-2009 Telerik. All Rights Reserved.