Best Practice: Making OpenAccess projects version independent

When working on any project that references external libraries, it’s important to configure your project references in such a way that “isolates” them from changes to your system. This is especially true if you’re working on a team and sharing code via source control. You want anyone to be able to check-out the project, and regardless of the software installed on their machine, be able to build and run the code. You also want to be free to upgrade your Telerik tools without being forced to upgrade all of your projects.

To achieve this version independence in your projects, follow this advice:

At at minimum, make local copies in your project folder of all referenced assemblies, and then have your projects reference the external libraries from this project relative location. In my solutions, I often create a top-level “Lib” or “Binaries” folder and copy my DLLs there.

I also create a Solution Folder of the same name in my Visual Studio solution and add these referenced assemblies to source control. By doing that, anyone that checks-out the project has all of the referenced assemblies needed to build.

This advice so far suggests two things:

1. DON’T reference external assemblies required to build your project from the GAC (except for perhaps Microsoft framework assemblies)
2. DON’T reference assemblies located in a directory that’s not included with your solution (such as an Program Files install location)

Breaking with either of the above suggestions will create headaches when sharing code with your team and headaches for you as you upgrade and change your system. It’s rare that you’ll want to upgrade all of your projects to a new version of an external library at one time, so free your projects from the whims of tool upgrades and reference local copies.

For most external libraries, like the RadControls for ASP.NET AJAX or Telerik Extensions, this is enough to achieve version independence for project builds. If you use OpenAccess, you may want to take one additional step.

Since OpenAccess “enhances” assemblies as part of the build process, your builds have a dependency on the OpenAccess enhancer (venhance.exe). To ensure that anyone that checks-out your solution can still complete a build without being forced to install OpenAccess, copy the venhance.exe to your local solution folders.

VEnhance can be found in the OpenAccess install directory in the SDK folder.

Copy this to your “Binaries” folder, and then configure your OpenAccess-enabled projects to use the local copy of VEnhance instead of the version in Program Files (the default behavior). That’s done by editing your Project Settings and adding a Post-build event:

1. Right-click on your project and select “Properties”
2. Click on the “Build Events” tab
3. In the “Post-build event” textbox, enter:
   "$(SolutionDir)\Binaries\VEnhance.exe" "-assembly:$(TargetPath)"
   (include the quotes and adjust the path to VEnhance as necessary)
4. Change the “Run” drop down to “Always” and save your project settings

Now your solution is completely version independent! You can install newer versions of OpenAccess ORM or any other Telerik tools and your solutions will continue to build against the configured tool versions. When you’re ready to upgrade, you can simply add the newer assemblies to your “Binaries” folder, update your project references, and then start enjoying the latest Telerik features.

Hopefully this basic advice helps you avoid some of the headaches of working with syncing versions of external tools in your solutions. Followed correctly, you’ll never have to worry about breaking existing projects with new installs of Telerik tools.