MarkLogic .NET Client Library

The MarkLogic .NET Client Library makes it easier to develop .NET applications for MarkLogic. It currently provides tooling for working with MarkLogic Data Services.

Using The Library

Add the client library and the CLI tool to your .NET project:

dotnet add package MarkLogic.Client 
dotnet tool install --global dotnet-ml

Working with Data Services

The approach in developing MarkLogic data services on the .NET is similar to its Java counterpart. Read about working with data services in detail here.

Proxy Service

Use the $netClass property in a service declaration file to explicitly specify the full name of the generated service class for .NET. If not specified, the class generator will fall back to using $javaClass.

For example:

{
  "endpointDirectory" : "/inventory/priceDynamically/",
  "$javaClass"        : "com.some.business.inventory.DynamicPricer",
  "$netClass"         : "SomeBusiness.Inventory.DynamicPricer"
}

Mapping Values to .NET Types

Use the $netClass property in endpoint declaration (.api) files to explicitly specify the type used (using its fully qualified name) for parameters and return values. For example:

{
  "functionName": "ProduceReport",
  "params": [{
    "name": "id",
    "datatype": "int"
  }, {
    "name": "occurred",
    "datatype": "date",
    "$netClass": "string"
  }],
  "return": {
    "datatype": "jsonDocument",
    "$netClass": "Newtonsoft.Json.Linq.JObject"
  }
}

The following table lists server data types, their available representations, and the default type used if $netClass is not specified:

Data Type	Server Type	Default .NET Type	Other .NET Type(s)
boolean	xs:boolean	bool	string
string	xs:string	string	System.IO.Stream
date	xs:date	System.DateTime	string
time	xs:time	System.DateTime	string
dateTime	xs:dateTime	System.DateTime	string
dayTimeDuration	xs:dayTimeDuration	System.TimeSpan	string
decimal	xs:decimal	decimal	string
double	xs:double	double	string
float	xs:float	float	string
int	xs:int	int	string
unsignedInt	xs:unsignedInt	uint	string
long	xs:long	long	string
unsignedLong	xs:unsignedLong	ulong	string
array (JSON)	array-node()	System.IO.Stream	string, Newtonsoft.Json.Linq.JArray
object (JSON)	object-node()	System.IO.Stream	string, Newtonsoft.Json.Linq.JObject
binaryDocument	binary-node()	System.IO.Stream
jsonDocument	document-node()	System.IO.Stream	string, Newtonsoft.Json.Linq.JObject
textDocument	text-node()	System.IO.Stream	string
xmlDocument	document-node()	System.IO.Stream	string, System.Xml.XmlDocument, System.Xml.Linq.XDocument

Generating the Proxy Service Class

A proxy service class provides an interface for calling the data service endpoints deployed on a MarkLogic server. The class is generated from one or more service declaration (service.json) files.

Code generation requires the .NET Core global tool dotnet-ml.

To install the dotnet-ml tool, open a terminal and run:

dotnet tool install -g dotnet-ml

To install from a custom location:

dotnet tool install --add-source <path to repo or package file> -g dotnet-ml

Installing from a custom location would be the case for instances where one doesn't wish to use the published versions, such as building the tool and assemblies locally.

To generate a .cs file from a service.json file, run the following command:

dotnet ml scaffold dataservice -i <path to service.json>

To emit the generated .cs file in a different location besides the current directory, use the -o option:

dotnet ml scaffold dataservice -i <path to service.json> -o <output path>

The filename for the generated .cs file will be the class name set in the $netClass property within the service.json file.

Another file will be generated if it doesn't yet exist: an ml-config.json file. This file will keep track of all subsequent scaffold commands, which will be useful when a project needs to scaffold or update multiple codefiles.

The following command will update all generated codefiles when changes are made to the service or endpoint declaration files:

dotnet ml scaffold update

Using a Proxy Service Class

Provide a valid IDatabaseClient instance to the proxy service class' Create static function to create an instance of a proxy service. Each data service endpoint will have a corresponding method that can be invoked.

var credentials = new NetworkCredential("admin", "admin", "public");
using (var dbClient = DatabaseClientFactory.Create(UriScheme.Http, "localhost", 9000, credentials, AuthenticationType.Digest))
{
  var service = SomeBusiness.Inventory.DynamicPricer.Create(dbClient);
  var jsonReport = await service.ProduceReport(100, DateTime.Now);
}

All endpoint methods are generated as asynchronous and return a Task<T>, where T is the corresponding .NET type of the method's return value. If the return value is declared as multiple, the return type is Task<IEnumerable<T>>. If there is no return value, the return type is Task.

Calling Endpoints in a Session

The generated proxy service class provides the NewSession method to create an instance of ISessionState used for endpoints that require to participate in a session.

Building and Running Tests

The library and CLI tool can be built by running the following commands in the project directory:

dotnet restore
dotnet build

Some tests require a local MarkLogic server to deploy test data services. Run the following commands from the project directory to deploy:

cd test
gradle mlDeploy

Execute the following in the project directory to run all tests:

dotnet test

Run the code-coverage.ps1 script located in each test project to generate its code coverage report, e.g.:

cd MarkLogic.Client.Tests
./code-coverage.ps1

An HTML code coverage report will be generated in the test project's coverage directory.