.NET Client

Nuxeo .NET Client is a cross-platform client library developed in C# for the Nuxeo Automation and REST API.

It targets two platforms:

net45: The traditional .NET framework 4.5, which covers Desktop and ASP .NET apps, among others
dnxcore50: For ASP .NET 5 apps using the open-source and multi-platform .NET Core framework

Nuxeo .NET Client can be used in desktop apps running on Microsoft Windows but also in web applications developed with ASP .NET, running on Windows, Linux and OS X.

Installation

Nuxeo .NET Client can easily be installed from NuGet. Here is how.

Developing with Visual Studio (2013 or Newer)

Open the Package Manager Console and type:

Install-Package NuxeoClient -Pre

Developing for .NET Core, without Visual Studio

Pre-Requistes

You will need to have .NET Core available in your system in order to run the client. Installation instructions are available for Linux, OS X and Windows.

Add the “NuxeoClient” dependency to your project.json file, which should look something like this:
```
{
  ...,
  "dependencies": {
      ...,
      "NuxeoClient": "1.0.0-*"
  },
 ...
}
```
Run the following command on your favorite shell to download all dependencies:
```
dnu restore
```

Initialization

Before using the client, you must include a reference to the NuxeoClient namespaces in your .cs file:
```
using NuxeoClient;
using NuxeoClient.Wrappers;
```
Create a new instance of NuxeoClient, which will allow us to perform API requests to a Nuxeo server. Assuming that the server is running on the local machine and with default credentials, create the client as follows:
```
Client client = new Client("http://localhost:8080/nuxeo/",
                        new Authorization("Administrator",
                                          "Administrator"));
```
Or just omit the default values:
```
Client client = new Client();
```
NuxeoClient exposes the following methods to specify the default schemas to be used when retrieving documents from the server (sets the X-NXDocumentProperties header):
- client.AddDefaultSchema(string schema)
- client.SetDefaultSchemas(string[] schemas)
- client.RemoveDefaultSchema(string schema)
- client.ClearDefaultSchemas()

API Calls

Nuxeo .NET Client exposes methods to perform requests to the Automation and REST API, via client.Operation(string id) and client.Request(RequestType type, string endpoint).

Automation API

The Operation object exposes several methods to parameterize calls to the Automation API. These are:

operation.SetInput: Sets the input of the operation. Can be a string, a JToken or a Blob object.
operation.SetContext(string property, JToken value): Sets the operation context. The value can also be passed as a string.
operation.SetParameter(string property, JToken value): Sets a parameter for the operation. The value can also be passed as a string.
operation.AddHeader(string name, string value): Adds a header to be used in the operation request.
operation.AddSchema(string schema) and operation.SetSchemas(string[] schemas): Defines the schemas to be used in the operation request (overrides the X-NXDocumentProperties header).
operation.SetTimeout(int timeout): Specifies the timeout for the operation.
operation.SetRepository(string repository): Sets the repository to be used in the request (sets the X-NXRepository header).
operation.Execute(): launches a Task that executes the operation, which can be awaited within an async method.

Operation Examples

Creating a document on the root:

Document folder = (Document) await client.Operation("Document.Create")
                                         .SetInput("doc:/")
                                         .SetParameter("type", "Folder")
                                         .SetParameter("name", "TestFolder")
                                         .SetParameter("properties", new ParamProperties { { "dc:title", "Test Folder" } })
                                         .Execute()

Getting the children of a document:

Documents documents = (Documents) await client.Operation("Document.GetChildren")
                                              .SetInput("doc:" + folder.Path)
                                              .Execute()
                                              .Result;

REST API

RESTful requests are made via the client.Request method, which has the following arguments:

RequestType type: the HTTP method type, which can be RequestType.GET, RequestType.POST, RequestType.PUT or RequestType.DELETE.
string endpoint: The URL to the endpoint to which the request will be made.
QueryParams parameters (defaults to null): The query parameters of the URL.
JToken data (defaults to null): The data to be sent in the request. A string can be used, which will be autoboxed to JToken.
Dictionary<string, string> additionalHeaders (defaults to null): The headers to be used in the request.
string contentType (defaults to ContentType.JSON): The content type of the request.

Requests made via this method are issued inside a Task, which can be awaited inside an async method. However, Nuxeo .NET Client provides a handful of wrappers to hide direct calls to client.Request and set headers, which makes code easier to read and write. Examples of these wrappers are Document and Batch.

Document CRUD via REST API

The Document wrapper provides several methods to perform operations over document, such as:

document.Get(): Fetches the document.
document.Post: Creates a child document. Receives an Entity or JToken object.
document.Put: Updates the document. Receives an Entity or JToken object.
document.Delete(): Deletes the document.
SetAdapter(Adapter adapter): Sets a document adapter.
SetContentEnrichers(string[] enrichers): Sets the document enrichers to be used in the next request.

Similarly to Operation, the Document wrapper also provides methods to define headers, schemas, the repository and the timeout.

Examples

Creating a document

Document folder = (Document)await
            client.DocumentFromPath("/")
                  .Post(new Document
                  {
                        Type = "Folder",
                        Name = "folder",
                        Properties = new Properties
                        {
                            { "dc:title", "A Folder" }
                        }
                  });

Updating the same document

Document folder = (Document)await folder.Put(new Document
{
     Properties = new Properties
     {
           { "dc:title", "new title" }
     }
});

Getting the folder's child documents, using the @children adapter
```
Documents children = (Documents)await folder.SetAdapter(new ChildrenAdapter())
                                            .Get();
```
Then, the list of children can be retrieved via:
```
children.Entries
```
Keep in mind that all the requests made to folder will be issued to the children adapter. The adapter can be unset by doing the following:
```
folder.SetAdapter(null);
```

Batch Upload

The Batch wrapper provides methods to upload files, perform operation on batches and get information about batches and uploaded files. Some of the exposed methods are:

batch.Operation(string operationId): Creates a new Operation to be executed over all files in the batch.
batch.Upload(UploadJob job): Uploads a file.
batch.UploadChunk(UploadJob job): Uploads a chunk of a file.
batch.Drop(): Drops the current batch.
batch.Info(): Gets information about a batch.
batch.Info(int fileIndex): Gets information about a specific file that was uploaded to this batch.

Nuxeo .NET Client provides an Uploader that exposes convenient methods to upload files, such as:

uploader.SetChunked(bool isChunkedUpload): Specifies whether files will be uploaded in chunks or not.
uploader.SetChunkSize(int size): The size of the chunks.
uploader.SetNumConcurrentUploads(int num): The number of files that can be uploaded in parallel.
uploader.AddFile(string file) and AddFiles(string[] files): Adds files to the upload queue.
uploader.UploadFiles(): Uploads files in the queue.
uploader.Operation(string operationId): Creates a new Operation to be executed over the current batch.

Now, imagine that you want to upload files to the server and import them as children of folder, the folder created above.

Create a new instance of Uploader, which will upload files in chunks of 1 kB.

Uploader uploader = client.Uploader()
                          .SetChunked(true)
                          .SetChunkSize(1024);

Add files to the queue and start the upload process:

await uploader.AddFile("Test.txt")
              .AddFile("Puppy.docx")
              .UploadFiles();

Perform a batch operation FileManager.Import, which will import all files in the batch as children of folder:

Documents documents = (Documents)await uploader.Operation("FileManager.Import")
                                               .SetContext("currentDocument", folder.Path)
                                               .Execute();

Remarks: Batch Upload complies with the upload API release with Nuxeo Platform 7.4. Batch operations are only compatible with Nuxeo Platform 7.10 or above.

Build

Nuxeo .NET Client's source code is available on GitHub, along with more usage examples and documentation.

In order to build Nuxeo .NET Client, you must have installed the .NET Core DNX SDK, version 1.0.0-beta8, or .NET 4.5 on a Windows setup.

Developing for .NET 4.5

Install the .NET Framework 4.5.
Build and run NuxeoClient_net45.sln in Visual Studio (2013 or newer).

Developing for .NET Core

Install .NET Core in your system. Installation instructions are available for Linux, Mac OS and Windows.
Add the following feeds to NuGet config file:
- https://www.myget.org/F/aspnetvnext/
- https://www.nuget.org/api/v2/
Build the solution with:

dnu build

Sample - NuxeoDotNetBrowser

The Nuxeo .NET Client is already being used by a sample application named NuxeoDotNetBrowser. It provides the basic functionality to browse documents in a Nuxeo server, perform CRUD operations and start workflows.