• Hello Orchard – Creating a Orchard module using latest source code

    by  • July 25, 2010 • Orchard CMS • 11 Comments

    What is Orchard?

    Project Orchard is the latest open source CMS project by folks in Microsoft based on ASP.NET MVC platform. It has some relationship with project Oxite which is another CMS used by the MIX event website. You can read more about Orchard from the official website here. And you can also check out the official download as well as the latest build from Codeplex. It is light weight where you can do copy-paste deployment onto shared webhosting, doesn’t require SQL Server to run yet at the same time you can add functionalities as a Orchard Module.


    Official Download

    The official download dates back to March 2010 at the time of MIX 2010. The feature sets are primitive and less composite than what’s in the roadmap. It has been 4 months since the release and the team will release a official Alpha release by end of July 2010.

    Having said that, the March release comes with a walkthrough which you can follow to build a customized module for Orchard. You can check out the walkthrough here.

    March 2010 release

    Walkthrough Document

    Video walkthrough

    Latest Build

    In the true spirit of open source, the Orchard team chose Mercurial instead of Team Foundation Server to be the source code host of the project. Codeplex supports both source control systems maybe because of some non-.NET or non-Windows hosted there.

    In the March 2010 release Modules are actually ASP.NET MVC 2 Area where else in the latest build, they are individual ASP.NET MVC Web App. The new module design makes Orchard more suitable for composition and multi tenancy, in a way like SharePoint features.

    Because of this architecture change, the walkthrough mentioned above does not work with the latest build. So in this and subsequent blog post, I will share more about creating a customized module for latest build of Orchard

    Downloading latest build

    To get the latest build, you either download from the source tree using TortoiseHG which is a Windows based Mercurial client (instructions here) or you can download the latest changeset from the source code page at Codeplex.


    Whenever you download source code packages as a zip file from the Web, remember to ‘unblock’ it from the file property page else Visual Studio will give you a not trusted source warning message which can be annoying at times.



    Understand the Orchard architecture

    I won’t dwell too deep into this as Bertrand Le Roy wrote an extensive document titled How Orchard Works here. Architects should read this document first to understand how things work.

    Accessing the latest change set


    I downloaded the latest change set as of today and from Windows Explorer you will notice there are 2 Visual Studio solution file. Note also that it has been updated to support Visual Studio 2010 solution. You also note that there is a Windows Azure solution file here but let’s check this out in my future post.

    The whole Orchard application framework is inside the Orchard folder while Orchard.Web is the ASP.NET project which can be hosted inside IIS. Let’s open up Orcahrd.sln using VS2010.


    All in all there are more than 30 projects in project Orchard with Orchard.Core, Orchard.Framework and Orchard.Web at the center of this CMS. On top of that there are some core modules which Orchard needs such as the User, Pages, and Setup modules.

    Build and setup a sample site

    Orchard supports both SQL Server and SQLite database but for sake of debugging and troubleshooting I will choose SQL Server. Let’s create an empty database inside SQL Server called OrchardTutorialDB in the local SQL Express instance.


    Back to Visual Studio 2010 with the project opened, press Ctrl-F5. IE will be opened and you will see the Orchard setup page


    At this page, you need to give a name for the website and assign a website admin account. Then click on ‘Use an existing SQL Server database’ to setup SQL Server. Key in the connection string in the following format

    Data Source=.\sqlexpress;Initial Catalog=OrchardTutorialDB ;User Id=myUsername;Password=myPassword;

    Note: Skip and leave the Database Table Prefix empty at the moment because of a known bug with using the prefix


    Click ‘Finish Setup’ and a few minutes later you will see the website up and running!


    I will normally change my theme to a more presentable one.


    Hello Orchard – Adding a new Module

    Note: from this point onwards I will reuse some of the text in the Orchard Walkthrough document.

    NOTE: Step 2 to 4 and 15 to 17 are very additional steps to make the walkthrough works in the new change set.

    The objective here is to build a very simply Hello World style webpage themed by Orchard with a menu item on top.


    1. A simple custom area that renders “Hello World” on the app’s front-end

    2. Views in the custom area that take advantage of the currently applied Orchard theme

    3. A menu item on the front-end for navigating to the custom area’s view

    Follow These Steps:

    1. Right-click the Modules node in VS Solution Explorer, and choose “Add > New Project…”


    2. In the project creation screen, choose “ASP.NET MVC 2.0 Empty Web Application”

    <Very Important> On the path text box, it is default to <Orchard location>\src folder. Change it to <Orchard location>\src\Orchard.Web\Modules\ folder (Screenshot below). Else Orchard will not recognize the new module.

    Finally Type “Orchard.Commerce” for the area name and click [OK].


    3. For Orchard to discover this module, you need to add a module.txt file at the project root folder and insert the following content.

    name: Commerce
    antiforgery: enabled
    author: Patrick Yong
    website: http://patrickyong.net
    version: 0.1
    orchardversion: 0.1.2010.0312
    description: Commerce
    features:    Orchard.Commerce:
    Description: Commerce.
    Category: Commerce

    4. Modify the web.config file accordingly. Basically I added <httphandlers> and <handlers> in <System.WebServer> for MVC routing.

    <?xml version="1.0"?>
    <!--  For more information on how to configure your ASP.NET application, please visit  http://go.microsoft.com/fwlink/?LinkId=152368  -->
       <!--             Set compilation debug="true" to insert debugging             symbols into the compiled page. Because this             affects performance, set this value to true only             during development.    -->
       <compilation debug="true" targetFramework="4.0">
          <add assembly="System.Web.Mvc, Version=, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
          <add assembly="System.Web.Abstractions, Version=, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
          <add assembly="System.Web.Routing, Version=, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
          <add assembly="System.Data.Linq, Version=, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
       <error statusCode="404" redirect="FileNotFound.htm" />
    </customErrors>    -->    <pages controlRenderingCompatibilityVersion="3.5" clientIDMode="AutoID">
       <add namespace="System.Web.Mvc"/>
       <add namespace="System.Web.Mvc.Ajax"/>
       <add namespace="System.Web.Mvc.Html"/>
       <add namespace="System.Web.Routing"/>
       <add namespace="System.Linq"/>
       <add namespace="System.Collections.Generic"/>
       <add namespace="Orchard.Mvc.Html"/>
          <add verb="*" path="*.mvc" validate="false" type="System.Web.Mvc.MvcHttpHandler, System.Web.Mvc, Version=, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    <!--         The system.webServer section is required for running ASP.NET AJAX under Internet        Information Services 7.0.  It is not necessary for previous version of IIS.  -->
       <validation validateIntegratedModeConfiguration="false"/>
       <modules runAllManagedModulesForAllRequests="true"></modules>
          <remove name="MvcHttpHandler"/>
          <remove name="UrlRoutingHandler"/>
          <add name="MvcHttpHandler" preCondition="integratedMode" verb="*" path="*.mvc" type="System.Web.Mvc.MvcHttpHandler, System.Web.Mvc, Version=, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
       <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
             <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
             <bindingRedirect oldVersion="" newVersion="" />

    5. Right-click the newly created “Ocrhard.Commerce > Controllers” folder, and choose “Add > Controller…”

    6. Name the Controller “HomeController”

    7. Right-click on the “Index()” method name and choose “Add View…”


    8. Selected the “Create a partial view” option and click [Add]


    9. Add the following HTML to the View page: <p>Hello World</p>

    10. Add Orchard.Framework and Orchard.Themes to the project reference


    11. Add the following namespace imports to the HelloController.cs file:

    using Orchard.Themes;
    using Orchard.UI.Navigation;

    12. Add an [Themed] attribute to the HelloController class:

    public class HomeController : Controller

    13. Add another class to create a new Menu item, you can create a new .cs file in the project root folder or add it inside the controller class

    public class MainMenu : INavigationProvider
            public Localizer T { get; set; }
             public String MenuName
                get { return "main"; }
             public void GetNavigation(NavigationBuilder builder)
                builder.Add(menu => menu.Add(T("Shop"), "4", item => item.Action("Index", "Home", new { area = "Orchard.Commerce" })));

    14. Type Ctrl-F5 to build and run in VS.

    15. Login as admin (using the admin account you created during setup) and navigate to the admin page


    16. Scroll down to look for Site Configuration menu and click on Features


    17. Voila! If you had done everything right, you will see Orchard.Commerce as a module under the Commerce category. Now click on the ‘Enable’ button.


    18. After a moment, message(s) will appear and to try out the feature, click on Your Site on top.


    19. Now you notice an additional item on the top menu



    10. Finally click on ‘Shop’ to Navigate to this URL in the browser: http://localhost:<port>/Commerce


    11 Responses to Hello Orchard – Creating a Orchard module using latest source code

    1. Jarik
      July 30, 2010 at 9:31 pm

      I like your tutorial, but C# and xml examples are not visible, probably you should change the style.

      I’m using Firefox.

    2. Pingback: Building a Staffing Website? A New Open-Source CMS to Consider

    3. Tom
      August 22, 2010 at 11:19 pm

      This ain’t working. And it’s very ambiguous with web.config files (there’s 1 in root and 1 in views, for example) so who knows, it might be “my” fault that it’s not.

    4. Hung Vu
      August 25, 2010 at 7:43 am

      Exactly what I need. Thanks. BTW, in step 12, you said: Add an [Themed] attribute to the HelloController class! What HelloController?

      I added an [Themed] attribute to the HomeController class and it work. But when I click on the “SHOP” menu, Orchard rendered only Hello World!, no styles/themes applied to new module! Could you please tell me what I did wrong?


    5. Gareth Mark Elms
      August 29, 2010 at 4:10 am

      Thanks for this I’m working through this series now

    6. Bob Tournoux
      November 26, 2011 at 12:16 pm

      This almost worked for me, but I had some errors in the Orchard.CommerceAreaRegistration.cs class. The class was created as:
      public class Orchard.CommerceAreaRegistration : Area Registration {

      But I had to remove the “Orchard.” from the class name in order to get it to build without errors. However, once built I did not see my new module. I’m working with version 1.3 and don’t know if that is the reason. I’m continuing on. Thanks for the detail.

    7. Alex
      February 2, 2012 at 8:10 am

      Looks good. I’ll give it a try tomorrow.

    8. Joseph
      April 11, 2012 at 4:38 am

      Hello, I followed step by step this tutorial, but always I got this error “The extension ‘Orchard.Commerce’ manifest could not be loaded. It was ignored.”
      I’m using the last version 1.4, (I’m very new in the Orchard world)
      can somebody help to figure it out this problem?

      • DGutt
        July 26, 2012 at 1:40 pm

        Hey mate, did you ever sort this error? I get exactly the same thing and it’s driving me mad? Thanks in anticipation, cheers Dyr

        • Mat
          October 1, 2012 at 10:43 pm

          Just luck, but I had an ‘&’ in my Author field in Module.txt, took it out and works fine…

    9. Pat
      June 9, 2014 at 3:43 pm

      I enjoy what you guys tend to be up too. This sort of clever work and reporting!

      Keep up the excellent works guys I’ve incorporated you guys to
      our blogroll.

    Leave a Reply

    Your email address will not be published. Required fields are marked *