Referencing the Data Server as a DLL

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

Note that the approach described in this guide is the same for all operating systems: Windows (32-bit and 64-bit), macOS (64-bit and ARM64), and Ubuntu/Linux (64-bit and ARM64).

Note Knowledge of core C# concepts is required to fully understand this guide.

Referencing Flexmonster Data Server

Prerequisites

• Microsoft .NET Core 3.1 or later
  In this tutorial, the .NET 8 framework is used.
• An IDE of your choice (e.g., Visual Studio).

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

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

If you don't have an existing ASP.NET Core project, create a new one with the following commands:

dotnet new web -n flexmonster-project
cd flexmonster-project

Check out how to create an ASP.NET Core project in Visual Studio.

Step 2. Install Flexmonster.DataServer.Core.dll

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

dotnet add package Flexmonster.DataServer.Core 

Step 3. 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 4. Configure the Data Server

Step 4.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
  ]
}

Note If you don't have your own dataset, use our sample data.json file for testing.

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

Step 4.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
  "DataSources":
  [
    // Data sources
  ],
  "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 4.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
app.Run();

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

Step 5. Implement the API controller

Implement the API controller, which is responsible for handling the requests from Flexmonster Pivot.

Step 6. Register the controller

After implementing the API controller, register it by adding 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 
app.Run();

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 
app.Run();

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();
  }
}
// This example CORS configuration is unsafe for production
// The configuration allows any origin, method, and header
// Ensure to adjust the configuration for your project
app.UseCors(builder => {
  builder.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader();
});
// Other app configurations
app.Run();

Learn more about 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

Now Flexmonster.DataServer.Core.dll is configured and ready to connect to Flexmonster Pivot.

Step 10. 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
/>

Step 11. 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",
      index: "index-json"
    }
  }
});

<FlexmonsterReact.Pivot
 toolbar={true}
 report={{
    dataSource: {
      type: "api",
      url: "http://localhost:5000/api",
      index: "index-json"
    }
  }}
/>

<fm-pivot
 [toolbar]="true"
 [report]="{
    dataSource: {
      type: 'api',
      url: 'http://localhost:5000/api',
      index: 'index-json'
    }
  }"
 >
</fm-pivot>

<Pivot
 toolbar
 v-bind:report="{
    dataSource: {
      type: 'api',
      url: 'http://localhost:5000/api',
      index: 'index-json'
    }
  }"
/>

Note The index must match the name of the index defined in step 4.1 (e.g., "index-json"), and the url must be set to your server's URL.

Open the pivot table in the browser to see the data.

Check out the client part of our sample ASP.NET project to see an example of how to configure Flexmonster Pivot.

Full server code

using Flexmonster.DataServer.Core;

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

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();
});

app.Run();

using Microsoft.AspNetCore.Mvc;
using Flexmonster.DataServer.Core;
using Flexmonster.DataServer.Core.Models;

[Route("api")]
[ApiController]
public class FlexmonsterAPIController : ControllerBase
{
  private readonly IApiService _flexmonsterApiService;

  public FlexmonsterAPIController(IApiService apiService)
  {
    _flexmonsterApiService = apiService;
  }

  const string API_VERSION = "2.9.80";

  [Route("handshake")]
  [HttpPost]
  public IActionResult Handshake()
  {
    object response = new { version = API_VERSION };
    return new JsonResult(response);
  }

  [Route("fields")]
  [HttpPost]
  public IActionResult PostFields([FromBody]FieldsRequest request)
  {
    var response = _flexmonsterApiService.GetFields(request);
    return new JsonResult(response);
  }

  [Route("members")]
  [HttpPost]
  public IActionResult PostMembers([FromBody]MembersRequest request)
  {
    var response = _flexmonsterApiService.GetMembers(request);
    return new JsonResult(response);
  }

  [Route("select")]
  [HttpPost]
  public IActionResult PostSelect([FromBody]SelectRequest request)
  {
    var response = _flexmonsterApiService.GetAggregatedData(request);
    return new JsonResult(response);
  }
}

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "DataSources":
  [
    {
      "Type": "json",
      "Indexes": {
        "index-json": {
          "Path": "data.json"
        }
      }
    }
  ],
  "DataStorageOptions": {
    "DataRefreshTime": 60,
    "CacheSizeLimit": 150
  }
}

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 by running the following command inside the project folder:

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