Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Collapse]ASP.NET Controls and MVC Extensions
 [Expand]Prerequisites
 [Expand]What's Installed
 [Expand]Common Concepts
 [Expand]ASP.NET WebForms Controls
 [Collapse]ASP.NET MVC Extensions
  [Expand]Product Information
  [Collapse]Getting Started
   [Collapse]Integration into an ASP.NET MVC Project
     Manual Integration into an Existing Project
     Integration into an Existing Project Using Wizards
    How It Works
  [Expand]Common Concepts
  [Expand]Grid View
  [Expand]Card View
  [Expand]Vertical Grid
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]HTML Editor
  [Expand]Image and Data Browsing
  [Expand]Docking and Popups
  [Expand]Navigation and Layout Extensions
  [Expand]File Management
  [Expand]Multi-Use Site Extensions
  [Expand]Charts
  [Expand]Pivot Grid
  [Expand]Scheduler
  [Expand]Tree List
  [Expand]Data Editor Extensions
  [Expand]Report Extensions
  [Expand]SpellChecker
 [Expand]Localization
 [Expand]Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Manual Integration into an Existing Project

This topic explains how to manually incorporate DevExpress Extensions for ASP.NET MVC into ASP.NET MVC applications. Note that all actions listed below are performed automatically when creating an MVC application, using specially designed DevExpress project templates.

To use DevExpress Extensions for ASP.NET MVC in a project, perform the following steps within your application.

Note

The version numbers mentioned in this document (17.2 or 17.2.1.0) and the public key token (B88D1754D700E49A) may differ, depending on the product version you purchased.

Expanded Step 1. Reference the Required Assemblies

References to the following assembly files should be added to the ASP.NET MVC application (refer to the Deployment - MVC Extensions topic to learn more).

  • DevExpress.Charts.v17.2.Core
  • DevExpress.Dashboard.v17.2.Core
  • DevExpress.Dashboard.v17.2.Web
  • DevExpress.Dashboard.v17.2.Web.Mvc
  • DevExpress.Data.v17.2
  • DevExpress.DataAccess.v17.2
  • DevExpress.Office.v17.2.Core.dll
  • DevExpress.PivotGrid.v17.2.Core
  • DevExpress.Printing.v17.2.Core
  • DevExpress.RichEdit.v17.2.Core.dll
  • DevExpress.SpellChecker.v17.2.Core
  • DevExpress.Spreadsheet.v17.2.Core
  • DevExpress.Utils.v17.2
  • DevExpress.Web.ASPxGauges.v17.2
  • DevExpress.Web.ASPxHtmlEditor.v17.2
  • DevExpress.Web.ASPxPivotGrid.v17.2
  • DevExpress.Web.ASPxRichEdit.v17.2
  • DevExpress.Web.ASPxScheduler.v17.2
  • DevExpress.Web.ASPxSpellChecker.v17.2
  • DevExpress.Web.ASPxSpreadsheet.v17.2
  • DevExpress.Web.ASPxThemes.v17.2
  • DevExpress.Web.ASPxTreeList.v17.2
  • DevExpress.Web.Mvc.v17.2 (or DevExpress.Web.Mvc5.v17.2 if using ASP.NET MVC 5)
  • DevExpress.Web.v17.2
  • DevExpress.Xpo.v17.2
  • DevExpress.XtraCharts.v17.2
  • DevExpress.XtraCharts.v17.2.Web
  • DevExpress.XtraGauges.v17.2.Core
  • DevExpress.XtraGauges.v17.2.Presets
  • DevExpress.XtraPivotGrid.v17.2
  • DevExpress.XtraReports.v17.2
  • DevExpress.XtraReports.v17.2.Web
  • DevExpress.XtraScheduler.v17.2.Core

Typically, after installation, the required DevExpress assemblies have already been registered in the GAC, so you can open the Reference Manager dialog (for instance, using the PROJECT | Add Reference... menu item), and select these assemblies within the dialog's .NET tab.

Depending on your development and deployment strategy, you can then set the CopyLocal property of the referenced DevExpress assemblies to True, or add the following lines to the 'configuration > system.web > compilation > assemblies' section of the application's Web.config file.

Web.config:

Note

When using the ASP.NET MVC 5 framework, you should add the DevExpress.Web.Mvc5.v17.2 assembly instead of the DevExpress.Web.Mvc.v17.2 assembly, as shown in the code sample below.

Expanded Step 2. Register DevExpress HTTP Handlers within the Application's Web.config File

Registering the service ASPxHttpHandlerModule in two sections of the application's Web.config file ('configuration > system.web > httpModules' and 'configuration > system.webServer > modules') is required.

Web.config:

If the UploadControl's progress panel functionality is utilized in an application, registering the ASPxUploadProgressHttpHandler (within the Web.config's 'configuration > system.web > httpHandlers' and 'configuration > system.webServer > handlers' sections) is also required.

Web.config:

Expanded Step 3. Register the Required Namespaces within the ~/Views/Web.config File

Razor uses a specific configuration section to globally define namespace imports for its views. This is the <system.web.webPages.razor> section, which is located within the Views folder's Web.config file. This section should contain the required DevExpress namespaces to make the DevExpress Extensions available for use within web project pages. Note that if you create a web project using a DevExpress project template, all required information is automatically added to the configuration files. Otherwise, you need to modify the configuration section manually.

Web.config:

Note

If using the ASPX view engine, register these namespaces within the 'configuration > system.web > pages > namespaces' section of the application's Web.config file.

As an alternative, you can manually insert @using directives into view pages to import the required namespaces.

View:

Access and customization of DevExpress MVC Extensions is now permitted within the application's view pages, including the use of IntelliSense. However, DevExpress Extensions are not yet fully functional at this stage, because they also require script and style files to be attached in order to work properly. By design, the required script and style sheet files are not referenced automatically for MVC extensions, so you should attach them manually, as described in the steps below.

Expanded Step 4. Register the DevExpress Configuration Section in the Web.config File

Different aspects of DevExpress functionality can be centrally controlled through configuration options provided by a specially designed DevExpress configuration section. Register this section in the application's Web.config file using the following code.

Web.config:

Note

In order to properly register the DevExpress ASP.NET MVC Extensions, it is recommended that you rebuild the project after this step.

Expanded Step 5. Attach the Required JavaScript Files

Attaching External Libraries

All the DevExpress ASP.NET MVC extensions require attaching the jQuery library and some of them also require attaching additional libraries.

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.

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 Embedding Third-Party Libraries.

  • "DevExtreme" - adds a reference to the DevExtreme package. For a complete list of these references, see the "Integration with 3rd-Party Libraries and Frameworks" section of the Introduction to DevExtreme 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.

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.

When updating your project version using the Project Converter, you are required to manually register this section in the Web.config file.


Attaching the DevExpress specific scripts

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.


Example

The code sample below demonstrates how to attach the jQuery library and the DevExpress specific scripts to your project.

View (or layout View) Code (Razor):

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 the jQuery library must be attached before attaching the DevExpress client script files.

Expanded Step 6. 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. Typically, style sheets can be attached to all Views in a central location within the layout View (before the @RenderBody() expression).

The code sample below demonstrates how to attach style sheets for the specified extension set(s).

View (or layout View) Code (Razor):

After attaching the style sheets, 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 DevExpressHelper.Theme static 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 DevExpressHelper.Theme static property.

Global.asax.cs Code:

Different approaches to attaching and applying DevExpress themes are described in the Applying Themes section of the documentation.

Expanded Step 7. Add Ignore Route Statements

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.

Tip

If you use the ASP.NET MVC 3 framework, you can find the route definition in the ~/Global.asax.cs file. If you use the ASP.NET MVC 4 or 5 framework, the route definition is placed in the ~/App_Start/RouteConfig.cs file by default.

Expanded Step 8. 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:
  • Overriding the Default Model Binder

    You can assign DevExpressEditorsBinder to the ModelBinders.Binders.DefaultBinder property to replace the global default model binder.

    Global.asax:
Note

Starting with v2012 vol 1, DevExpressEditorsBinder is automatically defined as a default model binder within projects created with the help of DevExpress MVC project templates.

Expanded Step 9. Remove CSS Settings Applied using Element Type Selectors

If you create an 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 affect the appearance of DevExpress MVC extensions incorrectly. To fix this problem, it is required that you clear the style settings defined in the element type selectors. This requirement also applies to your custom CSS files and rules, if any.

Expanded Step 10. Check the Document Type of View Pages

It is recommended that you use the following document type for Views to ensure that DevExpress MVC extensions will work properly.

Check and correct (if necessary) the document type for all Views containing DevExpress MVC extensions and/or the document type of layout pages used by Views.

Expanded Step 11. Add Extension Code

You can now use DevExpress Extensions within your ASP.NET MVC application. The NavBar extension will be used as an example. Add the following code to the Index View page of the project. (In this example, the project was initially created using the ASP.NET MVC 5 Web Application template.)

View code (Razor):

After building and running the application, the Index View page will appear as follows.

Refer to the How It Works topic to learn about the fundamentals of DevExpress ASP.NET MVC Extensions.

Expanded See Also

How would you rate this topic?​​​​​​​