.NET Framework is one of the most popular frameworks to develop for Microsoft Windows. Not only that, the adoption of ASP.NET as a server-side solution is increasing for the top 100k sites on the Internet, which makes .NET’s relevance hard to overlook. Keeping this in mind, developing a client using this framework for the Nuxeo Platform became one of our top priorities.
In this blog, I will discuss this client called the Nuxeo .NET Client in detail and show you how you can use it.
The Nuxeo .NET Client
The Nuxeo .NET Client is a cross-platform client library developed in C# for 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, multi-platform and recently-introduced .NET Core framework.
As such, the Nuxeo .NET Client is able to reach desktop apps for Microsoft Windows but also web applications developed with ASP.NET, running on Windows, Linux and Mac OS.
The Nuxeo .NET Client exposes a smooth interface that makes it easy to parameterize and send requests to an instance of the Nuxeo server. It takes care of marshalling and unmarshalling objects between native types and the JSON objects that are sent and received from the server.
Exploring the Nuxeo .NET Client
Now that we understand what it is and what it aims for, let’s play a little with it.
Installation
The Nuxeo .NET Client is available on NuGet. Assuming you are running Visual Studio 2013 or above, just open the Package Manager Console and type:
Install-Package NuxeoClient –Pre
and you are good to go!
If on the other hand, you are developing for ASP.NET 5 on .NET Core, you have to add the “NuxeoClient” dependency to your project.json file. It will look something like this:
{
…,
"dependencies": {
…,
"NuxeoClient": "1.0.0-*"
},
…
}
Then, you should download the missing dependencies by running:
dnu restore
In this case, you should have .NET Core installed in your system, which will provide you the dnu command. Here are installation instructions for Linux, Mac OS and Windows.
Creating a Client
First of all, include a reference to the NuxeoClient namespaces in your .cs file:
using NuxeoClient;
using NuxeoClient.Wrappers;
Now, let’s create a new instance of NuxeoClient, assuming we have local Nuxeo server running with default authentication credentials:
Client client = new Client("http://localhost:8080/nuxeo/",
new Authorization("Administrator",
"Administrator"));
Of course, the defaults can be omitted and we can end up with a much simpler instruction that does exactly the same:
Client client = new Client();
We can also add a default schema, which will be used on every request from now on:
client.AddDefaultSchema("dublincore");
We are now ready to issue requests to the server.
Common Operations
Here I will cover some of the most common operations that can be performed with the Nuxeo .NET Client.
CRUD: Create Document
You can create documents via REST API. Let’s create a folder in the root named “folder”:
Document folder = (Document)await
client.DocumentFromPath("/")
.Post(new Document
{
Type = "Folder",
Name = "folder",
Properties = new Properties
{
{ "dc:title", "A Folder" }
}
});
This new “folder” will be our testbed henceforth.
CRUD: Update Document
Want a different title for that folder? Here’s how you can change it:
Document folder = (Document)await folder.Put(new Document
{
Properties = new Properties
{
{ "dc:title", "new title" }
}
});
CRUD: Create a Child Document
This is how you can create a file inside a folder:
Document file = (Document)await folder.Post(new Document
{
Type = "File",
Name = "TestFile1",
Properties = new Properties { { "dc:title", "File 1" } }
});
Adapters: Getting Child Documents
Getting a document’s children can be achieved by using the @children adapter. This is how you can do it with the Nuxeo .NET Client:
Documents children = (Documents)await folder
.SetAdapter(new ChildrenAdapter())
.Get();
The Documents object encapsulates the respective JSON object with “entity-type”: “documents”. As such, it contains an Entries property, which represents a collection of Document objects. For example, checking for the number of children can be achieved with:
children.Entries.Count
From now on, every request to folder will be sent through the adapter. We can reset it with:
folder.SetAdapter(null);
Content Enrichers: Getting ACLs
Getting users’ permissions to read and write on a document can be conveniently achieved with enrichers:
Document folderWithAcls = (Document)await folder
.AddContentEnricher("acls")
.Get();
The ACLs can then be retrieved from the document’s ContextParameters with:
document.ContextParameters["acls"]
Batch Upload
The Nuxeo .NET Client provides an uploader that eases the task of uploading files. Let’s create a new instance of the Uploader which will upload files in chunks of 1kB:
Uploader uploader = client.Uploader()
.SetChunked(true)
.SetChunkSize(1024);
Now, let’s upload two files, “Test.txt” and “Puppy.docx”, to the server:
Entity result = await uploader.AddFile("Test.txt")
.AddFile("Puppy.docx")
.UploadFiles();
Batch Operation
We just uploaded two files to a batch, but they are not yet associated to any document. We would like to have them imported as children of our favorite folder. To do so, let’s perform a FileManager.Import operation on the whole batch, i.e., apply it to every document in it:
Documents documents = (Documents)await uploader
.Operation("FileManager.Import")
.SetContext("currentDocument", folder.Path)
.Execute();
CRUD: Delete Document
Now that we are done with it, we won’t need our beloved folder anymore. Let’s delete it:
folder.Delete();
More on GitHub
In this post we just scratched the surface of what you can do with the Nuxeo .NET Client. Make sure you check its GitHub repository for more details, examples and documentation. 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.
Nuxeo .NET Browser