Images in this post missing? We recently lost them in a site migration. We're working to restore these as you read this. Should you need an image in an emergency, please contact us at
Integrating Castle MonoRail into Legacy Code

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

kick it on

Posted 06-26-2007 4:18 PM by Billy McCafferty



Derik Whittaker wrote re: Integrating Castle MonoRail into Legacy Code
on 06-26-2007 7:43 PM

Great post Billy.  

Now if I only had a app to port :(  Oh well

Steve Gentile wrote re: Integrating Castle MonoRail into Legacy Code
on 06-26-2007 8:40 PM

Excellent - this is good stuff Billy - glad to see you using Monorail.

Nathan wrote re: Integrating Castle MonoRail into Legacy Code
on 06-26-2007 9:02 PM

Could you perhaps write a few words on what factors lead you to chose Brail? I've only had a cursory glance at MonoRail and noticed it supported multiple view engines.

Billy McCafferty wrote re: Integrating Castle MonoRail into Legacy Code
on 06-27-2007 12:21 PM

Here's a good rundown of the comparison of the available view engines: .  After comparing the options, I felt Brail is the most flexible, is being actively developed, has good community support, and has nice view syntax.  It also lends itself easily to a more powerful version of Passive View by allowing the view to access properties of the domain model directly.  This cuts down on the number of items that need to be passed to the view.  (It also lends itself to possible abuse but not anything as bad as what can be done in a code-behind page.)

If your considering MonoRail, you should carefully consider all the view options to determine what might work best for you and your team.

Richard wrote re: Integrating Castle MonoRail into Legacy Code
on 06-27-2007 1:23 PM

The documentation states that *.boo should be wired up with the HttpForbiddenHandler because that's how it's done with RC2. In the trunk, which you are using, this has been changed to *.brail. See

Billy McCafferty wrote re: Integrating Castle MonoRail into Legacy Code
on 06-27-2007 1:33 PM

Thanks Richard!

hammett wrote re: Integrating Castle MonoRail into Legacy Code
on 07-01-2007 10:46 PM

Not going with Windsor Integration?

Billy McCafferty wrote re: Integrating Castle MonoRail into Legacy Code
on 07-02-2007 5:59 PM

Hey there hammett...I'd love to.  I've been working on integrating in for the last couple of days.  Since you're interested ;), I'll add a help request to the Castle forums.

Steve Gentile wrote re: Integrating Castle MonoRail into Legacy Code
on 07-02-2007 8:26 PM

I've been trying get Ayende's 'Exesto' sample off the ground.  Include  Bindsor, Brail, IRepository<T> (IDao).  

Although the version on SVN doesn't build and he hasn't been able to figure out why yet, (or rather maybe he isn't interested in seeing why it doesn't run?)

But it would be a good sample to show - it includes a few view components (smartgridcomponent), scaffolding, etc...

Uses Windsor and Castle AR.

Let me know if I can help in any way, I've been pounding away at this and getting closer (I think).   Basically all the pages I have working minus the scaffolding pages.

Let me know if I can help

Pattern Matching » MonoRail & Brail Example wrote Pattern Matching &raquo; MonoRail &#038; Brail Example
on 08-25-2007 12:27 AM

Pingback from  Pattern Matching &raquo; MonoRail &#038; Brail Example

Billy McCafferty wrote Castle Project cooler than Jerry Springer
on 09-21-2007 2:00 PM

There, I&#39;ve said it. If Castle Project has been on your &quot;need to check that out list,&quot;

Sam Gentile wrote New and Notable 175
on 12-11-2007 6:20 PM

Temps near 100 F and 100% humidity make for some pretty uncomfortable days Windows Workflow Sometimes

Sam Gentile's Blog wrote New and Notable 175
on 12-02-2008 9:32 PM

Temps near 100 F and 100% humidity make for some pretty uncomfortable days Windows Workflow Sometimes you have to go beyond the two root models of WF which are Sequential and State. We needed to and ended up using a hybrid of rules driven and state. Matt

About The CodeBetter.Com Blog Network
CodeBetter.Com FAQ

Our Mission

Advertisers should contact Brendan

Google Reader or Homepage Latest Items
Add to My Yahoo!
Subscribe with Bloglines
Subscribe in NewsGator Online
Subscribe with myFeedster
Add to My AOL
Furl Latest Items
Subscribe in Rojo

Member Projects
DimeCasts.Net - Derik Whittaker

Friends of
Red-Gate Tools For SQL and .NET


SmartInspect .NET Logging
NGEDIT: ViEmu and Codekana
NHibernate Profiler
Balsamiq Mockups
JetBrains - ReSharper
Web Sequence Diagrams
Ducksboard<-- NEW Friend!


Site Copyright © 2007 CodeBetter.Com
Content Copyright Individual Bloggers


Community Server (Commercial Edition)