Configure a non Visual Studio Project

Jul 09, 2021
6 minutes to read

You can develop your ASP.NET Core application without Visual Studio, for example, on MacOS, Linux, using Visual Studio Code or CLI tools.

To configure your project to use DevExtreme-based controls, follow the steps below.

Install Server-Side Packages

Open the console and navigate to your project’s directory:
- Console
```
cd MyProject
```

Add one of the following NuGet package sources:

DevExpress NuGet Feed

Obtain your NuGet feed URL and run the following command. If nuget is not recognized, follow these instructions to install the NuGet CLI.
- Console
```
nuget sources Add -Name "DevExpress NuGet Feed" -Source "https://nuget.devexpress.com/{authorization key}/api"
```
Local Source

DevExtreme NuGet packages for ASP.NET Core MVC are included in the installer for Windows. Add their path to the package sources by running the following command. If nuget is not recognized, follow these instructions to install the NuGet CLI.
- Console
```
nuget sources Add -Name "DevExtreme ASP.NET MVC Controls" -Source "%ProgramFiles(x86)%\DevExpress 21.1\DevExtreme\System\DevExtreme\Bin\AspNetCore"
```

In both cases, you can change the %AppData%\NuGet\NuGet.config file as follows instead of running commands in the NuGet CLI:

 <configuration>
     <packageSources>
         ...
         <add key="DevExpress NuGet Feed"
              value="https://nuget.devexpress.com/{authorization key}/api" />
         <!-- or -->
         <add key="DevExtreme ASP.NET MVC Controls"
              value="%ProgramFiles(x86)%\DevExpress 21.1\DevExtreme\System\DevExtreme\Bin\AspNetCore" />
     </packageSources>
 </configuration>

Install the DevExtreme.AspNet.Data and DevExtreme.AspNet.Core packages for your project:

Console

dotnet add package DevExtreme.AspNet.Data
dotnet add package -v 21.1.12 DevExtreme.AspNet.Core

Add Client-Side Resources

The instructions below describe how to use npm and LibMan CLI to add client-side resources (DevExtreme scripts and CSS files) to a project.

Note

You can also use Webpack or Gulp to add client-side resources.

Ensure that Node.js is installed.
Open the console from the project directory and run the following commands to install DevExtreme and DevExtreme AspNet Data:
- Console
```
npm init -y
npm i devextreme@21.1 devextreme-aspnet-data
```
The last command adds DevExtreme files to the <project_name>/node_modules/devextreme and <project_name>/node_modules/devextreme-aspnet-data directories. You will refer to these files in step 5.

Note
If your project is under source control, add the node_modules directory to the project’s ignore list. For example, if you use git, add this directory to your .gitignore file.

Install the LibMan CLI:

Console

dotnet tool install -g Microsoft.Web.LibraryManager.Cli

Run the following command to initialize LibMan in your project:
- Console
```
libman init
```
A libman.json file is added to the project root:
- libman.json
```
{
    "version": "1.0",
    "defaultProvider": "cdnjs",
    "libraries": []
}
```
Note
MacOS, Linux: If the libman command is unavailable, specify the full path to LibMan: ~/.dotnet/tools/libman init. Refer to this issue for more information.

Add library files listed below to the libman.json file. You can modify this file or use the libman install command.

Directories and Files	What Provider to Use	Notes
jquery.js from the jQuery library	cdnjs	Add this file if it is not included in your project.
cldr.js	cdnjs
Globalize	cdnjs
JSZip	cdnjs	Required for client-side export.
node_modules/devextreme/dist/js/	filesystem
node_modules/devextreme/dist/js/localization/	filesystem	Required if you set up localization.
node_modules/devextreme/dist/js/vectormap-data/	filesystem	Required if you use a VectorMap control.
CSS themes you want to use, for example: - node_modules/devextreme/dist/css/dx.light.css - node_modules/devextreme/dist/css/dx.material.blue.light.css	filesystem
node_modules/devextreme/dist/css/icons/	filesystem
node_modules/devextreme/dist/css/fonts/	filesystem	Required if you use one of the Material Design Themes.
node_modules/devextreme-aspnet-data/js/dx.aspnet.data.js	filesystem

The libman.json file should look like this:

libman.json

{
    "version": "1.0",
    "defaultProvider": "cdnjs",
    "libraries": [
        {
            // add this file if your project does not include it yet
            "library": "jquery@3.5.1",
            "provider": "cdnjs",
            "destination": "wwwroot/js/devextreme",
            "files": [
                "jquery.js"
            ]
        },
        {
            "library": "cldrjs@0.5.1",
            "provider": "cdnjs",
            "destination": "wwwroot/js/devextreme/"
        },
        {
            "library": "globalize@1.4.2",
            "provider": "cdnjs",
            "destination": "wwwroot/js/devextreme/"
        },
        {
            // required for client-side export
            "library": "jszip@3.2.1",
            "provider": "cdnjs",
            "destination": "wwwroot/js/devextreme/"
        },
        {
            "library": "node_modules/devextreme/dist/js/",
            "provider": "filesystem",
            "destination": "wwwroot/js/devextreme/"
        },
        {
            // required if you set up localization
            "library": "node_modules/devextreme/dist/js/localization/",
            "provider": "filesystem",
            "destination": "wwwroot/js/devextreme/localization"
        },
        {
            // required if you use a VectorMap control
            "library": "node_modules/devextreme/dist/js/vectormap-data/",
            "provider": "filesystem",
            "destination": "wwwroot/js/devextreme/vectormap-data"
        },
        {
            "library": "node_modules/devextreme/dist/css/dx.light.css",
            "provider": "filesystem",
            "destination": "wwwroot/css/devextreme/"
        },
        {
            "library": "node_modules/devextreme/dist/css/icons/",
            "provider": "filesystem",
            "destination": "wwwroot/css/devextreme/icons"
        },
        {
            // required if you use one of the Material Design Themes
            "library": "node_modules/devextreme/dist/css/fonts/",
            "provider": "filesystem",
            "destination": "wwwroot/css/devextreme/fonts"
        },
        {
            "library": "node_modules/devextreme-aspnet-data/js/dx.aspnet.data.js",
            "provider": "filesystem",
            "destination": "wwwroot/js/devextreme"
        }
    ]
}

Run the following command to restore library files:
- Console
```
libman restore
```

Link Client-Side Resources

Open your project’s layout. Typically, it is the _Layout.cshtml file located in the Views/Shared folder (for MVC projects) or Pages folder (for Razor Pages).

Link the following styles and scripts in the head section:

_Layout.cshtml

<head>
    ...
    @* Uncomment to use the HtmlEditor control *@
    @* <script src="https://unpkg.com/devextreme-quill/dist/dx-quill.min.js"></script> *@

    @* Uncomment to use the Gantt control *@ 
    @*<link href="~/css/devextreme/dx-gantt.css" rel="stylesheet" />*@

    @* Uncomment to use the Diagram control *@
    @*<link href="~/css/devextreme/dx-diagram.css" rel="stylesheet" />*@

    <link href="~/css/devextreme/dx.light.css" rel="stylesheet" />

    @* Uncomment to use the Gantt control *@ 
    @*<script src="~/js/devextreme/dx-gantt.js"></script>*@

    @* Uncomment to use the Diagram control *@
    @*<script src="~/js/devextreme/dx-diagram.js"></script>*@

    <script src="~/js/devextreme/jquery.js"></script>

    @* Uncomment to use Globalize for localization *@
    @*<script src="~/js/devextreme/cldr.js"></script>*@
    @*<script src="~/js/devextreme/cldr/event.js"></script>*@
    @*<script src="~/js/devextreme/cldr/supplemental.js"></script>*@
    @*<script src="~/js/devextreme/cldr/unresolved.js"></script>*@
    @*<script src="~/js/devextreme/globalize.js"></script>*@
    @*<script src="~/js/devextreme/globalize/message.js"></script>*@
    @*<script src="~/js/devextreme/globalize/number.js"></script>*@
    @*<script src="~/js/devextreme/globalize/currency.js"></script>*@
    @*<script src="~/js/devextreme/globalize/date.js"></script>*@

    @* Uncomment to enable client-side export *@
    @*<script src="~/js/devextreme/jszip.js"></script>*@

    <script src="~/js/devextreme/dx.all.js"></script>

    @* Uncomment to provide geo-data for the VectorMap control *@
    @*<script src="~/js/devextreme/vectormap-data/world.js"></script>*@

    <script src="~/js/devextreme/dx.aspnet.mvc.js"></script> 
    <script src="~/js/devextreme/dx.aspnet.data.js"></script>
</head>

The layout file can contain jQuery links that were added earlier (they may be placed in the <environment> containers). In this case, remove them.

_Layout.cshtml

...
<!-- Remove the jQuery links below -->
<environment names="Development">
    <script src="~/lib/jquery/dist/jquery.js"></script>
...
<environment names="Staging,Production">
    <script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
...

Note

You can also apply bundling and minification via bundleconfig.json.

Register the DevExtreme.AspNet.Mvc Namespace

Open the _ViewImports.cshtml file located in the Views/Shared folder or Pages folder and add the following directive to it:

_ViewImports.cshtml

@using DevExtreme.AspNet.Mvc

Configure JSON Serialization

In the Startup.cs file, amend the ConfigureServices method as follows to ensure proper JSON serialization:

Startup.cs (ASP.NET Core 2)
Startup.cs (ASP.NET Core 3)

// ...
using Newtonsoft.Json.Serialization;

public void ConfigureServices(IServiceCollection services) {
    services.AddMvc().AddJsonOptions(options => options.SerializerSettings.ContractResolver = new DefaultContractResolver());
}

public void ConfigureServices(IServiceCollection services) {
    services.AddRazorPages().AddJsonOptions(options => options.JsonSerializerOptions.PropertyNamingPolicy = null);
    // or use the following methods:
    // services.AddControllersWithViews().AddJsonOptions(...);
    // services.AddMvc().AddJsonOptions(...);
    // services.AddControllers().AddJsonOptions(...);
}

Enable Controllers

For Razor page projects (ASP.NET Core 3), enable controllers in endpoint routing. To do this, amend the Configure method in the Startup.cs file as follows:

Startup.cs (ASP.NET Core 3)

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    // ...
    app.UseEndpoints(endpoints => {
        // ...
        endpoints.MapControllers(); // enables controllers in endpoint routing
        endpoints.MapDefaultControllerRoute(); // adds the default route {controller=Home}/{action=Index}/{id?}
    });
}

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Install Server-Side Packages

Add Client-Side Resources

Link Client-Side Resources

Register the DevExtreme.AspNet.Mvc Namespace

Configure JSON Serialization

Enable Controllers