This article was originally written by Jeff Morris
At long last, we present the official Developer Preview 1 (DP1) for the Couchbase .NET 2.0 SDK! Previously, I posted about some of the motivation behind rewriting the Couchbase .NET SDK and also some of the goals and features you should expect to find in it. This DP1 represents the minimal subset of features promised and should give you a feel for the direction we are taking the API from a developer’s perspective. In this post, I’ll show you how to get up and running with a preview of the new client and show off some of these features.
Warning: Do not use the DP1 in production!
Unless of course you enjoy running with scissors and sleepless nights debugging production issues is your forte’!
Seriously folks, this should be considered a very early pre-release and between now and the final GA lots of changes internally and externally are expected. That being said, the public interfaces will likely not change too much, with the exception of additional methods and functionality being added.
A couple of pre-requisite are required to get up and running with the DP1:
- You have a local instance of Couchbase Server 2.5 or greater installed and running. If not, go and do that now: http://www.couchbase.com/download
- You have N1QL Developer Preview 3 installed and running. If not go get that as well: http://www.couchbase.com/communities/n1ql
- Visual Studio 2013 installed. VS2012 will probably do as well, or one of the Express versions: http://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx, but I haven’t tested them so you’re on your own ;)
- Now, go download the bits from here.
Ok, got everything installed? Cool, let’s write some code*!
*If you wish to follow along as a tutorial, start VS2013 and create a Console Application called Couchbase.NetDP1 and add references to the binaries from the last bullet-point above. The final solution/project is also available here.
The Cluster object represents the client side representation of a Couchbase Server Cluster and provides interfaces for interacting with Couchbase Buckets and the Management API’s. Internally it manages the connectivity between the client and the server and ensures that resources are allocated and de-allocated correctly.
The Cluster class is a GOF Singleton with lazy-loaded behavior; it is that a single instance should be used across all threads within a process. This is a big change from the previous 1.X client which, while it wasn’t a singleton, for performance reasons, needed to be treated like a singleton.
In order to use the Cluster object, you first need to initialize it. By default, the configuration is set to use localhost (127.0.0.1) and create a connection pool with a MaxSize of 2 and a MinSize of 1 TCP connection per Cluster object. You can override these defaults by creating your own ClientConfiguration object and passing that to the Cluster.Initialize(…) method before calling Cluster.Get().
The ClientConfiguration class also allows you to override configuration at the Bucket level, which allows you to create a separate configuration for each Bucket you wish to use.
The CouchbaseBucket Object
Besides the Cluster object, the another important class is the CouchbaseBucket class, which provides an API for querying Views, performing N1QL queries and doing general CRUD operations on keys. It also performs any necessary serialization/deserialization of Types and manages key hashing across the cluster for a set of keys. The CouchbaseBucket class, implements the IBucket interface and has a cousin for working with in-memory Memcached Buckets: MemachedBucket. Both are supported in this DP.
In order to use the CouchbaseBucket class, you need an initialized Cluster object (see above) and you also need the Bucket to already exist within the Couchbase Server instance or cluster. Here is an example of opening the “default” Bucket which comes with every Couchbase install:
Once you have a Bucket instance, you can start performing CRUD operations on documents and the Bucket. Please note in DP1, only inserting and reading of documents is supported. Here is an example of the new Insert method:
And here is an example of using Get(key) to retrieve the documents inserted into the default bucket using the code above:
Once you are done using a Bucket, you simply release back to the Cluster object:
The Cluster object itself implements IDisposable, so when the process that is using it terminates, the Dispose method should be called. If it’s not called explicitly, the GC will invoke the finalizer at some point in time later, implicitly call Dispose and cleaning up the internal resources.
The IOperationResult<T> Object
Most of the methods return an IOperationResult<T> object that provides additional information regarding the results of the operation. Most notable, it has the following properties:
- Value – the object or value being inserted or returned from Couchbase – this is the Type T
- Success – a Boolean value indicating whether or not the operation succeeded or not
- Message – a string value with additional information regarding why the operation failed (if it did), otherwise it’s empty.
- ResponseStatus – the value returned from the server indicating status of the operation.
- Cas – a unsigned long that is the “Check and Set” value for the operation. This is used as a means of optimistic concurrency.
A fairly typical pattern is to check the Success property and alter program flow accordingly if an error was detected.
This developer preview also provides basic support for ad-hoc N1QL queries! If you’re not aware of what N1QL is, it’s a SQL like language for querying documents in Couchbase Buckets. Here is an example:
Please note that you must have Developer Preview 3 for N1QL installed and running for this to work! You can get it here: http://www.couchbase.com/communities/n1ql
View querying is also supported in developer preview 1. Assuming you have beer-sample installed (you can install it from the Couchbase Server Management Console under the Settings->Samples tabs), the following query should work:
CreateQuery method create an IViewQuery interface, which allows a Couchbase View REST URI to be generated. It’s a “fluent-style” interface, so you can chain together a series of calls to create the right query for your use-case.
We are expecting to have at least one more developer preview before we release beta and a GA can be expected around mid-to-late summer 2014 (no date is set, so this may change!). From a public facing perspective, the public interfaces discussed here are likely to change a bit, primarily to make them more consistent and easier to use. That being said they are fairly baked, pending feedback from the developer community (we are listening to you!).
What you will likely see in the next developer preview are support for all or most of Couchbase CRUD operations (Increment/Decrement, observe, etc) and support for TAP (await/async) after that you will more emphasis on performance and internal stability. Further down the line, you will see LINQ support for N1QL queries and SSL support
We Need Your Feedback!
Yes, you! Go ahead and play with the bits and let us know what you think. If you find a bug or have a feature request, you can create a Jira ticket here: http://www.couchbase.com/issues/browse/NCBC