Referencing the Data Server as a DLL

This guide describes the process of embedding Flexmonster Data Server in a .NET Core application.

Referencing Flexmonster Data Server

Prerequisites

• Microsoft .NET Core 3.1 or later
  In this tutorial, the .NET 6 framework is used.
• Visual Studio IDE
  In this tutorial, Visual Studio 2022 is used.

To reference the Data Server as a DLL, follow the steps below.

Step 1. Embed the component into your webpage

If Flexmonster is not yet embedded, set up an empty component in your webpage:

let pivot = new Flexmonster({
  container: "pivotContainer",
  componentFolder: "node_modules/flexmonster/",
  toolbar: true
});

<FlexmonsterReact.Pivot
 toolbar={true}
/>

<fm-pivot
 [toolbar]="true">
</fm-pivot>

<Pivot
 toolbar
/>

Now it’s time to embed Flexmonster Data Server into your ASP.NET Core project.

Step 2. Create a new ASP.NET Core web application

Skip this step if you already have an ASP.NET Core project.

Step 2.1. Start creating a new project:

Via the File menu

Via the start window

Step 2.2. In the project templates menu, select the ASP.NET Core Empty template:

Step 2.3. Enter the name of your project. In the next window, choose the project's configurations:

Step 3. Install Flexmonster.DataServer.Core.dll

Flexmonster.DataServer.Core.dll can be installed using either the NuGet Package Manager or the console:

Using NuGet

Step 3.1. Right-click the project name and select the Manage NuGet Packages item:

Step 3.2. In the Browse tab, search for the Flexmonster.DataServer.Core package and install it:

Using the console

Install Flexmonster.DataServer.Core.dll by running the following command in the console:

dotnet add package Flexmonster.DataServer.Core 

Step 4. Include Flexmonster.DataServer.Core in the Program.cs file

Program.cs is located in the project’s root directory. Add the following line of code to the beginning of the file:

using Flexmonster.DataServer.Core;

Step 5. Configure the Data Server

Step 5.1. For Flexmonster.DataServer.Core.dll, it is possible to configure data sources and different data storage options. The most convenient way of setting the Data Server configuration is to use the configuration file.

In the configuration file (e.g., appsettings.json), define the data sources to use. For example:

{
  // Other settings
  "DataSources": 
  [
    {
      "Type": "json",
      "Indexes": {
        "index-json": {
          "Path": "data.json"
        }
      }
    },
    // Other data sources
  ] 
}

To learn more about the available configurations for Flexmonster.DataServer.Core.dll, refer to the DLL configurations guide.

Step 5.2. optional Set the data storage options, which include the data refresh time and the cache size limit. The data refresh time defines how often the data is reloaded from a file or a database. The cache size limit is the maximum number of cached server responses for every index specified in the DataSources property. You can set the configurations in the configuration file (e.g., appsettings.json) like this:

{
  // Other settings
  "DataStorageOptions": {
    "DataRefreshTime": 60,
    "CacheSizeLimit": 150
  }
}

The data refresh time is set in minutes. If the refresh time is not defined, the data is not reloaded.

If the cache size limit is not specified, the number of cached responses is 100.

Step 5.3. In the previous steps, we configured the Data Server in the configuration file. To apply the configuration, add the following line of code to the Program.cs file:

using Flexmonster.DataServer.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureFlexmonsterOptions(builder.Configuration);
//  Other service configurations

var app = builder.Build();
//  Other app configurations

Note that the configuration should be applied before initializing the app variable.

Step 6. Implement the API controller

The API controller is responsible for handling the requests from Flexmonster Pivot. The implementation of the controller is described in the API controller guide.

After you implement the API controller, add the following lines of code to the Program.cs file:

using Flexmonster.DataServer.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureFlexmonsterOptions(builder.Configuration);
builder.Services.AddFlexmonsterApi();
builder.Services.AddControllers();
// Other service configurations

var app = builder.Build();
app.MapControllerRoute(
  name: "default",
  pattern: "{controller=Home}/{action=Index}"
);
// Other app configurations 

Step 7. (optional) Preload the data

When using the Data Server as a DLL, it is possible to preload data before running the Data Server.

When the app starts, create a scope to resolve the prepopulatingService and call the prepopulatingService.Prepopulate() method, which is responsible for data preloading:

using Flexmonster.DataServer.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureFlexmonsterOptions(builder.Configuration);
builder.Services.AddFlexmonsterApi();
builder.Services.AddControllers();
// Other service configurations

var app = builder.Build();
app.MapControllerRoute(
  name: "default",
  pattern: "{controller=Home}/{action=Index}"
);
using (var scope = app.Services.CreateScope())
{
  var prepopulatingService = scope.ServiceProvider.GetRequiredService<IPrepopulatingService>();
  if (prepopulatingService != null)
  {
    await prepopulatingService.Prepopulate();
  }
}
// Other app configurations 

Step 8. Enable cross-origin resource sharing (CORS)

Due to the same-origin policy, the browser only allows requests that come from the same origin. Cross-origin resource sharing (CORS) allows web applications to make cross-domain requests.

If the ASP.NET Core server and the client share the same origin, skip this step. Otherwise, CORS must be enabled to allow Flexmonster Pivot to send requests to Flexmonster.DataServer.Core.dll:

using Flexmonster.DataServer.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureFlexmonsterOptions(builder.Configuration);
builder.Services.AddFlexmonsterApi();
builder.Services.AddControllers();
builder.Services.AddCors();
// Other service configurations

var app = builder.Build();
app.MapControllerRoute(
  name: "default",
  pattern: "{controller=Home}/{action=Index}"
);
using (var scope = app.Services.CreateScope())
{
  var prepopulatingService = scope.ServiceProvider.GetRequiredService<IPrepopulatingService>();
  if (prepopulatingService != null)
  {
    await prepopulatingService.Prepopulate();
  }
}
app.UseCors(builder => {
  builder.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader();
});
// Other app configurations

Find out how to enable CORS in ASP.NET Core here.

Step 9. Run the project

The ASP.NET Core project can be run either using Visual Studio or the console. To run the project from the console, enter the following command:

dotnet run

Step 10. Configure the report

On the client side, configure the report as follows:

new Flexmonster({
  container: "pivotContainer",
  componentFolder: "node_modules/flexmonster/",
  toolbar: true,
  report: {
    dataSource: {
      type: "api",
      url: "http://localhost:5000/api", // replace with your url
      index: "index-json"
    }
  }
});

Note The index must match the name of the index defined in step 5.1 (e.g., "index-json").

Now Flexmonster.DataServer.Core.dll is configured and ready to connect to Flexmonster Pivot. Open the pivot table in the browser to see the data.

Removing the Data Server

To completely remove the Data Server, you need to delete the Data Server code, configurations, logs, and other related files.

Note The uninstallation is irreversible, so ensure you back up the Data Server configurations.

To remove the Data Server, do the following:

Step 1. Remove traces of the Data Server from your project, which include:

• The API controller (e.g., FlexmonsterAPIController.cs).
• The Data Server configurations (e.g., in the appsettings.json).
• The server filter.
• The custom parser (e.g., CustomParser.cs).
• The Data Server logs.

Step 2. Delete the Flexmonster.DataServer.Core.dll in one of the following ways:

Via Visual Studio

Step 2.1. Right-click the project name and select the Manage NuGet Packages... option:

Step 2.2. Go to the Installed tab, select the Flexmonster.DataServer.Core package, and click Uninstall:

Via the console

Open your project folder and run the following command:

dotnet remove package Flexmonster.DataServer.Core

What's next?

You may be interested in the following articles:

• DLL configurations reference
• Implementing the custom parser
• Implementing the server filter
• Configuring logging
• Troubleshooting the Data Server