Getting Started

Prerequisites

• Visual Studio 2017 Community v15.3 or higher.
  • C# 7.1 compiler features (included in Visual Studio 2017 v15.3 or higher)
• .NET Core SDK 2.1 or higher.

  C:\>dotnet --info
   .NET Command Line Tools (2.1.200)
   
   Product Information:
    Version:            2.1.200
    Commit SHA-1 hash:  2edba8d7f1
   
   Runtime Environment:
    Base Path:   C:\Program Files\dotnet\sdk\2.1.200\
   
   Microsoft .NET Core Shared Framework Host
     Version  : 2.0.7
  Build    : 2d61d0b043915bc948ebf98836fefe9ba942be11
  

• NuGet Package Command Line installed in your PATH via NuGet.org or via Chocolatey.
• (Optional) RazorGenerator / Visual Studio Extension to modify CodeGen templates.

Checkout & Prep

• git clone https://github.com/bchavez/RethinkDb.Driver.git
• cd RethinkDb.Driver
• build restore ⚠️ You must run this command before opening the .sln file in Visual Studio.

Build Commands

The following build tasks are defined in build.fsx. Execute any of the following build commands in the root project folder.

• build - By default, triggers build msb.
• build msb - Builds binaries for .NET Framework v4.5 using msbuild.
• build dnx - Builds CoreCLR binaries using dotnet command line.
• build clean - Cleans up build.
• build astgen - Regenerates C# AST classes from *.json files.
• build nuget - Builds local NuGet packages.
• build restore - Restores NuGet (runtime and devtime) packages.
• build serverup - Downloads the latest rethinkdb.exe server from the official rethinkdb.com site and sets up a locally running server. Useful for getting a server up and running on localhost for unit tests.
• build test - Run full ReQL unit test battery. This RethinkDB server should be running locally. Connection string for unit tests can be found in RethinkDb.Driver.Tests\App.config under configuration/appSettings/key=TestServer,value=127.0.0.1 XML Xpath.

Internal build commands used by AppVeyor CI server:

• build ci - Used only by CI server to kick off the entire build process. This build task should not be used for local development.
• build citest - Used only by CI server to run the full ReQL test battery. This build task should not be used for local development.

The following folders at the root checkout level be generated:

• __compile - Contains the result of the build process.
• __package - Contains the result of the packaging process.

Project Structure

• build.cmd - Ensures sane build environment and forwards build commands to Builder.
• Source\Builder - Primary location where build tasks are defined. See build.fsx.
• Source\RethinkDb.Driver - The RethinkDB C# driver.
• Source\RethinkDb.Driver.Tests - Driver unit tests.
• Source\Templates - Code generation templates.

Driver Architecture

There are two main components of this C# driver. The ReQL Abstract Syntax Tree (AST) and the infrastructure to handle serialization/deserialization of the AST. The infrastructure also handles communication with a RethinkDB server.

AST & Code Generation

The ReQL AST is located in Source\RethinkDb.Driver\Generated\Ast. The AST C# classes are generated using code generation templates in Source\Templates. The code generation process is similar to the Java driver, except this C# driver requires JSON metadata files derived the Java driver's python scripts (namely, metajava.py). The JSON metadata files required to rebuild the AST (and other objects) are:

• proto_basic.json
• java_term_info.json
• global_info.json

These files reside inside Source/Templates/Metadata.

java_term_info.json is a special file (not to be confused with term_info.json). java_term_info.json is a more refined output of term_info.json that includes extra metadata to support OOP language semantics when generating RethinkDB's AST.

To generate the intermediate JSON files required by this C# driver:

1. Clone the rethinkdb repository (preferably on a Linux computer with build/make tools).

2. Inside the cloned repo, run: ./configure --allow-fetch

3. Next,

   make build/drivers/java/proto_basic.json
   make build/drivers/java/java_term_info.json
   

The required JSON files will be in the following locations:

• rethinkdb/build/drivers/java/proto_basic.json
• rethinkdb/build/drivers/java/java_term_info.json
• rethinkdb/drivers/java/global_info.json

The JSON files above can be copied to & overwritten inside the C# driver's folder Source/Templates/Metadata. The build astgen task will use the *.json files mentioned above to regenerate all AST C# classes, protocol enums, and various models.

build astgen build task essentially runs Templates\GeneratorForAst.cs:Generate_All().

Updating Code Generation Templates

The code generator templates are located in Source/Templates/CodeGen/. The templates are RazorGenerator templates. Updating any of the *.cshtml code generation templates requires installing RazorGenerator's Visual Studio Extension or using RazorGenerator's MSBuild task to transform the Razor *.cshtml templates to *.generated.cs razor code-behind files.