Customizing MVC projects

When building sites using the MVC development model, the system’s functionality can be modified or extended via the standard customization API and endpoints described throughout the documentation (like with Portal Engine sites).

However, keep in mind that the MVC live site application and Kentico administration application each have their own separate code base and project files. Customization of the administration application does not automatically apply to the MVC application and vice versa. For every customization, you need to consider which applications should be affected and deploy your custom code accordingly:

• Both applications – in many cases, customizations need to cover both applications to work consistently. Typical examples are customizations of e-commerce functionality or user-related actions, which can occur both on the live site and through the administration interface. See Deploying custom code to both applications.
• Administration-only – for customizations that modify or extend parts of the administration interface or only affect functionality triggered in the administration. For example, extenders of UI elements or custom scheduled tasks.
• MVC-only – for customizations of actions that only occur on the live site. For example, code that adjusts the contact recognition logic.

Deploying custom code to both applications

We recommend using the following approach to deploy shared custom code to both the MVC and Kentico administration applications:

1. Create a Class Library project in one of the applications (under either the MVC solution or the Kentico administration WebApp.sln solution).

2. Install the Kentico.Libraries NuGet package into the project. The version must match your MVC project’s Kentico.AspNet.Mvc package and the exact hotfix version of your Kentico administration project.

3. Create classes with the required custom code in the project.

4. Add the same project to the other application’s solution.

   Important: When working with the Kentico administration solution, make sure that you do NOT install the Kentico.Libraries package into the CMSApp project. The project already references Kentico DLLs in the solution’s Lib folder.

Having a project in both solutions ensures that changes are shared between the projects during development.

If you also have customizations intended for only one of the applications, we recommend creating a separate Class Library project in each solution. In this scenario, you can share individual code files between the projects by adding them as links in Visual Studio.

Example

The following example demonstrates how to prepare a customization that automatically assigns new users to a default role. In MVC scenarios, users can be created both in the administration interface and on the live site (registration of visitors), so the customization is deployed to both applications to ensure that it works consistently.

Start by adding the customization to the MVC live site project:

1. Open your MVC site’s solution in Visual Studio.

2. Create a new Class Library project. For example, name the project Custom.

3. Add the Kentico API libraries to the project:

   1. Right-click the solution in the Solution Explorer and select Manage NuGet Packages for Solution.
   2. Select the Kentico.Libraries package.
   3. Install the package into the Custom project (the version must match your MVC project’s Kentico.AspNet.Mvc package and the exact hotfix version of your Kentico administration project).

4. Reference the Custom project from your MVC web project.

5. Edit the Custom project’s AssemblyInfo.cs file (in the Properties folder) and add the AssemblyDiscoverable assembly attribute:

   Copy

   
   
   
    using CMS;
   
    [assembly:AssemblyDiscoverable]
   
   
    

6. Create a new class under the custom project, for example named CustomUserModule (the example uses an event handler to extend the user functionality):

   Copy

   
   
   
    using CMS;
    using CMS.DataEngine;
    using CMS.Membership;
    using CMS.SiteProvider;
   
    // Registers the custom module into the system
    [assembly: RegisterModule(typeof(Custom.CustomUserModule))]
   
    namespace Custom
    {
        public class CustomUserModule : Module
        {
            // Module class constructor, the system registers the module under the name "CustomUsers"
            public CustomUserModule()
                : base("CustomUsers")
            {
            }
   
            // Contains initialization code that is executed when the application starts
            protected override void OnInit()
            {
                base.OnInit();
   
                // Assigns a handler to the Insert.After event of user objects
                UserInfo.TYPEINFO.Events.Insert.After += User_InsertAfterEventHandler;
            }
   
            // Handler method that runs when a new user object is created in the system
            private void User_InsertAfterEventHandler(object sender, ObjectEventArgs e)
            {
                if (e.Object != null)
                {
                    // Gets an info object representing the new user
                    UserInfo user = (UserInfo)e.Object;
   
                    // Gets the "DefaultRole" role
                    RoleInfo role = RoleInfoProvider.GetRoleInfo("DefaultRole", SiteContext.CurrentSiteName);
   
                    if (role != null)
                    {
                        // Assigns the role to the user
                        UserInfoProvider.AddUserToRole(user.UserName, role.RoleName, SiteContext.CurrentSiteName);
                    }
                }
            }
        }
    }
   
   
    

7. Save all changes and Rebuild the solution.

Now add the customization to your Kentico administration project:

1. Open your Kentico administration solution in Visual Studio (using the WebApp.sln file).
2. Right-click the solution in the Solution Explorer and select Add -> Existing Project.
3. Navigate to the Custom folder in the web project and select the Custom.csproj file.
4. Click Open.
5. Reference the Custom project from the Kentico web project (CMSApp).
6. Save all changes and Rebuild the solution.

The customization is now applied to both applications. The shared custom project allows you to keep changes in the custom code synchronized between the applications during development. When a new user registers on the live site or is created manually in the administration interface, they are automatically assigned to the DefaultRole role (you need to create a role with this code name).