---
title: Developing sites using the MVC framework
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Kentico supports website development using [ASP.NET MVC](http://www.asp.net/mvc).

## Installation and configuration

When you install Kentico, the project includes MVC 4 libraries by default. You can [perform an upgrade](https://docs.kentico.com/k8/developing-websites/developing-sites-using-the-mvc-framework/upgrading-the-mvc-version.md) 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 [documents](https://docs.kentico.com/k8/developing-websites/defining-website-data-structure/document-types.md) and [custom tables](https://docs.kentico.com/k8/developing-websites/defining-website-data-structure/custom-tables.md)), 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

> **Note:** **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](https://docs.kentico.com/k8/custom-development/developing-web-parts.md) and other Kentico components in MVC views
> - MVC views displayed in custom web parts
> - [Kentico document permissions](https://docs.kentico.com/k8/managing-users/configuring-permissions/configuring-document-permissions.md) do not automatically apply to MVC pages. You need to check the permissions manually in your controller code (see [MVC code examples](https://docs.kentico.com/k8/developing-websites/developing-sites-using-the-mvc-framework/mvc-code-examples.md) for more information).

### 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](https://docs.kentico.com/k8/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md) that initializes the MVC functionality when the application starts. You can use the class's _OnInit_ method to register [custom event handlers](https://docs.kentico.com/k8/custom-development/handling-global-events.md) for your MVC project.
- **Controllers** - stores controllers. Contains a sample controller for displaying news documents by default.
- **Models**
- **Views** - stores views. Contains a sample view for displaying news documents by default.

> **Tip:** **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](https://docs.kentico.com/k8/developing-websites/developing-sites-using-the-mvc-framework/upgrading-the-mvc-version.md) and use [attribute routing](http://blogs.msdn.com/b/webdev/archive/2013/10/17/attribute-routing-in-asp-net-mvc-5.aspx).
- You can register your routes in the **RouteConfig.cs** file in **CMSApp\_MVC/App\_Start**.
- To improve performance, we recommend [excluding](https://docs.kentico.com/k8/configuring-kentico/configuring-page-urls.md#excluding-urls-from-the-rewriting-engine) 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](#exporting-mvc-sites), return the full path of views for the actions in your controllers:

  ```csharp

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

  ```
- Load the data and settings of documents using the Kentico API. See [MVC code examples](https://docs.kentico.com/k8/developing-websites/developing-sites-using-the-mvc-framework/mvc-code-examples.md) 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](https://docs.kentico.com/k8/deploying-websites/exporting-and-importing-sites/exporting-sites.md) your sites along with controller and view 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/_/_.cs** - included in the package if the **Export files -> Export site folders** option is enabled for the export.
- **Controllers/_Global/_.cs** - included in the package if the **Export files -> Export global folders** option is enabled for the export.

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

**Views:**

- **Views/_/_/.cshtml** - included in the package if the **Export files -> Export site folders** option is enabled for the export.
- **Views/_Global/_/__.cshtml** - included in the package if the **Export files -> Export global folders** option is enabled for the export.

> **Info:** **Note**: The standard view location **Views//.cshtml** is not included in the export package.

**Models:**

Custom model files (and files in other locations in the CMSApp\_MVC project) are not exported along with sites automatically. You either need to:

- Transfer the files manually\
  OR
- Add the files into the _****_ folder under the **CMSApp** project (this folder is automatically exported along with sites)

**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](http://blogs.msdn.com/b/webdev/archive/2013/10/17/attribute-routing-in-asp-net-mvc-5.aspx) in your controller files (MVC 5 only).

### Importing MVC code files

When you [import](https://docs.kentico.com/k8/deploying-websites/exporting-and-importing-sites/importing-a-site-or-objects.md) 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 documents directly

> **Info:** 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 documents directly in the Kentico administration interface.

1. Open the **Pages** application.
2. Select the document in the content tree.
3. Open the **Properties -> URLs** tab.
4. In the **Document URL path** section, set the **Path type** to **MVC**.
5. Enter a path or route into the **Path or pattern** field.

   > **Info:** 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 document 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._ 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 document'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](https://docs.kentico.com/k8/configuring-kentico/optimizing-website-performance/configuring-caching/caching-page-output.md) for pages.

#### Handling MVC patterns through document aliases

You can define any number of [document aliases](https://docs.kentico.com/k8/configuring-kentico/configuring-page-urls/setting-document-aliases.md) for documents, 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).