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:

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 included 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.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

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

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

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 instant is initialised (note that the examples 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):

A connection string. Note that the values DbType can take is defined in the list of strings above. If using this method, you may wish to store the connection string in a global configuration like the demo examples (shown above).

using (var db = new Database( String type, String connectionString))
{
    ...
}

An existing DbConnection.

using (var db = new Database( String type, DbConnection connection))
{
    ...
}

DbConnectionStringBuilder.

using (var db = new Database( String type, DbConnectionStringBuilder builder))
{
    ...
}

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)!