Monday, February 28, 2011

Why not ORM: OpenAccess Watcher, Part 3

ORM-Robot-watcherIn part 1 of this ongoing series, we dispelled ORM myths, shaking the errant assumptions that many developers still hold about ORM. In part 2, we took a deeper look at why and how you can learn to trust the SQL an ORM produces. In part 3, we'll examine a simple tool I've crafted to help with that SQL visualization when using Telerik's OpenAccess ORM.

WHAT DOES THE TOOL DO?

The goal for this tool is simple: make it simple to visualize and summarize in real-time the SQL output from any OpenAccess-powered application. My self-imposed requirements were simple, too:

  • The tool must add value above and beyond what OpenAccess' built-in logging provides
  • The tool must be easy to setup with any application (win or web)
    • At most, 1 assembly reference, 1 line of "initialization" code
  • The tool must work with "new" (Visual Designer) and "classic" (IObjectScope) OpenAccess

THE RESULT: OPENACESS WATCHER

The tool, which I've dubbed OpenAccess Watcher, is composed of two parts:

  1. The Watcher- This is a simple WinForms application built with the Telerik RadControls for WinForms and the SharpDevelop TextEditor (for syntax highlighting) that "listens" for messages from OpenAccess applications.
  2. The Sender- This is a custom OpenAccess TraceListener that builds on the built-in OpenAccess logging to format and send messages in real-time to The Watcher, which in turn handles the visualization. There is also some advanced use of JustMock's CodeWeaver, but more on that in a moment.

The key thing to understand is that (for the most part) this tool is working with the same data you might find in the OpenAccess logs. It's value is in the summary stats it provides, the easier data navigation and visualization, and the "real-time" nature of the log output.

USING OPENACCESS WATCHER

Sticking to my requirements, OpenAccess Watcher requires minimal setup. To use it in an OpenAccess-powered app, you must simply:

  1. Add a reference to the assembly that contains "The Sender" (OpenAccessWatcher.Listeners.dll)
  2. Initialize the custom TraceListener during your application startup
    • For Web, this means 1 line of code in Application_Start in Global.asax
    • For Win, this means 1 line of code in your Program's Main method

That's it! Two steps. Now all you need to do is open "The Watcher" and start your application. If everything is working, you'll start seeing OpenAccess generated SQL show-up in The Watcher. (A complete "Getting Started" readme is available with the code.)

UNDERSTANDING THE LOG DATA

Since this tool does depend heavily on the OpenAccess log data, it's important to understand what's available. First, what's available is directly connected to the level of logging you've configured. The three common modes are:

  • Normal - This is good for capturing the basic SQL statements, but omits most of the log data that can be used to interpret other behaviors (like row count).
  • Verbose - This is good for capturing most SQL behavior, including connections, but it can significantly slow the execution of some applications.
  • All - This gives you maximum logging data and enables you to measure things like total rows returned and total data readers opened. Unfortunately, this can really slow down bigger apps.

My suggestion: Start with verbose. If that makes your app unbearably slow, try using normal. If your app runs tolerably with verbose and you want to try to get event more data, then give all a try.

It should also go without saying, these are not settings for production or for measuring application speed. These are settings specifically designed for visualizing SQL behavior during development, with the goal being to use the info for tuning ORM performance configuration.

EXAMPLE APP

To test OpenAccess Watcher, I've got a simple WinForms application with a RadGrid that loads data using the OpenAccessDataSource. When I open the page with this grid, I see the following in Watcher:

SNAGHTML41e98abc

There are three primary areas of information:

  1. SQL Activity Log (A) - This is a raw log of the SQL queries generated by OpenAccess (pulled from the OpenAccess logs). This data is displayed in a RadGrid for WinForms, so you have the complete ability to sort, filter, and group this data.
  2. SQL Visualizer (B) - Using the open source ShareDevelop TextBox, this area better visualizes the selected SQL statement so that you can easily review the SQL with syntax highlighting.
  3. Statistics Summary (C) - This area displays the values from various logging counters that summarize OpenAccess database activity. The version of OpenAccess you're using and your logging settings will impact that values that are available here.

While I'll save a full discussion of how to work with this data for Part 4, it's worth noting now that there is not a one-to-one relationship between SQL queries and database connections. OpenAccess typically prepares and executes multiple queries in batch, so don't freak out if you see larger numbers of queries.

ADVANCED LOGGING: CODE INJECTION

As I alluded to above, I am making use of Telerik's very cool CodeWeaver library, available with JustMock, to do IL injection with OpenAccess assemblies. This allows the custom TraceListener to go beyond tracking OpenAccess log data and inject code in to key OpenAccess methods that is used for gathering statistics.

Newer versions of OpenAccess (Q3 2010+) have convenient IntelliTrace and CommandWrapper classes through which all OpenAccess connections and transactions pass, so by injecting some counters in these methods I am able to report on connections and transactions even when logging is tuned-down or disabled.

For older versions OpenAccess, I am not able to do counters as easily, but there is still some injection in to the very low-level Transaction and Connection runtime implementations to help gather as many stats as possible for the visualizer.

In all cases, the code injection tooling will only work when the JustMock profiler is enabled. When not available, you'll get fewer stats.

IT WORKS ON MY MACHINE DISCLAIMER

This is an experimental project. It is not guaranteed to work with your setup. If it doesn't, I'm sorry. Send me feedback and I'll see what I can do to make it cover more scenarios. Known caveats with this preview:

  • I'm primarily focusing on SQL Server scenarios today. It should work for other OpenAccess providers, but I haven't tested that yet.
  • I've only tested this with .NET 4.0 projects. I'm not sure what will happen if you try to use the custom TraceListener with older .NET versions.
  • Your application probably needs to be running in full trust to support the reflection and code injection tooling that's going on.
  • The UI of the WinForms app can "hang" when huge volumes of logging data are being collected. Just wait a few seconds and it should become more responsive.

THE BITS

Disclaimer out of the way, here are the bits. Enjoy and share your feedback.

In Part 4, I'll show you how you can use The Watcher to start learning and optimizing the SQL generated by OpenAccess. Since OpenAccess has powerful configuration and optimization options, it's surprisingly easy (compared to other ORMs) to tweak once you have a clear understanding of what's happening.

Thursday, February 24, 2011

Why not ORM: Trusting SQL, Part 2

ORM-RobotIn part 1, we examined and busted 5 common ORM myths. Actually, we busted 4.5. We agreed that one myth, that you can't trust the SQL an ORM produces, is plausible. Let's bust that myth, at least bust it for OpenAccess ORM, today.

IN TOOLS I TRUST

One of the biggest barriers to adopting any time saving development tool is trust. You have to trust that the work the tool is doing to save you time is of equal or better quality than the same work you would otherwise do by hand. A development tool is in many ways like a co-worker or contractor. You have to get to know the results they produce before you can stop worrying about including their output in your project.

This is true for refactoring tools (like JustCode), UI components (like the RadControls), and especially true for data tools like OpenAccess ORM.

But how do you go about "trusting" a tool like OpenAccess ORM? Transparency.

OPEN THE BLACK BOX

With ORMs, many fears root in the perceived "black box" nature of what's happening under the covers. Many developers are familiar with hand crafting EACH-and-EVERY-sql-statement, and it can be unsettling to let some ORM robot start automagically creating your SQL based on abstracted LINQ. What if the SQL is inefficient? What if way too much SQL is being generated? What if the ORM "select *" my database?!

The result of this fear is often cut-and-run. Dump (or don't start using) the ORM and stick with time-wasting, but 100% transparent hand coding.

What developers need is an easy way to open the ORM black box and see what's really happening. Cut-out the "what ifs," and replace them with "when I do X, the ORM will do Y."

WHAT *IS* REALLY HAPPENING?

While ORMs like OpenAccess are unbelievably sophisticated, giving you the power to map database objects to code and even update schemas from code-based models, at the very root of the implementation is code you know. Standard (best practice) .NET for moving data between various databases. In the case of SQL Server, you'll find ADO.NET and SqlCommands, Transactions, and Connections.

The important thing to know is that this "standard" code is built by super-smart developers that are 100% focused on best practice data programming. Think about that. When you use a well built ORM, it's like adding a .NET data programming expert to your team, freeing you to really focus and be an expert on other layers of your app.

Then there's the SQL. And here it's worth noting, not all ORMs are created equal. The way an ORM converts LINQ or OQL or whatever in to SQL, and the ability on top of that to optimize the SQL through configuration, is often what makes one ORM better than another. With a quality ORM, though, you get SQL generated by programmers that are again 100% focused on SQL programming.

Now, much like you must "speak Google" to get the search results you expect, you usually need to learn how to "speak ORM" to get the SQL output you expect. That means you need to form an understanding of how the abstracted data languages (usually LINQ) produce SQL so you know when extra optimization configurations are needed. Do that, and there is no reason the SQL created by an ORM will be any different than the SQL you would create by hand (it may even be better!).

A good ORM is more than a tool. It's a .NET data programming and SQL expert. But how do you prove that to yourself? And how do you learn to speak ORM?

THE ORM LOOKING GLASS

You should never blindly trust any tool. Just as I'd expect you to inspect the HTML produced by the Telerik Extensions for ASP.NET MVC, I'd expect you to inspect the SQL produced by OpenAccess. Doing so not only helps you learn when and how to optimize ORM programming, but it helps you build the trust in your essential data tool.

Fortunately, OpenAccess provides a couple ways to open the "black box" out of the box:

  1. Logging
    If you've never used OpenAccess logging, you may be amazed at what can be easily logged with the simple change to a couple of config settings. All SQL statements, parameter values, database connections, and even returned rows can be captured by OpenAccess logging for your thorough review. Logs can be output to the console, a text file, or even directly to a in-memory StringWriter, and volume of data that is captured depends on your logging level. More on that in the next post.
  2. IntelliTrace
    For added runtime debugging transparency, OpenAccess (as of Q3 2010) provides deep insight with integrated IntelliTrace support in Visual Studio 2010. As you step and debug your app, IntelliTrace can reveal the SQL OpenAccess is producing and executing.

Both of these approaches are useful, but they do require you to manually "parse" the logs or trace stacks to understand what's happening when your program runs. Is there an easier way to see the bigger picture?

WATCHING OPENACCESS

Taking advantage of the OpenAccess logging output via a custom TraceListener (along with a few other tricks for newer versions of OpenAccess), I've created a simple tool designed to help you better visualize what OpenAccess is doing when your application runs.

openaccess-watcher

The advantages of this tool:

  • Easier to visualize, syntax-highlighted SQL
  • Convenient log sorting, filtering, and grouping (provided by RadGridView)
  • Summary values for key behaviors (total connections, total queries, total transactions, etc.)
  • Real-time visualization of OpenAccess output

In part 3, I'll provide a more complete overview of this new tool and provide a basic working version that you can try with your own OpenAccess-powered applications. The main idea behind this tool: make it dead simple to open the OpenAccess black box and visualize the "real" SQL.

Whether you use built-in logging output or a visualization tool like this, take the time to get to know your ORM. If you can build a trust with a powerful ORM, like OpenAccess, you'll leave hand-coding data access in the past where it belongs and never look back.

Can you trust the SQL produced by an ORM? Definitely! You just need to take a look. It's not in a book…it's in a log file.

Wednesday, February 16, 2011

The Brilliance of Microsoft + Nokia

microkia-better-workWhile most of the industry seems to be confounded by the recent Microsoft and Nokia announcements around Windows Phone, I think there is a brilliant Silverlining.

And rather than heap more narrative upon the piles that have already been written about this partnership, let's cut straight to the chase.

WHAT IS MICROSOFT'S PROBLEM

In a two words: hardware and apps.

Arguably, Microsoft has an innovative mobile OS with Windows Phone that is ahead of its time. But the hardware is lukewarm at best. The hardware partners for WP7 have all introduced devices that do little to differentiate from Android counterparts, and they have failed to rival the lust worthy industrial design of devices like iPhone 4 or Motorola Droid.

Meanwhile, as the hardware fails to draw consumers in droves away from the sexy gadgets available from Apple and various Google partners, Microsoft faces a chicken and egg problem. They need stronger adoption to motivate developers to strongly back WP7, but they need more apps to gain adoption. Partners like Telerik are helping with programs designed to spur early WP7 app development, but more fuel is need to turn these sparks in to a roaring marketplace and platform.

WHAT IS NOKIA'S PROBLEM

In two words: software and focus.

Everyone understands Nokia's software problem. After dominating dumbphones for years, Nokia failed to transition to modern smart phones fast enough to remain relevant. They have proven unable to move fast enough independently to solve their software woes without assistance.

As they struggle with software, that has led to some stumbling hardware designs. Saddled with an OS unable to support modern smart phone concepts, Nokia engineers have been producing phones that fail to impress.

WHAT MICROSFT AND NOKIA DO WELL

Despite their problems in today's smart phone market, Microsoft and Nokia are two industry veterans very familiar with the mobile market and loaded with "weapons" for a renewed mobile battle. Among their biggest strengths:

Microsoft brings:

  • The huge .NET developer audience that already has the skills to build WP7 apps (they just need more incentive)
  • Industry leading development and debugging tools (just compare the process of registering a WP7 dev device to Apple's iPhone dev device registration process for a good case-in-point)
  • A mature partner network and developer ecosystem, with vendors like Telerik already gearing-up to provide tools unmatched by competing platforms
  • A critical understanding that the future of Microsoft depends heavily on the success of WP7
  • Lots of cash

Nokia brings:

  • Unmatched hardware distribution channels. Nokia shipped more than 111 million devices in 2010, compared to Apple's 47 million and Android's 67 million.
  • Highly tuned supply chain (you don't ship 111 million devices without one)
  • One of the most valuable consumer brands in the world (Microsoft brings this, too)
  • With the ousting of internal software efforts, a critical understanding that they must build great hardware or die

MICROKIA: THE PERFECT MARRIAGE

Nokia and Microsoft may be operating from positions of weakness today, but they are the perfect example of two companies that are stronger together than independent.

With Nokia providing near exclusive focus on producing killer hardware, and Microsoft re-focused on improving upon its innovative mobile platform, "Microkia" (as the Microsoft + Nokia partnership has been dubbed) is positioned to start shipping devices by the end of 2011 that firmly leap-frog Android and maybe even iOS, which is starting innovate more slowly under the weight of its huge adoption. If Microsoft and Nokia combined can't make Windows Phone succeed, it never will.

THE MISSING CONVERSATION: TABLETS

Everyone (self included) has accused Microsoft of missing another cycle by failing to have a good answer for the iPad early this year. Nokia may be the godsend Microsoft needs to recover.

If Nokia is no longer investing significant energy in software, it has "nothing" to do other than focus on designing and building great hardware. Imagine a sexy Nokia tablet concept running Windows Phone 8 (the naming of the tablet OS gets a bit tricky…can't go back to Windows Mobile or Windows OS) by late 2011. If, and this is the big IF, Nokia and Microsoft can execute on these opportunities together, they can re-spark the excitement both companies so desperately need.

SURPRISE! THE ANALYSTS ARE WRONG

Many analysts and pundits seem to think Microsoft and Nokia are "screwed" because Android and iOS have sizable leads in the modern mobile world. Really? How much of a "lead" did RIM and Microsoft have when Apple hit the scene in 2007? Remember the headlines? How about:

In those articles, we find quotes from the same pundits and analysts dooming Nokia and Microsoft, like this choice insight from Forrester:

"The iPhone will not substantially alter the fundamental structure and challenges of the mobile industry."

Among the pundits arguments against Apple at the time? You got it. Apple is "too late" to the game. Sound familiar? That's one of the primary assaults launched against Nokia and Microsoft for not having the apps and hardware they need to compete on the market today.

Give it time. Give it 2011. Microsoft and Nokia are more focused than they have ever been on making Windows Phone succeed. The future of both companies depends on it, and they have the resources, focus, and ammunition to go to battle and win.

(SIDE NOTE: Remember Xbox? Another great example of Microsoft making a come-from-behind play for a market and toppling two well entrenched industry giants. Ironically, Xbox may now play a critical role in helping Windows Phone achieve similar success.)

WINDOWS PHONE IS GOLD

What should you, the developer, take from this lengthy analysis? If you're sitting on the sidelines with Windows Phone, rethink your position. Now is the time to get in ahead of the coming rush of excitement Nokia and Microsoft will create later this year. There will soon be an explosion of apps for Windows Phone and a wave of consumers to buy them; the next major mobile gold rush.

Telerik is clearly committed to helping you seize the opportunities of this gold rush by providing highly optimized tools for Windows Phone apps, so get started today. Or don't. Just don't be surprised when Nokia is shipping 60+ million Windows Phone devices and your app is missing.

Monday, February 14, 2011

Why not ORM: 5 ORM myths dispelled, Part 1

ORM-Robot Let's start with a DISCLAIMER: If you are already an active user of any ORM, this specific post is not for you. I'll talk to you later. For everyone else, let's continue.

In my role as a technical evangelist, I get the chance to travel the globe and talk to developer audiences on a regular basis. To keep a clear picture of how developers are working, I often informally poll audiences and try to listen for trends in development behavior. One trend that continues to stand out is how many developers still do all data access by hand!

What do I mean "by hand?" I mean manually creating and destroying ADO.NET objects (like SqlConnection and SqlCommand) to move data between apps and data stores. (This includes developers that use tools to simply auto-generate "by hand" code- that's just saving keystrokes.)

Does that describe you? Hopefully it does to a certain degree (otherwise you've overlooked and/or disregarded the DISCLAIMER). You need to stop. You need to reevaluate how and why you're building applications.

DON'T DEVELOP LIKE IT'S 1999

I'm going to talk primarily to web developers, A) because it's what I know best, and B) because I know many readers of this blog are just that. Think back to web development circa 1999 and good 'ol "classic" ASP. We've moved well beyond the days of those spaghetti code script pages, but let's illustrate how data access was commonly done:

Dim Conn
Dim SQLTemp

Set Conn = Server.CreateObject("ADODB.Connection")
Conn.connectionstring =
 "Provider=Microsoft.Jet.OLEDB.4.0;Data
 Source=" & Server.MapPath("\database_name.mdb")& ";"
Conn.Open

SQLTemp = "SELECT * FROM table_name"
set rstemp=Conn.execute(SQLTemp)

Do While Not rstemp.EOF

rstemp.Fields("field_name").Value

rstemp.MoveNext
Loop

Conn.Close
Set Conn = Nothing
You created a connection object. You created a command. You executed it and looped through the results. And in an application working with lots of data, you did this over, and over, and over…
Fast forward to the modern .NET era. If you're still doing data access "by hand" (or having a tool generate code for you), you are probably doing some variant of this:
SqlConnection conn = new SqlConnection("connection string...");

SqlDataReader rdr = null;

try
{
   conn.Open();
   SqlCommand cmd = new SqlCommand("select * from Customers", conn);

   rdr = cmd.ExecuteReader();

   while (rdr.Read())
   {
       Console.WriteLine(rdr[0]);
   }
}
finally
{
   //Clean-up...
}
An improvement syntactically over VBScript, yes, but in concept it's the same old "naive" model for working with data: create connection, create command, execute and process results. Sure, you can wrap this in a pretty "framework"- you pass-in SQL, you get back a DataSet- but you're still doing pretty "raw" data access. There is no "software intelligence" helping you look for opportunities to lazy load data, optimize SQL, or cache data efficiently. That's all on you! There must be a better way.
 
THE MIGHTY ORM
 
Ah, ORM- that's Object Relational Mapper, for the uninitiated. Tomes have been written about ORM over the years, its benefits, its problems, its limits. Boil it all away and a good ORM (generally speaking) has a simple goal: make it easier to for developers to work with data. Data access is not rocket science. Information sitting in structured tables on disk needs to be retrieved and loaded in to memory for an application to do additional processing. Things get a bit harder when you introduce the real world complexities of a reliable, performant system. Data access needs to be fast, it needs to ensure data integrity, and it needs to be efficient so it doesn't "hog" server resources.
 
Still, these are well defined problem areas that don't change from application to application. These are the kinds of narrow, well-defined problems robots (i.e. software) are really good at solving. So that ultimately begs the question…
 
WHY DON'T YOU USE ORM
 
If there are tools, like ORMs, that make data access easier without compromises, then why would anyone (you!) continue to do data access by hand? I have some theories. I think there are some powerful myths surrounding ORMs that prevent hard working developers from realizing ORM benefits:
  1. MYTH #1: ORMs are difficult to configure, Learning curves are too steep
    A common myth surrounding ORM is that in the time it would take to configure and learn the ORM system, you can finish creating the data access you need by hand with time to spare. This myth earns its reputation honestly. In the early days of ORM, there were few options for .NET, and those that did exist, like NHibernate, did require some pretty gnarly XML configurating. But that was then.

    Today, .NET developers have a host of ORM options, some of which can have you up and running in minutes. Take LinqToSql or OpenAccess ORM. Both provide simple visual designers that let you easily configure an ORM data context in seconds. OpenAccess even provides wizards on top of the designer to further streamline the setup process. Entity Framework, while more complex, also offers a rich visual designer.

    CONCLUSION: Myth busted. The ORMs of today are easy to configure. If you're avoiding ORM because you remember the XML config days, it's time to look again.

  2. MYTH #2: I can't give-up Stored Procedures, and ORMs don't use Stored Procs
    I'll save the religious debate about the necessity of stored procedures for another day, but any ORM worth its salt today offers support for Stored Procedures. Some offer better stored proc support than others, but with a good ORM, you can "hydrate" (that's an ORM term that means initialize your model objects with data from your database) objects using stored procs and forego completely ORM generated SQL.

    CONCLUSION: Myth busted. Stored Procs are not an excuse for avoiding ORM.

  3. MYTH #3: It's difficult to keep the database and ORM in sync.
    A great myth, and true for simple ORMs like LinqToSql, but absolutely false for ORMs that provide powerful Visual Studio tools. Thanks to improved framework features, like partial classes, and improved tooling, like OpenAccess' wizards, the process of merging database schema changes in to your mapped ORM classes is no longer a frustrating "blow all your customizations away" event. In fact, tools like OpenAccess are powerful enough to go the other direction and merge changes in your classes back in to your database schema! How's that for developer power?

    CONCLUSION: Myth busted. It's not hard with modern tools and framework features to keep database and ORM code in-sync.

  4. MYTH #4: I can't optimize an ORM. I'm stuck with its data access decisions.
    This is true for many ORMs, but with powerful ORMs like Telerik's OpenAccess, even this is a myth for the past. Using simple configuration steps, you can give ORMs "hints" that optimize query plans in your application. Generating hundreds of SELECTs when loading a collection of objects? No problem. Specify a fetch plan and those hundreds of statements can be condensed in to one or two powerful SQL statements.

    CONCLUSION: Myth busted. True, some ORMs leave you hanging when it comes to optimization (like LinqToSql). But powerful, full-featured ORMs like OpenAccess even make optimization a simple process.

  5. MYTH #5: I don't trust the SQL that an ORM produces.
    The big one! I'd wager this is one of the TOP reasons developers like you avoid ORMs. You don't trust them. You don't trust the SQL they generate and you don't feel like you have a good idea how those simple design-time LINQ queries get expanded to "real SQL" at runtime. Sure, you can fire-up SQL Profiler (or the free AnjLab SQL Profiler Express) and try to see what's coming-out of your app at runtime, but that's inconvenient and can be difficult to analyze. I'd say this is the one myth that continues to trouble today's ORMs. Yes, there are commercial tools that can help with profiling, but out of the box, ORM is largely a "black box."

    CONCLUSION:
    Plausible. This myth presents a challenge that needs a solution. If you're going to stop doing data access by hand, you need to be able to peer-in to the black box and form a trust with your ORM.

GETTING PAST THE 5th MYTH

If lack of SQL transparency- which I think leads to a lack of trust- is one of the biggest barriers to ORM adoption, then it's the problem that should be solved. You should not waste days of your development life writing unnecessary data access code simply because it's too hard to peer-in to the ORM black box and form an understanding of what's happening. What do we need? We need an easy way to see what our ORM is doing. A tool that will help us easily find ways to optimize ORM behavior and establish a close working relationship so that you can focus on application development, and the ORM can focus on moving data.

In Part 2, I'll introduce a simple tool that I've crafted that will help you do exactly that for OpenAccess ORM. In the mean time, let's all agree to stop wasting time, get past our 1999 data access patterns, dispel the myths, and give ORM a try. And since OpenAccess ORM is FREE, why not start today?!

Tuesday, February 08, 2011

Troubleshooting OpenAccess ORM VEnhance errors

venhance-error

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:
  2. <?xml version="1.0" encoding="utf-8" ?>
    <configuration>
    <startup>
      <supportedRuntime version="v4.0"/>
    </startup>
    </configuration>
  3. 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.
  4. 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
  5. 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!