Integration into an Existing Project Using Wizards
- 16 minutes to read
This topic explains how to incorporate DevExpress Extensions for ASP.NET MVC into an existing ASP.NET MVC application using wizards. If you wish to create a new ASP.NET MVC application and use a DevExpress ASP.NET MVC extension within it, create a new application using specially designed DevExpress project templates.
You can use the DevExpress Project Wizard or the Insert Extension Wizard to simplify the integration of DevExpress ASP.NET MVC extensions into your project.
This document consists of two step-by-step tutorials.
- Integrating DevExpress ASP.NET MVC Extensions into an Existing Project using the Project Wizard
- Integrating DevExpress ASP.NET MVC Extensions into an Existing Project using the Insert Extension Wizard
Integrating DevExpress ASP.NET MVC Extensions into an Existing Project using the Project Wizard
To integrate DevExpress ASP.NET MVC extensions into an existing project using the Project Wizard, perform the following steps.
Open your ASP.NET MVC project. In the main menu of Visual Studio, click the DEVEXPRESS submenu and select ASP.NET Controls v23.2 | Run Wizard to Update Project….
This invokes the DevExpress ASP.NET MVC Project Wizard. This wizard allows you to customize the settings specific to DevExpress ASP.NET MVC Extensions (e.g., you can select the required theme or select the localization). After the required settings have been specified, click Update Project.
The wizard adds the required assemblies to the project, and makes all necessary changes to the Web.config file.
Attach the required JavaScript files.
All the DevExpress ASP.NET MVC extensions require attaching the jQuery library and some of them also require attaching additional libraries.
Important
If you attach the jQuery scripts manually, the jQuery script must be attached before attaching the DevExpress client script files, in order to avoid possible errors.
If you bundled your JavaScript files, the bundle with jQuery library must be attached before attaching the DevExpress client script files. By default, the standard ASP.NET MVC 4 and 5 projects locate reference to the JavaScript bundle at the bottom of the “_Layout.cshtml” page.
For an ASP.NET MVC extension to work properly, you either need to manually add the required external libraries, or enable the control to load them automatically by adding the following references to the “resources” section in the Web.config file.
<devExpress> <!-- ... --> <resources> <add type="ThirdParty" /> <add type="DevExtreme" /> </resources> </devExpress>These settings specify the following resources.
- “ThirdParty“ - adds references to external libraries required by a specific control. For a complete list of these references, see External Client Libraries.
- “DevExtreme“ - adds a reference to the DevExtreme package. For a complete list of these references, see the 3rd-Party Frameworks Integration API document.
The above resources are automatically added to the Web.config file on adding a DevExpress web control to a new application created using the DevExpress template gallery. In this case, all necessary client-side libraries are automatically passed to the client.
When manually adding such controls to a web page, you need to explicitly specify which of the client libraries must be deployed on the client by the control. By default, on adding such a DevExpress control, it loads only the DevExtreme library to a web page without loading third-party libraries.
To avoid automatic loading of any libraries by a control (e.g., when such libraries are already referenced on the web page), declare an empty “resources” section and manually attach DevExtreme resources and the required third-party libraries (such as jQuery and Globalize) to the web page.
<resources> </resources>Deleting the DevExpress “resources” section from the Web.config file will enable the default behavior (with automatic loading of only DevExtreme, without adding third-party libraries).
On adding such DevExpress controls to a project, the “resources” section should automatically become registered in the application’s Web.config file.
<configuration> <configSections> <sectionGroup name="devExpress"> <!-- ... --> <section name="resources" type="DevExpress.Web.ResourcesConfigurationSection, DevExpress.Web.v23.2, Version=23.2.5.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" requirePermission="false" /> </sectionGroup> </configSections> <!-- ... --> </configuration>When updating your project version using the Project Converter, you are required to manually register this section in the Web.config file.
To attach the required DevExpress JavaScript files, use the ExtensionsFactory.GetScripts (or ExtensionsFactory.RenderScripts, if your project uses the ASPX view engine) method within the View page’s HEAD or BODY tag. Typically, scripts can be attached to all Views in a central location within the layout View.
If the “resources” section of an application’s Web.config file contains a reference to the “ThirdParty” and/or “DevExtreme” libraries, the GetScripts method will attach the corresponding libraries and additional resources to the View.
The jQuery scripts are typically located within the Scripts folder after creating a new ASP.NET MVC Web Application project.
<head> ... <!-- Attach the jQuery script if the "resources" section of an application's Web.config file contains a reference to the "ThirdParty" libraries. --> <script src="@Url.Content("~/Scripts/jquery-3.5.1.min.js")" type="text/javascript"></script> <!-- The DevExpress ASP.NET MVC Extensions' scripts --> @Html.DevExpress().GetScripts( new Script { ExtensionSuite = ExtensionSuite.NavigationAndLayout }, new Script { ExtensionSuite = ExtensionSuite.HtmlEditor }, new Script { ExtensionSuite = ExtensionSuite.GridView }, ... ) ... </head>Attach the required style sheets.
To attach the required style sheets, use the ExtensionsFactory.GetStyleSheets extension method within a View page’s HEAD (recommended) or BODY tag. If you are planning to use DevExpress ASP.NET MVC extensions within multiple views of your project, you can attach style sheets to all Views in a central location such as the “_Layout.cshtml” shared View page (before the @RenderBody() expression). If you plan to use DevExpress Extensions within a single View, it is recommended that you attach the style sheets to the required View.
The code sample below demonstrates how to attach style sheets for the specified extension set(s).
View (or layout View) Code (Razor):
<head> ... @Html.DevExpress().GetStyleSheets( new StyleSheet { ExtensionSuite = ExtensionSuite.NavigationAndLayout }, new StyleSheet { ExtensionSuite = ExtensionSuite.Diagram }, new StyleSheet { ExtensionSuite = ExtensionSuite.Gantt }, new StyleSheet { ExtensionSuite = ExtensionSuite.Editors }, new StyleSheet { ExtensionSuite = ExtensionSuite.HtmlEditor }, new StyleSheet { ExtensionSuite = ExtensionSuite.GridView }, new StyleSheet { ExtensionSuite = ExtensionSuite.PivotGrid }, new StyleSheet { ExtensionSuite = ExtensionSuite.Chart }, new StyleSheet { ExtensionSuite = ExtensionSuite.Report }, new StyleSheet { ExtensionSuite = ExtensionSuite.Scheduler }, new StyleSheet { ExtensionSuite = ExtensionSuite.TreeList }, new StyleSheet { ExtensionSuite = ExtensionSuite.Spreadsheet }, new StyleSheet { ExtensionSuite = ExtensionSuite.RichEdit }, new StyleSheet { ExtensionSuite = ExtensionSuite.SpellChecker } ) ... </head>Note
If you have not selected the required theme within the DevExpress Project Wizard, the Default theme will be applied. To select the required theme or change any other DevExpress extension-specific settings, run the wizard again and define these settings.
Different options for attaching and applying DevExpress themes are described in the Applying Themes section of the documentation.
You should include the ignore route statements with the following patterns to prevent requests from being passed to a controller:
{resource}.axd/{*pathInfo}- for the Web resource files (e.g., scripts, styles);{resource}.ashx/{*pathInfo}- for the ASHX handler, which processes the file upload functionality of DevExpress ASP.NET MVC extensions (e.g., UploadControl, FileManager, HtmlEditor).
In the registered route collection, add the required ignore route statements above the other route definitions:
// ... public static void RegisterRoutes(RouteCollection routes) { // Ignore route statements. routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); routes.IgnoreRoute("{resource}.ashx/{*pathInfo}"); // Route definitions. // ... } // ...Tip
If you use the ASP.NET MVC v.3 framework, you can find the route definition in the ~/Global.asax.cs file. If you use the ASP.NET MVC v.4 or v.5 framework, the route definition is placed to the ~/App_Start/RouteConfig.cs file by default.
Override the Default Model Binder.
When DevExpress editors are bound to data model fields (by using Bind(dataObject, propertyName) methods or using strongly typed helpers), the DevExpressEditorsBinder model binder must be used instead of the default model binder to correctly transfer values from DevExpress editors back to corresponding data model fields.
You can specify DevExpressEditorsBinder as a model binder in the following manners.
Decorating the Parameter of Action Method
You can declare DevExpressEditorsBinder as a parameter attribute on an action method: ([ModelBinder(typeof(DevExpressEditorsBinder))])
Controller:
[HttpPost] public ActionResult ModelBinding([ModelBinder(typeof(DevExpressEditorsBinder))] MyModelData myModel) { ... }Overriding the Default Model Binder
You can assign DevExpressEditorsBinder to the ModelBinders.Binders.DefaultBinder property to replace the global default model binder.
Global.asax:
protected void Application_Start(){ ... ModelBinders.Binders.DefaultBinder = new DevExpress.Web.Mvc.DevExpressEditorsBinder(); }
Note
DevExpressEditorsBinder is automatically defined as a default model binder within projects created with the help of DevExpress MVC project templates.
- If you create an ASP.NET MVC project using the standard ASP.NET MVC Web Application template provided by Visual Studio, the project’s Content folder contains the automatically generated Site.css file. Specific type selectors that are defined in this file and relate directly to HTML element types (such as links, input elements, tables and table cells) may adversely affect the appearance of DevExpress MVC extensions. To fix this problem, you are required to clear the style settings defined in the element type selectors. This requirement also applies to your custom CSS files and rules, if any.
It is recommended that you use the following document type for Views, to ensure that DevExpress ASP.NET MVC extensions work properly.
<!DOCTYPE html>Check and correct (if necessary) the document type of all Views containing DevExpress ASP.NET MVC extensions and/or the document type of layout pages used by Views.
You can now use DevExpress extensions within your ASP.NET MVC application.
Integrating DevExpress ASP.NET MVC Extensions into an Existing Project using the Insert Extension Wizard
To integrate DevExpress ASP.NET MVC extensions into an existing project using the Insert Extension Wizard, perform the following steps.
Open your ASP.NET MVC project. Go to the View in which you wish to insert an extension. Focus the line of code where you will insert the extension. Right-click and select the Insert DevExpress MVC Extension v23.2… item in the context menu.
This invokes the Insert Extension Wizard. This wizard allows you to select the required extension, define its settings and add the extension to the View. After specifying the required extension settings, click Insert.
The wizard automatically generates the code for a DevExpress extension, which is selected and customized via the wizard. The generated code is inserted into the View at the cursor position. After this step, the wizard adds the required assemblies to the project, and makes all necessary changes to the Web.config file.
Attach the required JavaScript files.
All the DevExpress ASP.NET MVC extensions require attaching the jQuery library and some of them also require attaching additional libraries.
Important
If you attach the jQuery scripts manually, the jQuery script must be attached before attaching the DevExpress client script files, in order to avoid possible errors.
If you bundled your JavaScript files, the bundle with jQuery library must be attached before attaching the DevExpress client script files. By default, the standard ASP.NET MVC 4 and 5 projects locate reference to the JavaScript bundle at the bottom of the “_Layout.cshtml” page.
For an ASP.NET MVC extension to work properly, you either need to manually add the required external libraries, or enable the control to load them automatically by adding the following references to the “resources” section in the Web.config file.
<devExpress> <!-- ... --> <resources> <add type="ThirdParty" /> <add type="DevExtreme" /> </resources> </devExpress>These settings specify the following resources.
- “ThirdParty“ - adds references to external libraries required by a specific control. For a complete list of these references, see External Client Libraries.
- “DevExtreme“ - adds a reference to the DevExtreme package. For a complete list of these references, see the 3rd-Party Frameworks Integration API document.
The above resources are automatically added to the Web.config file on adding a DevExpress web control to a new application created using the DevExpress template gallery. In this case, all necessary client-side libraries are automatically passed to the client.
When manually adding such controls to a web page, you need to explicitly specify which of the client libraries must be deployed on the client by the control. By default, on adding such a DevExpress control, it loads only the DevExtreme library to a web page without loading third-party libraries.
To avoid automatic loading of any libraries by a control (e.g., when such libraries are already referenced on the web page), declare an empty “resources” section and manually attach DevExtreme resources and the required third-party libraries (such as jQuery and Globalize) to the web page.
<resources> </resources>Deleting the DevExpress “resources” section from the Web.config file will enable the default behavior (with automatic loading of only DevExtreme, without adding third-party libraries).
On adding such DevExpress controls to a project, the “resources” section should automatically become registered in the application’s Web.config file.
<configuration> <configSections> <sectionGroup name="devExpress"> <!-- ... --> <section name="resources" type="DevExpress.Web.ResourcesConfigurationSection, DevExpress.Web.v23.2, Version=23.2.5.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" requirePermission="false" /> </sectionGroup> </configSections> <!-- ... --> </configuration>When updating your project version using the Project Converter, you are required to manually register this section in the Web.config file.
To attach the required DevExpress JavaScript files, use the ExtensionsFactory.GetScripts (or ExtensionsFactory.RenderScripts, if your project uses the ASPX view engine) method within the View page’s HEAD or BODY tag. Typically, scripts can be attached to all Views in a central location within the layout View.
If the “resources” section of an application’s Web.config file contains a reference to the “ThirdParty” and/or “DevExtreme” libraries, the GetScripts method will attach the corresponding libraries and additional resources to the View.
The jQuery scripts are typically located within the Scripts folder after creating a new ASP.NET MVC Web Application project.
<head> ... <!-- Attach the jQuery script if the "resources" section of an application's Web.config file contains a reference to the "ThirdParty" libraries. --> <script src="@Url.Content("~/Scripts/jquery-3.5.1.min.js")" type="text/javascript"></script> <!-- The DevExpress ASP.NET MVC Extensions' scripts --> @Html.DevExpress().GetScripts( new Script { ExtensionSuite = ExtensionSuite.NavigationAndLayout }, new Script { ExtensionSuite = ExtensionSuite.HtmlEditor }, new Script { ExtensionSuite = ExtensionSuite.GridView }, ... ) ... </head>Attach the required style sheets.
To attach the required style sheets, use the ExtensionsFactory.GetStyleSheets extension method within the View page’s HEAD (recommended) or BODY tag. If you are planning to use DevExpress ASP.NET MVC extensions within multiple views of your project, you can attach style sheets to all Views in a central location such as the “_Layout.cshtml” shared View page (before the @RenderBody() expression). If you plan to use DevExpress extensions within a single View only, it is recommended that you attach the style sheets to the required View.
The code sample below demonstrates how to attach style sheets for the specified extension set(s).
View (or layout View) Code (Razor):
<head> ... @Html.DevExpress().GetStyleSheets( new StyleSheet { ExtensionSuite = ExtensionSuite.NavigationAndLayout }, new StyleSheet { ExtensionSuite = ExtensionSuite.Diagram }, new StyleSheet { ExtensionSuite = ExtensionSuite.Gantt }, new StyleSheet { ExtensionSuite = ExtensionSuite.Editors }, new StyleSheet { ExtensionSuite = ExtensionSuite.HtmlEditor }, new StyleSheet { ExtensionSuite = ExtensionSuite.GridView }, new StyleSheet { ExtensionSuite = ExtensionSuite.PivotGrid }, new StyleSheet { ExtensionSuite = ExtensionSuite.Chart }, new StyleSheet { ExtensionSuite = ExtensionSuite.Report }, new StyleSheet { ExtensionSuite = ExtensionSuite.Scheduler }, new StyleSheet { ExtensionSuite = ExtensionSuite.TreeList }, new StyleSheet { ExtensionSuite = ExtensionSuite.Spreadsheet }, new StyleSheet { ExtensionSuite = ExtensionSuite.RichEdit }, new StyleSheet { ExtensionSuite = ExtensionSuite.SpellChecker } ) ... </head>After attaching the style sheets, you should define the theme that will be applied to the DevExpress ASP.NET MVC extensions using one of the following approaches.
- Assign the theme name to the static DevExpressHelper.Theme property. This programmatically applies the theme to all DevExpress extensions within an application.
- Assign the theme name to the DevExpress Theme Name option in the Web.config file. This declaratively applies the theme to all DevExpress extensions within an application.
The following code demonstrates how the “Aqua” theme can be globally applied to all DevExpress ASP.NET MVC extensions within an application using the static DevExpressHelper.Theme property.
Global.asax.cs Code:
using DevExpress.Web.Mvc; ... protected void Application_PreRequestHandlerExecute(object sender, EventArgs e) { DevExpressHelper.Theme = "Aqua"; } ...Different options for attaching and applying DevExpress themes are described in the Applying Themes section.
You should include the ignore route statements with the following patterns to prevent requests from being passed to a controller:
{resource}.axd/{*pathInfo}- for the Web resource files (e.g., scripts, styles);{resource}.ashx/{*pathInfo}- for the ASHX handler, which processes the file upload functionality of DevExpress ASP.NET MVC extensions (e.g., UploadControl, FileManager, HtmlEditor).
In the registered route collection, add the required ignore route statements above the other route definitions:
// ... public static void RegisterRoutes(RouteCollection routes) { // Ignore route statements. routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); routes.IgnoreRoute("{resource}.ashx/{*pathInfo}"); // Route definitions. // ... } // ...Tip
If you use the ASP.NET MVC v.3 framework, you can find the route definition in the ~/Global.asax.cs file. If you use the ASP.NET MVC v.4 or v.5 framework, the route definition is placed to the ~/App_Start/RouteConfig.cs file by default.
Override the Default Model Binder.
When DevExpress editors are bound to data model fields (by using Bind(dataObject, propertyName) methods or using strongly typed helpers), the DevExpressEditorsBinder model binder must be used instead of the default model binder to correctly transfer values from DevExpress editors back to corresponding data model fields.
You can specify DevExpressEditorsBinder as a model binder in the following manners.
Decorating the Parameter of Action Method
You can declare DevExpressEditorsBinder as a parameter attribute on an action method: ([ModelBinder(typeof(DevExpressEditorsBinder))])
Controller:
[HttpPost] public ActionResult ModelBinding([ModelBinder(typeof(DevExpressEditorsBinder))] MyModelData myModel) { ... }Overriding the Default Model Binder
You can assign DevExpressEditorsBinder to the ModelBinders.Binders.DefaultBinder property to replace the global default model binder.
Global.asax:
protected void Application_Start(){ ... ModelBinders.Binders.DefaultBinder = new DevExpress.Web.Mvc.DevExpressEditorsBinder(); }
Note
DevExpressEditorsBinder is automatically defined as a default model binder within projects created with the help of DevExpress MVC project templates.
- If you create an ASP.NET MVC project using the standard ASP.NET MVC Web Application template provided by Visual Studio, the project’s Content folder contains the automatically generated Site.css file. Specific type selectors that are defined in this file and relate directly to HTML element types (such as links, input elements, tables and table cells) may adversely affect the appearance of DevExpress MVC extensions. To fix this problem, you are required to clear the style settings defined in the element type selectors. This requirement also applies to your custom CSS files and rules, if any.
It is recommended that you use the following document type for Views to ensure that DevExpress ASP.NET MVC extensions will work properly.
<!DOCTYPE html>Be sure to check and correct (if necessary) the document type of all Views containing DevExpress ASP.NET MVC extensions and/or the document type of layout pages used by Views.
The required extension has now been inserted into the View, and you can use all other DevExpress extensions within your ASP.NET MVC application.
Refer to the Get Started topic to learn about the fundamentals of DevExpress ASP.NET MVC extensions.