We hear a lot that migrating projects using OpenAccess to a new OpenAccess version is a complicated process. The first decision should be if you want to migrate each of your projects or if you want to stay for some of them with the old OpenAccess version.
This post describes how to prepare your project so that an installation of a new OpenAccess version does not break your build or makes it necessary to use the new version in your older projects.
The first step is to check-in all necessary runtime and compile time used resources instead of taking them from the OpenAccess installation or the global assembly cache. Here is the list of files that you have to check in:
You have to go through all your projects that references an OpenAccess assembly and replace each reference with one to the checked in assembly. The assemblies might be installed in the GAC and to avoid the usage of the GAC installed assemblies, please set the ‘Copy Local’ property of the references to ‘True’. Even if you see it as ‘True’ (the default value might not be stored and later calculated different) please switch it once to ‘False’ and back to ‘True’ to really change this setting.
Additionally, because the runtime system is not referenced directly, you have to make sure that the runtime system is copied to the executables or applications output directory. The easiest way is to add the Telerik.OpenAccess.Runtime.dll, Telerik.OpenAccess.Adonet2.dll and Telerik.OpenAccess.Config.dll as items to your main project. Just start ‘Add’ ‘Existing Item’ by right click on your project in the solution explorer, select the assemblies and close the dialog by using the down arrow besides the ‘Add’ button and choose ‘Add As Link’
You can also move these new items to a folder in your project. Because the default settings for those items does not fulfill our needs, please open the properties dialog of all added items and set the ‘Build Action’ to ‘None’ and ‘Copy To Output Directory’ property to ‘Copy if newer’.
Now we have all used assemblies project local. This trick can also be used to add the assemblies to your installer or web side packaging.
The remaining problem is; the enhancer.exe is used from the product installation. To change it you have to edit the project that needs the enhancer. Usually the project that calls the enhancer is your project with the persistent classes inside, Those can be defined in our graphical designer (.rlinq file) or, if you are using the fluent API, in the project that contains the persistent model.
To edit a project file with the XML editor in Visual Studio you have to right click on the project in the project explorer and choose ‘Unload Project’. The project is now grayed and the menu has changed so that you can right click again and choose ‘Edit’. Now the project is opened in the XML editor. Go to the end of the project and locate the line containing ‘OpenAccess.targets’, usually it look like:
As you can see, the OpenAccess.targets file is taken from an MsBuild directory. The OpenAccess installer installs it to this directory and it always refers to the installed enhancer that might not be the right one for you; we want to use the checked in version. Replace this line now by a new block with incremental path to your checked in OpenAccess.targets and enhancer.exe files.
Close the project in the editor, right click in the project explorer and say ‘Reload’. If you did a mistake in the path, or you did not check in the targets file first, the project load will report an error and you have to fix the project file in the XML editor as described above.
One final step is necessary. The OpenAccess.targets file contains an absolute path to enhancer, that overwrites your local specified path. Please open your checked in OpenAccess.targets file and remove or comment out the following lines:
>c:\Program Files\Telerik\OpenAccess ORM</
Your targets file is loaded together with the Solution. After you have changed it, please reopen the Visual Studio or the Solution.
The OpenAccess SDK is using the same mechanism, if you want to copy it from there please download the OpenAccess SDK and look into the local files.
Now your project is independent of the installed OpenAccess version. Even with the new version installed, the old one is used. To migrate, please change the checked in files and change the OpenAccess.targets file again.