Billy McCafferty

After deciding to migrate our current project to Castle Project's MonoRail, next came the task of going through the available documentation, forums and sample code to determine how best to integrate the MonoRail Project into our legacy application.  What follows should serve as a solid tutorial if you choose to take this path with legacy code as well.  (If you're beginning a new, ground-up solution, a getting starting sample may be downloaded from the Castle Project website.)  These integration steps make the following assumptions:

• Using Castle MonoRail Build 429 from the Castle Build Server; more recent builds should most likely work just as well.
• Brail has been selected as your view engine.
• Your domain/core classes are kept in a separate assembly from the web project.
• IIS is your web server of choice.

Integrating Castle MonoRail w/Brail Views into Legacy Code

1. From the build zip, add the following DLLs to your "Solution Items" folder:
   • Boo.Lang.dll
   • Boo.Lang.Compiler.dll
   • Boo.Lang.Parser.dll
   • Castle.Components.Common.EmailSender.dll
   • Castle.Components.Validator.dll
   • Castle.Core.dll
   • Castle.MonoRail.Framework.dll
   • Castle.MonoRail.View.Brail.dll
2. Add a new project to your solution to hold the MVC controllers.  In my own applications, I name each assembly using the following convention:  <project name>.<assembly scope>; e.g. MyProject.Controllers.  (I discuss my default architecture in a previous post.)  If you're already using MVP or another separation-of-concerns technique which has a dedicated assembly for presentation logic, I still recommend adding a new controllers specific assembly.  This should minimize confusion between what's using the "old way" and what's using the "new way."
3. Within the controllers assembly, add references to:
   • Castle.Components.Common.EmailSender.dll
   • Castle.MonoRail.Framework.dll
4. Within your web project, add references to:
   • The MyProject.Controllers project
   • Boo.Lang.dll
   • Boo.Lang.Compiler.dll
   • Boo.Lang.Parser.dll
   • Castle.Components.Validator.dll
   • Castle.Core.dll
   • Castle.MonoRail.View.Brail.dll
5. Follow the First Controller steps in the Getting Started guide to create your first controller, HomeController, in the controllers project.
6. Augment web.config with the following:

   <configSections> <section name="monoRail" type="Castle.MonoRail.Framework.Configuration.MonoRailSectionHandler, Castle.MonoRail.Framework"> <!-- Declared so that MonoRail views can be set to communicate with domain layer classes --> <section name="Brail" type="Castle.MonoRail.Views.Brail.BrailConfigurationSection, Castle.MonoRail.Views.Brail"> </configSections> <monoRail> <controllers> <assembly>MyProject.Controllers</assembly> </controllers> <viewEngine viewPathRoot="Views" customEngine="Castle.MonoRail.Views.Brail.BooViewEngine, Castle.MonoRail.Views.Brail"> </monoRail> <Brail saveDirectory="Brail_Generated_Code" commonScriptsDirectory="CommonScripts"> <reference assembly="MyProject.Core"/> </Brail> <httpHandlers> <!-- Have Castle MonoRail handle anything with a rails extension --> <add verb="*" path="*.rails" type="Castle.MonoRail.Framework.MonoRailHttpHandlerFactory, Castle.MonoRail.Framework"></add> <!-- Block user access to Brail templates --> <add verb="*" path="*.brail" type="System.Web.HttpForbiddenHandler"></add> </httpHandlers> <httpModules> <add name="monorail" type="Castle.MonoRail.Framework.EngineContextModule, Castle.MonoRail.Framework"></add> </httpModules>

   Note that "MyProject.Core" should be replaced with the assembly name which holds your domain/core classes. (There may be multiple.)  Also, the documentation states that *.boo should be wired up with the HttpForbiddenHandler.  Although the documentation has not been updated, the most recent code trunk requires that you mask the *.brail extension instead; but after doing this, the wiring doesn't seem to work for me in preventing a user from viewing the raw view.  I'm assuming I've missed something here but wanted to show how it's supposed to work.
7. Adapt IIS to handle the rails extension as outlined in the Getting Started guide for your website or virtual directory.
8. Build the controllers project and browse to http://localhost/MyProject/home/index.rails.  You should get an error as follows:  "Could not find view template: home\index"
9. Add the following folder structure to the root of the web project:  /Views/Home.
10. Add Index.brail and About.brail files to the Home directory and put differing "hello world" content in each (so you can tell them apart).  You should now be able to browse to http://localhost/MyProject/home/index.rails and http://localhost/MyProject/home/about.rails while not breaking any of the existing functionality.

The above steps represent the minimal actions necessary to get MonoRail integrated into a legacy application.  Further options and capabilities may require further integration steps with additional Castle assemblies.  Only integrate MonoRail into a legacy application after careful consideration of the maintenance implications.  Developers will now need to be aware of multiple presentation models being maintained within the legacy application and how to deal with both.  Introducing a paradigm shift into an existing application can cause a lot of havoc breaking the adhere to the style of the original rule of thumb.  But sometimes, a style needs to be broken. ;)

Billy McCafferty