Need a special offer?Find out if your project fits.
+
All documentation
  • Introduction
  • Connecting to data source
    1. Supported data sources
    2. Connecting to other data sources
  • Browser compatibility
  • Documentation for older versions
  • Configurations reference

    This guide describes the available configurations for Flexmonster.DataServer.Core.dll. For the Data Server DLL, it is possible to configure data sources and set the data refresh time.

    Available configurations

    The Data Server supports the following configuration properties:

    {
      "DataSources": DataSourceConfigObject[],
      "DataStorageOptions": DataStorageOptionsObject
    }
    Property/TypeDescription
    DataSources
    DataSourceConfigObject[]
    Options for configuring the data sources.
    DataStorageOptions
    DataStorageOptionsObject
    optional Allows configuring options for data storage.

    DataSourceConfigObject

    This object allows configuring a data source. It has the following properties:

    {
      "Type": string,
      "DatabaseType": string,
      "ConnectionString": string,
      "Indexes": object
    }
    Property/TypeDescription
    Type
    String
    The type of the data source: "json""csv""database", or your custom type (for the custom parser).
    DatabaseType
    String
    optional The type of the database: "mysql""mariadb", "mssql""postgresql", or "oracle". Only for the "database" data source type.
    ConnectionString
    String
    optional A connection string for the database. Only for the "database" data source type.
    Setting passwords with special characters in the connection string. The Data Server parses passwords with special characters correctly unless the password contains ; or ". These symbols are treated as delimiters, so they should be escaped:
    • If your password contains a semicolon (;), enclose the password in single quotes (e.g., Pwd='123;45').
    • If your password contains a double quote ("), escape this symbol with a backslash (e.g., Pwd=123\"45).
    Indexes
    Object
    Contains a list of datasets. Each dataset is represented by a "key": "value" pair, where "key" is a dataset name. The "value" can either be null (only for the custom data source type) or be an IndexObject.

    IndexObject

    This object describes a specific dataset. It has the following properties:

    {
      "Path": string,
      "Query": string,
      "Mapping": ServerSideMappingObject,
      "Delimiter": string,
      "DecimalSeparator": string,
      "ThousandsSeparator": string,
      "Status": string,
      "RefreshTime": number
    }
    Property/TypeDescription
    Path
    String
    optional The path to the file with data. Only for "json" and "csv" data source types.
    Query
    String
    optional The query to execute (e.g., "SELECT * FROM tablename"). It can contain a stored procedure. Only for the "database" data source type.
    Mapping
    ServerSideMappingObject
    optional Defines how the Data Server should process fields from the dataset. Only for "json" and "csv" data source types.
    Delimiter
    String
    optional Defines the specific fields separator to split each CSV row. There is no need to define it if the CSV fields are separated by ,. This property is required only if another character separates fields.
    Default value: ",".
    DecimalSeparator
    String
    optional Defines the specific character used to separate decimal parts of numbers. For example, to import CSV data with commas used to separate decimal parts of numbers (e.g., 3,14), set the "DecimalSeparator" property to ",".
    Default value: ".".
    ThousandsSeparator
    String
    optional Defines the specific character used to separate groups of digits in numbers. For example, to import CSV data with periods used to separate groups of digits in numbers (e.g., 1.000 for one thousand), set the "ThousandsSeparator" property to ".".
    Default value: ",".
    Status
    String
    optional The index status. It can be either "enabled" or "disabled". Disabled indexes are not available from the client.
    The "Status" property is available starting from version 2.9 of the Data Server.
    Default value: "enabled".
    RefreshTime
    Number
    optional Defines how often the Data Server reloads the data for the index.
    The refresh time is specified in minutes. If it is 0, the Data Server will not reload the data.
    "RefreshTime" will override a value set in DataStorageOptions.DataRefreshTime.
    If "RefreshTime" is not specified, the Data Server will use the DataStorageOptions.DataRefreshTime property.
    If both properties are not specified, the data will not be reloaded.
    The "RefreshTime" property is available starting from version 2.9 of the Data Server.

    ServerSideMappingObject

    This object defines how the Data Server should process fields from the dataset. It has the following properties:

    "Mapping": {
      "(uniqueName)": {
        "Type": string
      }
    }
    Property/TypeDescription
    (uniqueName)
    Object
    Allows setting the mapping for a specific field from the dataset. "(uniqueName)" is the field’s unique name.
    (uniqueName).Type
    String
    optional The field’s data type. The "Type" can be:
    • "string" — the field stores string data.
    • "number" — the field stores numerical data.
    • "date" — the field stores a date.
    If this property is not specified, the Data Server resolves the data type automatically based on the field’s values in the dataset.

    DataStorageOptionsObject

    This object allows configuring options for data storage. It has the following properties:

    "DataStorageOptions": {
      "DataRefreshTime": number,
      "CacheSizeLimit": number,
      "KeepDataOnRefresh": boolean,
      "CommandTimeout": number
    }
    Property/TypeDescription
    DataRefreshTime
    Number
    optional Defines how often the data is reloaded from a file or a database. The refresh time is set in minutes. If the "DataRefreshTime" is not specified, the data will not be reloaded.
    CacheSizeLimit
    Number
    optional The maximum number of cached server responses for every index defined in the "DataSources" property. When set to 0, the Data Server does not cache the responses.
    Default value: 100.
    KeepDataOnRefresh
    Boolean
    optional When set to true, the Data Server keeps a copy of index data while the index is being refreshed. As a result, the index is available to Flexmonster Pivot even during index reload. Note that this feature requires more RAM. As soon as the index is refreshed, the Data Server deletes its copy.
    If "KeepDataOnRefresh" is set to false, the index will be unavailable while refreshing.
    Default value: true.
    CommandTimeout
    Number
    optional Defines the wait time before canceling the attempt to execute the Query and generating an error. The wait time is set in seconds. When set to 0, the wait time is unlimited.
    If "CommandTimeout" is not specified, the Data Server will use the timeout value from the SQL driver. Only for the "database" data source type.

    Setting configs

    You can configure the Data Server through:

    • Configuration file
    • Code
    • Both code and the file

    Configuration file

    Flexmonster.DataServer.Core.dll can be configured via the ASP.NET configuration file (e.g., appsettings.json). In addition to the Data Server's configuration, this file can contain any other settings needed for the project, as long as they do not conflict with each other.

    To configure the Data Server via appsettings.json, follow the steps below:

    Step 1. Define the needed configurations in appsettings.json. Here is an example of a configured appsettings.json file with the custom parser:

    Expand the example
    {
      "DataSources": [
        {
          "Type": "custom-parser",
          "Indexes": {
            "custom-index": null
          }
        },
        {
          "Type": "json",
          "Indexes": {
            "first-json-index": {
              "Path": "data/data.json" 
            },
            "second-json-index": {
              "Path": "data/another-data.json"
            }
          }
        },
        {
          "Type": "csv",
          "Indexes": {
            "csv-index": {
              "Path": "data/data.csv",
              "Delimiter": ";",
              "DecimalSeparator": "."
            }
          }
        }
      ],
      "DataStorageOptions": {
        "DataRefreshTime": 60,
        "CacheSizeLimit": 150
      }
    }

    Step 2. To apply configs from appsettings.json, 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 configurations

    Code

    You can configure the Data Server through code using the Program.cs file. See how to:

    Create indexes

    Step 1. In the Program.cs file, call the builder.Services.Configure<DatasourceOptions> method:

    var builder = WebApplication.CreateBuilder(args);
    // Other configurations
    
    builder.Services.Configure<DatasourceOptions>((options) => {
    });
    // Other configurations

    Step 2. In the builder.Services.Configure<DatasourceOptions>, create a dictionary to store your indexes:

    // Other configurations
    
    builder.Services.Configure<DatasourceOptions>((options) => {
        options.Indexes = new Dictionary<string, IndexOptions>();
    });
    // Other configurations

    As you can see, each index consists of two fields:

    • A string field, which is the index’s name.
    • An IndexOptions field, which contains configurations needed to load the index’s data. IndexOptions is an abstract class.

    Step 3. Add your index to the Indexes dictionary. For example, let’s create a new JSON index:

    // Other configurations
    
    builder.Services.Configure<DatasourceOptions>((options) => {
        options.Indexes = new Dictionary<string, IndexOptions>();
        options.Indexes.Add("json-index", 
          new JsonIndexOptions("path-to-your-file.json"));
    });
    // Other configurations

    JsonIndexOptions is a class that allows configuring JSON indexes. It is based on the IndexOptions class.

    CSV and database indexes are configured through similar classes. See a list of these classes and their constructors:

    • JSON:
      • public JsonIndexOptions(string path)
    • CSV:
      • public CsvIndexOptions(string path)
      • public CsvIndexOptions(string path, char delimiter, char decimalSeparator, char thousandsSeparator)
    • Databases:
      • public DatabaseIndexOptions(databaseType, connectionString, query)

    See the full list of configurations for indexes.

    Set data storage options

    Step 1. In the Program.cs file, add the following lines of code:

    using Flexmonster.DataServer.Core.DataStorages;
    
    var builder = WebApplication.CreateBuilder(args);
    // Other configurations
    
    builder.Services.Configure<DataStorageOptions>((options) => {
    });
    // Other configurations

    Step 2. Set the needed data storage options using the options object:

    // Other configurations
    
    builder.Services.Configure<DataStorageOptions>((options) =>
    {
        options.CacheSizeLimit = 100;
        options.DataRefreshTime = 60;
    });
    // Other configurations

    See the full list of available data storage options.

    Both code and the file

    If needed, you can load configs from appsettings.json and then continue configuring the Data Server through code. It can be done by importing configs from appsettings.json before adding configs through code:

    using Flexmonster.DataServer.Core;
    
    var builder = WebApplication.CreateBuilder(args);
    builder.Services.ConfigureFlexmonsterOptions(builder.Configuration);
    
    /* Note: importing configs from the file overrides configs
       set through code. That’s why you should always 
       add your configs after the 
       builder.Services.ConfigureFlexmonsterOptions(builder.Configuration) 
       line
    */
    builder.Services.Configure<DatasourceOptions>((options) => {
        options.Indexes = new Dictionary<string, IndexOptions>();
        options.Indexes.Add("json-index", 
          new JsonIndexOptions("path-to-your-file.json"));
    });
    // Other configurations

    What’s next?

    You may be interested in the following articles: