Introducing Couchbase .NET 2.4.0 – .NET Core GA

This release is the official GA release for .NET Core support for the Couchbase .NET SDK! .NET Core is the latest incarnation of the .NET framework and its described as “.NET Core is a blazing fast, lightweight and modular platform for creating web applications and services that run on Windows, Linux and Mac”

Wait a minute…read that again: “.NET Core is a blazing fast, lightweight and modular platform for creating web applications and services that run on Windows, Linux and Mac“. Microsoft .NET applications running on OSX and Linux? What kind of bizzaro world are we living in? It’s the “New” Microsoft for sure!

In this blog post, I’ll go over what is in the 2.4.0 release, changes to packaging (NuGet), and what version of .NET the SDK supports. We’ll also demonstrate some of the new features such as Datastructures.

What’s in this release?

2.4.0 is a large release with over 30 commits. When you consider that we released 3 Developer Previews leading up to 2.4.0, there are actually many, many more commits leading up to this release over the last 6 months. Here is an overview of some of the more impressive features – you can see all of the commits in the “Release Notes” section below:

.NET Core Support

Of course the most significant feature of 2.4.0 is .NET Core support, which from the opening paragraph, means you can now develop on Mac OS or Windows and deploy to Linux (or vice-versa, but the tooling is a bit immature still). This is great stuff and a major change for the traditional Windows developer.

If you’re unaware of .NET Core, you can read up more about it over on the .NET Core website. One cool thing about it is that it’s open source (Apache 2.0) and source is all available on Github.

The Couchbase SDK specifically supports the netstandard1.5 or greater. We tested the SDK using 1.0.0-preview2-1-003177 of the Command Line Tools.

Packaging changes

Just like the three developer previews, the NuGet package will contain binaries for both the .NET Full Framework (targeting .NET 4.5 or greater), but also for .NET Core (targeting .NET Core 1.1). Depending on the target project you are including the dependency for, the correct binaries will be used.

So, if your Visual Studio project is a .NET Full Framework application greater than or equal to 4.5, you’ll get the binaries for the full framework version of .NET. Likewise, if your application is a .NET Core application, then the .NET Core version of the binaries will be used. There should be nothing you have to do to enable this.

The older .NET 4.5 version of the packages will no longer be released; 2.3.11 is the last supported release of the 2.3.X series.

MS Logging for Core

For .NET Core we decided to change from using Common.Logging to MS Logging mainly because no 3rd party (log4net for example) have stable support for .NET Core at this time.

Additionally, by moving from Common.Logging  to MS Logging we have removed one more 3rd party dependency – which is always nice. Not that Common.Logging wasn’t sufficient, but it makes more sense to use a dependency from Microsoft.

Here is an example of configuring the 2.4.0 client targeting .NET Core and using NLog:

First add the dependencies to the project.json:

Then, add a nlog.config file to your project with the following contents:

Finally, add the code to configure the Couchbase SDK for logging:

Note that the project.json has a copyToOutput.include  value for nlog.config . This is required so the tooling will copy that file to the output directory when built.

Now for the .NET 4.5 Full Framework binaries, the dependency on Common.Logging remains and any existing logging configuration should work as it always has.

Datastructures

Datastructures are a new way of working with Couchbase documents as if they are a common Computer Science data structures such as lists, queues, dictionaries or sets. There are two implementations in the SDK; one as a series of methods on CouchbaseBucket  which provide functionality for common data structure operations and another as implementations of the interfaces within System.Collections.Generics . Here is a description of each Datastructure class found in the SDK:

• CouchbaseDictionary<TKey, TValue> : Represents a collection of keys and values stored within a Couchbase Document.
• CouchbaseList<T> : Represents a collection of objects, stored in Couchbase server, that can be individually accessed by index.
• CouchbaseQueue<T> : Provides a persistent Couchbase data structure with FIFO behavior.
• CouchbaseSet<T> : Provides a Couchbase persisted set, which is a collection of objects with no duplicates.

All of these classes are found in the Couchbase.Collections  namespace. Here is an example of using a CouchbaseQueue<T> :

Multiplexing IO

The Couchbase SDK has used connection pooling in the past to allow high throughput and scale at the cost of latency and resource utilization. In Couchbase 2.2.4 we introduced a better IO model call Multiplexing IO or MUX-IO, which the client could be configured to use (the default was pooled connections).

In 2.4.0 we are making MUX-IO the default IO model and making connection pooling optional. What this means to you is that some connection pooling properties in your configuration may still be used SDK. For example:

• PoolConfiguration.MaxSize  is still used but should be relatively small values – e.g. 5-10
• PoolConfiguration.MinSize should be 0 or 1

To disable MUX-IO it’s simply a matter of setting the  ClientConfiguration.UseConnectionPoolingto true (the default is false) to use connection pooling:

Streaming N1QL and Views

Streaming N1QL and Views are a performance optimization in certain cases where the amount of data retrieved is large. To understand why, let’s consider how non-streaming queries work:

1. A request is dispatched to the server.
2. The server does it’s processing and returns back the results as a stream after processing the entire response.
3. The client buffers the entire stream and then de-serializes the stream into a collection of type “T”, where T is the POCO that each result is mapped to.
4. The server returns back the list to the application within its IResult

What can go wrong here? Think about very large results and that memory resources are finite: eventually you will always encounter an OutOfMemoryException ! There are other side effects as well related to Garbage Collection.

With streaming clients the process is as follows:

1. A request is dispatched to the server
2. The server does it’s processing and returns back the results as a stream as soon as the response headers are available.
3. The client partially reads the headers and meta-data and then pauses until iteration occurs.
4. When the application starts iterating over the IResult , each item is read one at a time without storing in an underlying collection.

The big benefit here is that the working set of memory will not grow as the collection grows and internally re-sized by .NET. Instead, you have a fixed working size of memory and GC can occur as soon as the read object is discarded.

To use streaming N1QL and views, all that you do is call the UseStreaming() method and pass in true to stream:

Passing in false will mean that the entire response is buffered and processed before returning.

N1QL Query Cancellation

This feature allows long running N1QL queries to be canceled before they complete using task cancellation tokens. For example:

This commit was via a community contribution from Brant Burnett of CenteredgeSoftware.com!

Important TLS/SSL Note on Linux

There is one issue on Linux that you may come across if you are using SSL: a PlatformNotSupportedException will be thrown if you have a version of libcurl installed on the server < 7.30.0. The work-around is to simply upgrade your libcurl installation on Linux to something equal to or greater than 7.30.0. You can read more about this on the Jira ticket: NCBC-1296.