Activating the Record

Lots of things happened since I last cared to blog. Here's the first one, chronologically. While I'm trying to not get too excited about Dependency Injection, I realized that it's about time to use some services in Inka, and I sort of needed an IoC container. My first idea was to use StructureMap by Jeremy Miller, but I wanted an automocking container for my tests as well, and I was forced to choose Castle Windsor. Or so I thought at that time -- it turned out that, first, I didn't have time to implement these things, and second, StructureMap also has an automocking container. But that's not the point.

The point is, I thought, hell, why not move to a decent ORM as well? Meaning Castle ActiveRecord.

My first ORM was Neo (Net Entity Objects, I think the name has been invented before The Matrix). Unlike Castle AR, which is really a nice interface for NHibernate, Neo is Active Record in a true sense. I'd even say, it's Typed DataSets Done Right. Each entity class is a wrapper over the DataRow class, so we can track the state (is it added, deleted, or modified) automatically. Each object is created via a factory, and added to the context automatically, so it can appear in your query results without being saved to a database. Cool. And also very convenient for testing.

Speaking of testing, I still can't figure out how to test AR applications without a database connection.

So, Neo is not for purists (nor is AR), they want POCOs. But I''m just a script kiddie, so it's OK for me. Neo's got a code generator, so I quickly enjoyed the idea and put all sorts of stuff into my templates, including some UI-related things. Don't blame me, I haven't heard about SoC in these days. In return, I managed to do some boilerplate stuff extra quickly.

Unfortunately, there's a very small community around Neo, and the development seems to stop. I've fixed a few bugs, but never got to publishing the fixes (only recently I learned that I had violated the LPGL license). Also, it's pretty simple, and perhaps won't cover more complex situations, including fat query results.

I'm only learning Active Record, and it has some very nice points (including a great graphic schema editor, Active Writer), but I've had some really weird moments with it. One, for example, is that I've been getting some weird exceptions that I wasn't able to reproduce in my tests. Almost intuitively, I invoked a Scope constructor at startup, and the problem was gone, although I never used the created scope variable anywhere! Turned out there's some dirty game with shared (static in C# :) variables here and there. I used to wonder why people hate these statics, now I know!

I'd like to learn more about AR, but now I'm totally thrilled by Ivonna being released soon, so I'm leaving the applied programming world for a while..

Oops

Hmm.. finally my layout engine for Inka is ready. Or so I thought. All tests are green, well, some are yellow, but come on. I was sure that I over-tested it and began planning to dramatically reduce the number of tests -- I start a demo app and discover that everything looks wrong!

Just can't help it!

Well, finally I'm at the point where I have to prepare an installer for Ivonna. Actually, I'm stuck at this point for about two weeks. Not because of installer itself, but because of the documentation. No, I diligently wrote all the xml comments, believe me. But these comments have to make way into a nice docs, preferably with some custom ("conceptual" in Sandcastle terms) content. And it has to be in Html Help 2.x format. This morning I finally discovered that my help can be viewed in the Document explorer. Was it because of the electricity been cut for a moment?

Anyway, here's my recipe. I'll be using VS 2005 with the 2007 SDK, Sandcastle January 2008 release, and DocProject 1.10.0 RC.

1. Install the VS SDK.
2. Install Sandcastle. It is important to install it after the SDK, because the SDK contains its own version of Sandcastle, which is too old. Anyway, if you installed Sandcastle first accidentally, just edit your DXROOT environment variable so that it points to the Sandcastle's folder.
   
3. Download and extract the presentation file patches. This fixes a bug in Sandcastle when you don't have a root topic.
   
4. Install DocProject. A major annoyance is a bug in the 1.10 RC version: the Add-in looks for the Project toolbar that has more than 40 items. Mine had only 38. The suggested workaround is to download the code and patch it manually, but I couldn't afford that, so, instead I wrote a macro that added 3 ugly entries to my Project menu. Anybody interested? Update: there's a 1.10.1 version that supposedly fixed this bug.
   
5. Add a DocProject to your solution. You can add a DocSite project instead if you need online help (it will build the offline help as well).
6. You might want to modify some templates offered by the DocProject wizard. But don't remove the feedback section entirely -- you'll get a JavaScript error later.
7. Modify the AssemblyInfo.cs file to reflect your documentation title and organization.
   
8. Don't ever rebuild the project -- it'll lose some essential files.
9. In the project wizard or later in the DocProject properties (available as an additional context menu item for your project), select "build html 2.0".
10. You might want to select the fastest build option -- choose "none" in the "build assembler options".
11. Now, after building the project, you have an HxS file in your output folder.
12. Unlike a chm file, you can't open it directly. Instead, you have to register it and navigate to it using the special ms-help protocol.
13. So, how do you register it?
14. The manual steps recommended copying a certain merge module from the sdk directory and manually editing it with Orca.
15. Like I was going to do that.
16. Actually I even did a first step.
17. But it turned out that there's a new kind of extensibility projects called "Help Integration Wizard". What you want is create a merge module that you'll add to your installation project. The wizard is pretty trivial, and it stores all its settings in the CollectionFiles folder, so you can edit them manually later.
18. At the first step, I chose the help file that I discovered in the Help/bin folder of my DocSite project.
    
19. The wizard showed me the structure of my future help. It contained one topic, called "sample topic" or something. it was on the left pane, and on the right there were my topics, conveniently excluded from the future help. I renamed the sample topic to "Ivonna", and added my topics under that root topic.
20. I also chose the namespace for my help -- ivonna.docs.
21. However, building the project didn't work for me, the postbuild event (the one that actually edited the merge module) failed. Invoking it manually from the command line failed as well. So, I opened the executable in the Reflector, and it turned out that it has been designed specifically in order to hide the possible cause of an error. For example, the exception was coming from a logging statement that was inside a catch block, so it was cleverly hiding the real exception. Also, all exception messages came from some native calls, so, for example, "File not found" turned into "Invalid handle".
    
22. So, I just wrote something that mimicked this app, and it somehow worked. Now I have a patched merge module that I can add to my installer. Update: It turned out that the problem was with the path -- it contained cyrillic characters. Once I created another project in a different location, everything went smooth.
23. Now, you should add the merge module from this project to your setup. You should probably create a Help folder under your app folder, and choose it for the merge module files. Choose the merge module in your setup project, and choose the folder in the Properties, KeyOutput -> MergeModuleProperties -> Module Retargetable Folder.
24. By the way, you can see all installed help namespaces via a handy utility located here: \Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Archive\HelpIntegration\Unsupported\Namespace.exe
    
25. You probably want to include a shortcut to your documentation. It should be something like this: "%CommonProgramFiles%\Microsoft Shared\Help 8\dexplore.exe" /helpcol ms-help://ivonna.docs. Note that I put my namespace after the "ms-help://" stuff. Yes, you are even able to view it in IE.
    
26. After you successfully made the installer, you discover that when the documentation opens it shows an empty page. If you want an introduction or something to appear, you should register it as "DefaultPage". Details can be found here.
    
27. Modify your shortcut like this: "%CommonProgramFiles%\Microsoft Shared\Help 8\dexplore.exe" /helpcol ms-help://ivonna.docs /LaunchNamedUrlTopic DefaultPage.

By the way, you can download Ivonna from my new site here, and view the online docs (produced with DocProject) here. I'll be blogging about Ivonna on my site's blog.