Hi, in this step by step article, I will show you how to integrate DevExtreme components into ABP Framework-based applications.

(A screenshot from the example application developed in this article)

Create the Project

ABP Framework offers startup templates to get into the business faster. We can download a new startup template using ABP CLI:

abp new DevExtremeSample

After the download is finished, open the solution in the Visual Studio (or your favorite IDE):

Run the DevExtremeSample.DbMigrator application to create the database and seed initial data (which creates the admin user, admin role, related permissions, etc). Then we can run the DevExtremeSample.Web project to see our application working.

Default admin username is admin and password is 1q2w3E*

Install DevExtreme

You can follow this documentation to install DevExpress packages into your computer.

Don't forget to add "DevExpress NuGet Feed" to your Nuget Package Sources.

Adding DevExtreme NuGet Packages

Add the DevExtreme.AspNet.Core NuGet package to the DevExtremeSample.Application.Contracts project.

Install-Package DevExtreme.AspNet.Core

Add the DevExtreme.AspNet.Data package to your DevExtremeSample.Web project.

Install-Package DevExtreme.AspNet.Data

Adding DevExtreme NPM Dependencies

Open your DevExtremeSample.Web project folder with a command line and add devextreme and devextreme-aspnet-data NPM packages:

npm install devextreme

npm install devextreme-aspnet-data

Adding Resource Mappings

The devextreme and devextreme-aspnet-data NPM packages are saved under node_modules folder. We need to move the needed files in our wwwroot/libs folder to use them in our web project. We can do it using the ABP client side resource mapping system.

Open the abp.resourcemapping.js file in your DevExtremeSample.Web project and add the following definitions to inside mappings object.

"@node_modules/devextreme/dist/**/*": "@libs/devextreme/",
"@node_modules/devextreme-aspnet-data/js/dx.aspnet.data.js": "@libs/devextreme/js/"

The final abp.resourcemapping.js file should look like below:

module.exports = {
  aliases: {},
  mappings: {
    "@node_modules/devextreme/dist/**/*": "@libs/devextreme/",
    "@node_modules/devextreme-aspnet-data/js/dx.aspnet.data.js": "@libs/devextreme/"
  },
};

Open your DevExtremeSample.Web project folder with a command line and run the abp install-libs command. This command will copy the needed library files into the /wwwroot/libs/devextreme/ folder.

abp install-libs

You can see devextreme folder inside the wwwroot/libs:

Adding DevExtremeStyleContributor

We will add DevExtreme CSS files to the global bundle by creating a bundle contributor.

Create a Bundling folder in the DevExtremeSample.Web project and a DevExtremeStyleContributor.cs file with the following content:

using System.Collections.Generic;
using Volo.Abp.AspNetCore.Mvc.UI.Bundling;

namespace DevExtremeSample.Web.Bundling
{
    public class DevExtremeStyleContributor : BundleContributor
    {
        public override void ConfigureBundle(BundleConfigurationContext context)
        {
            context.Files.AddIfNotContains("/libs/devextreme/css/dx.common.css");
            context.Files.AddIfNotContains("/libs/devextreme/css/dx.light.css");
        }
    }
}

You can choose another theme than the light theme. Check the /libs/devextreme/css/ folder and the DevExtreme documentation for other themes.

Open your DevExtremeSampleWebModule.cs file in your DevExtremeSample.Web project and add following code into the ConfigureServices method:

Configure<AbpBundlingOptions>(options =>
{
    options
        .StyleBundles
        .Get(StandardBundles.Styles.Global)
        .AddContributors(typeof(DevExtremeStyleContributor));
});

Adding DevExtremeScriptContributor

We can not add DevExtreme js packages to Global Script Bundles, just like done for the CSS files. Because DevExtreme requires to add its JavaScript files into the <head> section of the HTML document, while ABP Framework adds all JavaScript files to the end of the <body> (as a best practice).

Fortunately, ABP Framework has a layout hook system that allows you to add any code into some specific positions in the HTML document. All you need to do is to create a ViewComponent and configure the layout hooks.

Let's begin by creating a DevExtremeScriptContributor.cs file in the Bundling folder by copying the following code inside it:

using System.Collections.Generic;
using Volo.Abp.AspNetCore.Mvc.UI.Bundling;
using Volo.Abp.AspNetCore.Mvc.UI.Packages.JQuery;
using Volo.Abp.Modularity;

namespace DevExtremeSample.Web.Bundling
{
    [DependsOn(
        typeof(JQueryScriptContributor)
        )]
    public class DevExtremeScriptContributor : BundleContributor
    {
        public override void ConfigureBundle(BundleConfigurationContext context)
        {
            context.Files.AddIfNotContains("/libs/devextreme/js/dx.all.js");
            context.Files.AddIfNotContains("/libs/devextreme/js/dx.aspnet.mvc.js");
            context.Files.AddIfNotContains("/libs/devextreme/js/dx.aspnet.data.js");
        }
    }
}

As you see, the DevExtremeScriptContributor depends on JQueryScriptContributor which adds JQuery related files before the DevExpress packages (see the bundling system for details).

Create DevExtremeJsViewComponent

Create a new view component, named DevExtremeJsViewComponent inside the /Components/DevExtremeJs folder of the Web project, by following the steps below:

1. Create a DevExtremeJsViewComponent class inside the /Components/DevExtremeJs (create the folders first):

using Microsoft.AspNetCore.Mvc;
using Volo.Abp.AspNetCore.Mvc;

namespace DevExtremeSample.Web.Components.DevExtremeJs
{
    public class DevExtremeJsViewComponent : AbpViewComponent
    {
        public IViewComponentResult Invoke()
        {
            return View("/Components/DevExtremeJs/Default.cshtml");
        }
    }
}

2. Create Default.cshtml file in the same folder with the following content:

@using DevExtremeSample.Web.Bundling
@addTagHelper *, Volo.Abp.AspNetCore.Mvc.UI.Bundling

<abp-script type="typeof(DevExtremeScriptContributor)" />

Your final Web project should be like the following:

3. Now, we can add this view component to <head> section by using the layout hooks.

Open your DevExtremeSampleWebModule.cs file in your DevExtremeSample.Web project and add following code into the ConfigureServices method:

Configure<AbpLayoutHookOptions>(options =>
{
    options.Add(
        LayoutHooks.Head.Last, //The hook name
        typeof(DevExtremeJsViewComponent) //The component to add
    );
});

Known Issue: Uncaught TypeError: MutationObserver.observe: Argument 1 is not an object.

This issue does exist in the ABP Framework v3.0 and earlier versions. If you are using ABP Framework v3.1 or a later version, you can skip this section.

When you run your *.Web project, you will see an exception (Uncaught TypeError: MutationObserver.observe: Argument 1 is not an object.) at your console.

To fix that issue, download this file abp.jquery.js and replace with the wwwroot/libs/abp/jquery/abp.jquery.js file of your Web project.

Result

The installation step was done. You can use any DevExtreme component in your application.

Example: A button and a progress bar component:

This example has been created by following this documentation.

The Sample Application

We have created a sample application with Tree List and Data Grid examples.

The Source Code

You can download the source code from here.

Data Grid

You can see the full working example of Data Grid.

The related files for this example are highlighted at the following screenshots.

Tree List

You can see the full working example of Tree List.

The related files for this example are highlighted at the following screenshots.

Additional Notes

Data Storage

I've used an in-memory list to store data for this example, instead of a real database. Because it is not related to DevExpress usage. There is a SampleDataService.cs file in Data folder at .Application.Contracts project. All the data is stored here.

JSON Serialization

You can see some JsonProperty attributes on the DTO properties. I use these attributes because DevExtreme example expects PascalCase property names in the serialized JSON that is sent to the client. But ABP Framework & ASP.NET Core conventionally uses camelCase property names on JSON serialization. Adding these JsonProperty attributes ensures that the related properties are serialized as PascalCase.

DevExtreme Components vs Application Service Methods

ABP Framework conventionally converts application services to API Controllers. For example, see the application service below:

public class OrderAppService : DevExtremeSampleAppService, IOrderAppService
{
    public async Task<LoadResult> GetOrdersAsync(DataSourceLoadOptions loadOptions)
    {
        ...
    }

    public async Task<Order> InsertOrder(string values)
    {
        ...
    }
    ...
}

You can use these service methods for your DevExtreme components as shown below:

Html.DevExtreme().DataGrid<Order>()
            .DataSource(d => d.Mvc()
                .Controller("Order") // Application Service Name without 'AppService'
                .LoadAction("GetOrders") // Method Name without 'Async'
                .InsertAction("InsertOrder")
                .UpdateAction("UpdateOrder")
                .DeleteAction("DeleteOrder")
                .Key("OrderID")
            )

Conclusion

In this article, I've explained how to use DevExtreme components in your application. ABP Framework is designed so that it can work with any UI library/framework.

Introduction

This step-by-step article describes how to upload a file to a Web server and also download by client with using ASP.NET Core & ABP Framework. By following this article, you will create a web project and its related code to upload and download files.

Before the creating application, we need to know some fundamentals.

BLOB Storing

It is typical to store file contents in an application and read these file contents on need. Not only files, but you may also need to save various types of large binary objects, a.k.a. BLOBs, into a storage. For example, you may want to save user profile pictures.

A BLOB is a typically byte array. There are various places to store a BLOB item; storing in the local file system, in a shared database or on the Azure BLOB storage can be options.

The ABP Framework provides an abstraction to work with BLOBs and provides some pre-built storage providers that you can easily integrate to. Having such an abstraction has some benefits;

• You can easily integrate to your favorite BLOB storage provides with a few lines of configuration.
• You can then easily change your BLOB storage without changing your application code.
• If you want to create reusable application modules, you don't need to make assumption about how the BLOBs are stored.

ABP BLOB Storage system is also compatible to other ABP Framework features like multi-tenancy.

To get more information about ABP BLOB Storing system, please check this documentation.

Preparing the Project

Startup template and the initial run

Abp Framework offers startup templates to get into the business faster. We can download a new startup template using Abp CLI:

abp new FileActionsDemo -m none

After the download is finished, we run FileActionsDemo.DbMigrator project to create the database and seed initial data (admin user, role, etc). Then we run FileActionsDemo.Web to see our application working.

Default admin username is admin and password is 1q2w3E*

Adding Blob Storing Module

For this article, we use Blob Storing Database Provider.

You can use Azure or File System providers also.

Open a command prompt (terminal) in the folder containing your solution (.sln) file and run the following command:

abp add-module Volo.Abp.BlobStoring.Database

This action will add the module dependencies and also module migration. After this action, run FileActionsDemo.DbMigrator to update the database.

Setting up Blob Storage

BLOB Storage system works with Containers. Before the using blob storage, we need to create our blob container.

Create a class that name MyFileContainer at the FileActionsDemo.Domain project.

using Volo.Abp.BlobStoring;

namespace FileActionsDemo
{
    [BlobContainerName("my-file-container")]
    public class MyFileContainer
    {

    }
}

That's all, we can start to use BLOB storing in our application.

Creating Application Layer

Before the creating Application Service, we need to create some DTOs that used by Application Service.

Create following DTOs in FileActionsDemo.Application.Contracts project.

• BlobDto.cs

  namespace FileActionsDemo
  {
      public class BlobDto
      {
          public byte[] Content { get; set; }
  
          public string Name { get; set; }
      }
  }
  

• GetBlobRequestDto.cs

  using System.ComponentModel.DataAnnotations;
  
  namespace FileActionsDemo
  {
      public class GetBlobRequestDto
      {
          [Required]
          public string Name { get; set; }
      }
  }
  

• SaveBlobInputDto.cs

  using System.ComponentModel.DataAnnotations;
  
  namespace FileActionsDemo
  {
      public class SaveBlobInputDto
      {
          public byte[] Content { get; set; }
  
          [Required]
          public string Name { get; set; }
      }
  }
  

Create IFileAppService.cs interface at the same place with DTOs.

• IFileAppService

  using System.Threading.Tasks;
  using Volo.Abp.Application.Services;
  
  namespace FileActionsDemo
  {
      public interface IFileAppService : IApplicationService
      {
          Task SaveBlobAsync(SaveBlobInputDto input);
  
          Task<BlobDto> GetBlobAsync(GetBlobRequestDto input);
      }
  }
  

After creating DTOs and interface, FileActionsDemo.Application.Contracts project should be like as following image.

Then we can create our Application Service.

Create FileAppService.cs in FileActionsDemo.Application project.

using System.Threading.Tasks;
using Volo.Abp.Application.Services;
using Volo.Abp.BlobStoring;

namespace FileActionsDemo
{
    public class FileAppService : ApplicationService, IFileAppService
    {
        private readonly IBlobContainer<MyFileContainer> _fileContainer;

        public FileAppService(IBlobContainer<MyFileContainer> fileContainer)
        {
            _fileContainer = fileContainer;
        }

        public async Task SaveBlobAsync(SaveBlobInputDto input)
        {
            await _fileContainer.SaveAsync(input.Name, input.Content, true);
        }

        public async Task<BlobDto> GetBlobAsync(GetBlobRequestDto input)
        {
            var blob = await _fileContainer.GetAllBytesAsync(input.Name);

            return new BlobDto
            {
                Name = input.Name,
                Content = blob
            };
        }
    }
}

As you see in previous code block, we inject IBlobContainer<MyFileContainer> to our app service. It will handle all blob actions for us.

• SaveBlobAsync method uses SaveAsync of IBlobContainer<MyFileContainer> to save the given blob to storage, this is a simple example so we don't check is there any file exist with same name. We sent blob name, blob content and true for overrideExisting parameter.

• GetBlobAsync method is uses GetAllBytesAsync of IBlobContainer<MyFileContainer> to get blob content by name.

We finished the application layer for this project. After that we will create a Controller for API and Razor Page for UI.

Creating Controller

Create FileController.cs in your FileActionsDemo.HttpApi project.

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Volo.Abp.AspNetCore.Mvc;

namespace FileActionsDemo
{
    public class FileController : AbpController
    {
        private readonly IFileAppService _fileAppService;

        public FileController(IFileAppService fileAppService)
        {
            _fileAppService = fileAppService;
        }

        [HttpGet]
        [Route("download/{fileName}")]
        public async Task<IActionResult> DownloadAsync(string fileName)
        {
            var fileDto = await _fileAppService.GetBlobAsync(new GetBlobRequestDto{ Name = fileName });

            return File(fileDto.Content, "application/octet-stream", fileDto.Name);
        }
    }
}

As you see, FileController injects IFileAppService that we defined before. This controller has only one endpoint.

DownloadAsync is using to send file from server to client.

This endpoint is requires only a string parameter, then we use that parameter to get stored blob. If blob is exist, we return a File result so download process can start.

Creating User Interface

We will create only one page to prove download and upload actions are working.

Create folder that name Files in your Pages folder at FileActionsDemo.Web project.

Create a Razor page that name Index with its model.

• Index.cshtml.cs

using System.ComponentModel.DataAnnotations;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Volo.Abp.AspNetCore.Mvc.UI.RazorPages;

namespace FileActionsDemo.Web.Pages.Files
{
    public class Index : AbpPageModel
    {
        [BindProperty]
        public UploadFileDto UploadFileDto { get; set; }

        private readonly IFileAppService _fileAppService;

        public bool Uploaded { get; set; } = false;

        public Index(IFileAppService fileAppService)
        {
            _fileAppService = fileAppService;
        }

        public void OnGet()
        {

        }

        public async Task<IActionResult> OnPostAsync()
        {
            using (var memoryStream = new MemoryStream())
            {
                await UploadFileDto.File.CopyToAsync(memoryStream);

                await _fileAppService.SaveBlobAsync(
                    new SaveBlobInputDto
                    {
                        Name = UploadFileDto.Name,
                        Content = memoryStream.ToArray()
                    }
                );
            }

            return Page();
        }
    }

    public class UploadFileDto
    {
        [Required]
        [Display(Name = "File")]
        public IFormFile File { get; set; }

        [Required]
        [Display(Name = "Filename")]
        public string Name { get; set; }
    }
}

As you see, we use UploadFileDto as a BindProperty and we inject IFileAppService to upload files.

The UploadFileDto is requires a string parameter for using as a blob name and a IFormFile that sent by user.

At the post action (OnPostAsync), if everything is well, we use MemoryStream to get all bytes from file content.

Then we save file with SaveBlobAsync method of IFileAppService.

• Index.cshtml

@page
@model FileActionsDemo.Web.Pages.Files.Index

@section scripts{
    <abp-script src="/Pages/Files/index.js" />
}

<abp-card>
    <abp-card-header>
        <h3>File Upload and Download</h3>
    </abp-card-header>
    <abp-card-body>
        <abp-row>
            <abp-column>
                <h3>Upload File</h3>
                <hr />
                <form method="post" enctype="multipart/form-data">
                    <abp-input asp-for="UploadFileDto.Name"></abp-input>

                    <abp-input asp-for="UploadFileDto.File"></abp-input>

                    <input type="submit" class="btn btn-info" />
                </form>
            </abp-column>

            <abp-column style="border-left: 1px dotted gray">
                <h3>Download File</h3>
                <hr />
                <form id="DownloadFile">
                    <div class="form-group">
                        <label for="fileName">Filename</label><span> * </span>
                        <input type="text" id="fileName" name="fileName" class="form-control ">
                    </div>

                    <input type="submit" class="btn btn-info"/>
                </form>
            </abp-column>
        </abp-row>
    </abp-card-body>
</abp-card>

We divided the page vertically, left side will be using for upload and right side will be using for download. We use ABP Tag Helpers to create page.

• index.js

$(function () {
  var DOWNLOAD_ENDPOINT = "/download";

  var downloadForm = $("form#DownloadFile");

  downloadForm.submit(function (event) {
    event.preventDefault();

    var fileName = $("#fileName").val().trim();

    var downloadWindow = window.open(
      DOWNLOAD_ENDPOINT + "/" + fileName,
      "_blank"
    );
    downloadWindow.focus();
  });

  $("#UploadFileDto_File").change(function () {
    var fileName = $(this)[0].files[0].name;

    $("#UploadFileDto_Name").val(fileName);
  });
});

This jQuery codes are using for download. Also we wrote a simple code to autofill Filename input when user selects a file.

After creating razor page and js file, FileActionsDemo.Web project should be like as following image.

Result

After completing code tutorial, run FileActionsDemo.Web project and go /Files. You can upload any file with any name and also download those uploaded files.