Troubleshooting OpenAccess ORM VEnhance errors

I'm working on what I promise will be a very cool and useful tool/demo for OpenAccess ORM (more on that very soon), and in the process I was reminded of some of the challenges that can pop-up when you start manually "enhancing" OpenAccess-enabled assemblies. Manual enhancing is something you usually do when your project configuration and build steps require maximum control, or when you're trying to use specific versions of the enhancer (VEnhance.exe) with your code. In other words, it's not something faced by every project, and new OpenAccess projects using the new DataContext are event less likely to require manual VEnhance steps.

Still, if you prefer the pre-visual designer approach to OpenAccess, or if you're maintaining code that uses a specific VEnhance version, here are a few quick tips that should help you quick resolve any build-time VEnhance crashes:

1. VEnhance Config: If you're working with .NET 4, a common cause of VEnhance crashes is failure to include the "venhance.exe.config" file in the same directory as the "venhance.exe" executable. This simple config file is needed with .NET 4 to tell the enhancer to use use Framework v4 assemblies when enhancing your code. The contents of the config file are simply:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<startup>
  <supportedRuntime version="v4.0"/>
</startup>
</configuration>

2. VEnhance Version: Another common mistake is mis-matching VEnhance versions. That is, using a VEnhance version that is different from the version of the OpenAccess assemblies you're referencing. With the latest VEnhance versions, you can actually use a newer VEnhance.exe with older versions of OpenAccess, so just make sure you're using the latest VEnhance executable. If you find yourself in doubt, though, it can't hurt to make sure both your referenced assemblies and VEnhance version match.
3. Supporting DLLs: The VEnhance tool needs a few external assemblies to do its magic, so make sure they are accessible by the executable (usually best kept in the same directory). If you are copying VEnhance.exe to a project-relative location (good practice for creating "upgrade proof" projects), don't forget to bring these files along: Telerik.OpenAccess.SDK.dll, (and in newer OA versions) Mono.Cecil.dll, and Mono.Cecil.Pdb.dll
4. Manually Run VEnhance: Finally, if after checking your VEnhance version and making sure the necessary config file is in-place, you can always run VEnhance manually. The advantage to doing this instead of using Visual Studio post-build events is that you tend to get much more descriptive errors that help with troubleshooting (versus the totally unhelpful crash message pictured above). To manually enhance:
1. In Visual Studio, select your OpenAccess-enabled project and set the project "Enhancing" attribute to "False" (disables IDE integration "auto" enhancing)
2. Build your project (should build and do no OpenAccess enhancing)
3. Open a command prompt in the directory containing "venhance.exe"
4. Run the command "venhance <path to your compiled DLL>" (In newer versions of VEnhance.exe, it will be: venhance -assembly:"<path to dll>"
5. Inspect the command prompt output for runtime errors or SUCCESS!

There are other options you can use with manual enhancing, too, like the "-verbose+" command combined with "-verboseMode:4" to see detailed output in the command window about what VEnhance is doing. If nothing else has solved your problem, this technique should at least tell you what's wrong.

Don't get stuck or frustrated with useless VEnhance Windows crash dialogs. Try these troubleshooting steps and get back on the road to using one of the most powerful and enjoyable ORMs available for .NET development!