Is this really the version you are looking for? Kentico 8.2 documentation is no longer updated. Use the switch in the header to choose your Kentico version.

Developing sites using the MVC framework

Kentico supports website development using ASP.NET MVC.

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

Limitations

Kentico itself is a Web Form application and from an architectural point of view, it is not possible to combine MVC with Web Forms. You can have one application that combines MVC and Web Form pages, but you cannot combine these frameworks within individual pages.

The following scenarios are NOT supported:

  • Web parts and other Kentico components in MVC views
  • MVC views displayed in custom web parts
  • Kentico page permissions do not automatically apply to MVC pages. You need to check the permissions manually in your controller code (see MVC code examples for more information).

 

 

On this page

In this section

Related blogs

Please note: Articles linked here may not reflect the latest version of Kentico. Please report any issues with these links using the feedback form at the bottom of this page.

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.

Tip: When you make changes in the CMSApp_MVC project, you do not need to compile the whole solution, only the project itself.

Best practices for MVC development

Routing

  • The optimal solution is to upgrade to MVC 5 and use attribute routing.

  • 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:

    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.

Note: The standard controller location Controllers/<controllerName>.cs is not included in the export package.

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.

Note: The standard view location Views/<viewName>/<action>.cshtml is not included in the export package.

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 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

We recommend handling routing manually in the CMSApp_MVC project. The following features are intended for backward compatibility or special scenarios on websites that use MVC partially.

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).