Developing sites using the MVC framework

Kentico supports website development using ASP.NET MVC⁠ (opens in a new tab).

Installation and configuration

When you install Kentico, the project includes MVC 4 libraries by default. You can perform an upgrade if you wish to use a newer MVC version.

We recommend the following installation configuration for MVC projects:

• .NET Framework version: .NET Framework 4.5 / 4.5.1
• Web project type: Web application (the ASP.NET MVC framework is fully supported only for web applications)

Developing MVC projects

When using ASP.NET MVC to develop your website, we recommend using Kentico as a content platform.

This means that you use Kentico to store data and manage content (via pages and custom tables), and generate the entire design of the site using your own MVC controllers and views. We also recommend handling routing manually using the standard MVC approach.

To summarize:

• You implement Controllers and Views in a standard MVC project within the Kentico solution
• You manually manage routing
• The live site is generated by your MVC code
• Content is managed via the Kentico application

MVC project structure

When you open the Kentico application in Visual Studio (using the WebApp.sln file), the solution includes the CMSApp_MVC project by default. This project is a standard MVC 4 project where you can define routes, and develop your controllers and views.

On the file system, the MVC project files are in the same folder as the main Kentico application — inside the CMS folder in the project directory.

The project contains the following folders by default:

• App_Start - standard MVC project folder. Contains RouteConfig.cs where you can handle your routing.
• CMS_MvcModule - Kentico folder containing a module class that initializes the MVC functionality when the application starts. You can use the class's OnInit method to register custom event handlers for your MVC project.
• Controllers - stores controllers. Contains a sample controller for displaying news pages by default.
• Models
• Views - stores views. Contains a sample view for displaying news pages by default.

Best practices for MVC development

Routing

• The optimal solution is to upgrade to MVC 5 and use attribute routing⁠ (opens in a new tab).
• You can register your routes in the RouteConfig.cs file in CMSApp_MVC/App_Start.
• To improve performance, we recommend excluding the URLs defined by your routes from the Kentico rewriting engine (Settings -> URLs & SEO -> Excluded URLs).
• If possible, avoid routes starting with placeholders, such as {controller}/{action}/{id}. Placeholders at the start of the route also match some of the URLs used by the Kentico system and you may need to manually exclude the URLs to avoid problems.
  • You can either add a fixed prefix to the beginning of your routes or register all routes covered by the first placeholder (for example routes for all controllers if you start with the {controller} placeholder).

Controllers

• When using the view locations that support the Kentico export, return the full path of views for the actions in your controllers:

  C#

  Copy

  return View("~/Views/CorporateSite/News/List.cshtml", newsList);

• Load the data and settings of pages using the Kentico API. See MVC code examples for more information.

Views

• We recommend using the Razor view engine. However, other view engines are also supported.

Models

• We recommend using the Kentico API classes (Info objects) for your models.
• If you use data container classes (for example TreeNode), you can create a simplified model class with the required public properties, and use this class in strongly typed views.

Exporting MVC sites

You can export your sites along with controller, view and model code files. To ensure that the files are included in the export package, you need to use the following locations in the CMSApp_MVC project.

Controllers:

• Controllers/<siteName>/<*controllerName*>.cs - included in the package if the Export files -> Export site folders option is enabled for the export.
• Controllers/Global/<*controllerName*>.cs - included in the package if the Export files -> Export global folders option is enabled for the export.

Views:

• Views/<siteName>/<*viewName*>/<*action*>.cshtml - included in the package if the Export files -> Export site folders option is enabled for the export.
• Views/Global/<*viewName*>/<action>.cshtml - included in the package if the Export files -> Export global folders option is enabled for the export.

Models:

• Models/<sitename>/<modelName>.cs - included in the package if the Export files -> Export site folders option is enabled for the export.
• Models/Global/<modelName>.cs - included in the package if the Export files -> Export global folders option is enabled for the export.

Routes:

The RouteConfig.cs file is not automatically included in the export package. You either need to transfer the file manually, or use attribute routing⁠ (opens in a new tab) in your controller files (MVC 5 only).

Importing MVC code files

When you import a package containing controller and view code files, you need to:

1. Open the web application in Visual Studio.
2. Manually include the imported files into the CMSApp_MVC project.
3. Build the CMSApp_MVC project.

Setting MVC routes for pages directly

It is possible to set the MVC route (and the default controller and action) for individual pages directly in the Kentico administration interface.

1. Open the Pages application.

2. Select the page in the content tree.

3. Open the Properties -> URLs tab.

4. In the Page URL path section, set the Path type to MVC.

5. Enter a path or route into the Path or pattern field.

   MVC URL patterns support the following syntax:

   • {controller}, {action} - allows you to specify controllers and actions dynamically through the placeholder segments in the URL. For example, the /{controller}/{action}/{id} pattern can be used to direct users to pages generated by any controllers or actions.
   • {name;value} - provides a way to set the default value of the placeholders in the URL. For example,*/{controller;NewsMVC}/{action;Detail}/{id;My-First-News}*has the same functionality as the previous option, but the system is able to automatically generate the default URL /NewsMVC/Detail/My-First-News for the page if the placeholders do not have values specified.
   • {*name;value*} - hidden value, which is passed as a parameter to the action handler in the controller class, but is not incorporated into the URL itself. For example, /NewsMVC/List{*TopN;10*} generates the /NewsMVC/List pattern and provides the value of the TopN parameter during the processing of the request.

6. Specify the following:

   • Default controller - sets the name of the controller class containing the MVC action that the system performs when visitors access the page. Enter the class name without the Controller part at the end, for example NewsMVC if the class is called NewsMVCController. The system first searches for the specified class in the CMS.Controllers.<current site code name> namespace. If the class is not found there, the CMS.Controllers.Global namespace is searched.
   • Default action - specifies the exact action defined within the controller class.

7. Click Save.

When a user accesses the page's URL, the system runs the specified controller and MVC actions and the output is generated by the corresponding view. The advantage of this approach is that you can:

• Access the DocumentContext.CurrentPageInfo object in the code of your controllers. The object carries the data of the currently viewed page, and provides automatic caching.
• Leverage standard Kentico output caching for pages.

Handling MVC patterns through page aliases

You can define any number of page aliases for pages, each with a different URL and MVC controller/action settings. The system uses the specified controller and action instead of the default configuration when the page is accessed through the alias URL (pattern).