Installing - .NET Core

This documentation guides you through the installation and basic use of the Editor libraries on your .NET Core environment. The end result is a portable software package that can be run on Windows, Mac or Linux.

Demo package installation

This installation is a simple four step process which the documentation below will guide you though.

Download

To download the Editor .NET Core package, open the Editor download page and select the Editor .NET Core package. If you already have a DataTables account the download will start immediately. If you don't have a DataTables account you will be asked to create one to start a trial.

When the download completes, unzip the files. If you are a Visual Studio user, open the project file. If you prefer the command line, edit the files described below in your favourite Editor.

Examples SQL

We now need to load your database with the tables and data required for the Editor examples. The .NET libraries work with a number of different databases, each of which requires its own SQL. The following links contain the SQL needed for each of the supported databases:

• SQL Server / Azure
• MySQL
• Postgres
• Oracle
• SQLite

Select the appropriate file for your database and then run the SQL contained within on your database access portal (SQL Server Management Studio, CLI, phpMyAdmin or pgAdmin3 for example). The demo SQL will create new tables and enter data into them. Note that they will overwrite any conflicting table names - installing into a new database is recommended, and also, as is good practice, ensure that you have backed up your database.

Database connection

The next step is to set up the database connection so the Editor libraries can interact with the database server. This is done through the Database class in the DataTables namespace, which is a database abstraction layer, so it can interface with any of the above database types.

The database connection for the demo package is configured in the Properties/launchSettings.json file. There are DBTYPE and DBCONNECTION environment variables available which should be set to provide your database connection (note that there are two instances for these variables, one for IIS Express and one for a generic web-server, e.g. Nginx, replace both with your connection detaiils.

• DBTYPE - This defines the database type you are connecting to and can be one of:
  • azure - Microsoft Azure
  • mysql - MySQL
  • postgres - PostgreSQL
  • oracle - Oracle
  • sqlite - SQLite
  • sqlserver - SQL Server
  • sqlserverce - SQL Server CE (for local file databases)
• DBCONNECTION - This is the database connection string to connect to the SQL server. The exact format of the connection string depends upon the server being used, but typically it includes the server host name / address, user name and password. The Connection Strings web-site can be useful if you aren't sure of what connection string to use for your server.

Running the examples

That's all the set up that is needed to run the examples! To actually run them, now press F5 or select the Start debugging option from the Debug menu in Visual Studio.

NuGet

The Editor server-side libraries for .NET are available on NuGet for easy inclusion in your project without needing to build or locally reference the DataTables-Editor-Server.dll yourself. To install via NuGet search in Visual Studio's NuGet explorer for "DataTables-Editor-Server" and install. If you prefer to install on the command line use:

# Package manager:
Install-Package DataTables-Editor-Server

# or
# .NET CLI
dotnet add package DataTables-Editor-Server

Database connection

Program

The database connection for .NET Core differs a little from .NET Framework. In .NET Framework the database drivers that are available to a program are automatically available system wide (through machine.config). This is not the case in .NET Core and you must register the database driver you want to use - typically in Program.cs or Startup.cs. The registration is done using the DbProviderFactories.RegisterFactory method:

SQL Server

If you are using System.Data.SqlClient then use:

// using statement at top of Program.cs
using System.Data.SqlClient;

// Register the factory in `Main`
DbProviderFactories.RegisterFactory("System.Data.SqlClient", SqlClientFactory.Instance);

However, if you are using the newer Microsoft.Data.SqlClient use:

// using statement at top of Program.cs
using Microsoft.Data.SqlClient;

// Register the factory in `Main`
DbProviderFactories.RegisterFactory("Microsoft.Data.SqlClient", SqlClientFactory.Instance);

and when you create an Editor database connection, use the optional third parameter to ensure the correct factory provider is used (see the Controllers section below for further details):

var db = new Database("sqlserver", connectionString, "Microsoft.Data.SqlClient");

MySQL

// using statement at top of Program.cs
using MySql.Data.MySqlClient;

// Register the factory in `Main`
DbProviderFactories.RegisterFactory("MySql.Data.MySqlClient", MySqlClientFactory.Instance);

PostgreSQL

// using statement at top of Program.cs
using Npgsql;

// Register the factory in `Main`
DbProviderFactories.RegisterFactory("Npgsql", NpgsqlFactory.Instance);

SQLite

// using statement at top of Program.cs
using Microsoft.Data.Sqlite;

// Register the factory in `Main`
DbProviderFactories.RegisterFactory("Microsoft.Data.Sqlite", SqliteFactory.Instance);

Controllers

From this point on, the connection to the database is the same as for .NET Framework (since the data provider has been registered). In each controller a Database class instance is initialised (note that many of the examples on the site and the demo package make use of the using statement to ensure that the connection is closed when no longer required - you could call db.Close() manually if you prefer).

The Database class has a number of overloads, allowing new connections to be made or existing connections to be reused. It accepts up to three parameters:

1. String - A database type, This must be one of the strings shown above.
2. String, DbConnection or DbConnectionStringBuilder - this defines the connection to the database - e.g. its address, user name / password, etc. It can be a standard .NET connection string for your database type, an existing database connection that you have available in your application or a database connection string builder instance ).
3. String - Optionally you can set the database factory.

Here are a few examples:

// Connecting to an SQL Server with a connection string
var db = new Database("sqlserver", connectionString);

// Connecting to an SQL Server with the newer Microsoft.Data.SqlClient provider
var db = new Database("sqlserver", connectionString, "Microsoft.Data.SqlClient");

// Connecting to Postgres with an existing database connection
var db = new Database("postgres", dbConnection);

Returning JSON from a controller

Please be aware that as of .NET Core 3 and newer (including .NET5) to have a JSON return from a controller, you need to register a JSON controller. This can be done in your Startup.cs file's ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers().AddNewtonsoftJson(); // Required in .NET Core 3 and later. Optional before
    // ... other configuration
}

The Editor demo package has this already configured, but you may need to add it to your own package if you have started a fresh solution.

Next steps

With the examples running, the next step is to start experimenting with the examples and understanding how the Editor C# code operates. Beyond that, you can start to include Editor in your own applications (Web API / MVC)!