Couchase ASP.NET Integration Beta 3 released!

Today we pushed Beta 3 of the Couchbase ASP.NET Integration packages to NuGet! Formally known as Couchbase Caching and Session providers, this project contains or will contain implementations of various API’s (Caching/Session providers, Identity, etc) for integration between Couchbase Server and Microsoft ASP.NET. Eventually support for .NET Core will likely be added, but that is some time out after the .NET SDK supports it.

Breaking Changes

First up, unfortunately there are a couple of breaking changes between Beta 2 and Beta 3. In the previous beta, we used the ClusterHelper object to manage the scope/lifetime of the Cluster and Bucket objects used by the Session Provider. This worked well, but with the ClusterHelper, you are limited to opening one Couchbase Server cluster per application. In most scenarios, this is ok – a cluster can have multiple buckets and you can open them via GetBucket. In some cases, however, you may have an application which opens buckets from multiple clusters. With Beta 3, we went back to opening and scoping the Cluster and bucket to the instance of the Caching or Session provider. This means you can configure buckets in different clusters for your Caching and Session provider instances.

In order to do this, the ClusteHelper was removed (along with requiring that you initialize it in the Global.asax or Setup.cs classes) and the configuration was re-factored. So, unfortunately, its not a drop in replacement for Beta 2. To see the “new” way of configuring, see the “How to use it” section below.

What’s in Beta 3?

Note that issues are tracked in Jira – if you encounter a bug or want to request a feature, you can do so there. Here is a list of tickets that were resolved for Beta 3:

Bug

• [CBASP-1] – Couchbase session state provider does not works with WebForm project
• [CBASP-14] – AspNet not throwing error when comment says it should
• [CBASP-16] – AspNet attempts to reference data in an error condition
• [CBASP-21] – System.ArgumentNullException with ASP.NET Session Management

Improvement

• [CBASP-17] – Update NuGet packages to Couchbase.NetClient 2.2.5
• [CBASP-18] – Add Couchbase.AspNet.UnitTests project
• [CBASP-19] – Update dependencies on Common.Logging and JSON.NET
• [CBASP-23] – Refactor initialization and setup/configuration

How to use it

Note that I am assuming you have already created a Couchbase Cluster with two nodes and a Memcached bucket called "my-memcached-bucket". If you haven’t done this, go now and do this.

Once you have your configuration setup for the Couchbase SDK (from the last steps), you’ll need to do three things:

1. Install the Couchbase ASP.NET Integration package from NuGet
2. Configure the Couchbase .NET SDK to use your cluster
3. Configure your ASP.NET project to use the custom Session provider from the Couchbase ASP.NET Integration package and configure the custom session provider to use the CouchbaseClientSection you defined in step 1.

1. Install Couchbase ASP.NET Integration package from NuGet

Create or open an ASP.NET MVC project using Visual Studio. Click “Tools”, “NuGet Package Manager” and then “Package Manager Console” from the main menu bar. Then type the following:

This will install the Couchbase ASP.NET Integration Package along with all dependencies that are needed (Couchbase .NET SDK, etc).

2. Configure the Couchbase .NET SDK

The Caching and Session providers require configuration via App.Config or Web.Config (JSON configuration ala .NET Core 1.0 is not yet supported, but will be soon!). The first thing you’ll need to do is add the configuration support for initializing the cluster and bucket objects. This is done via the Couchbase SDK Configuration API like so:

In this case we are defining a CouchbaseClientSection called "couchbase-session" at the top of our App.config or Web.config and then providing the actual configuration section and the configuration we intend to use for the Cluster and Bucket objects that the session provider will use. In this case we have two URI’s http://a-couchbase-server1:8091/ and http://a-couchbase-server2:8091/ that we will use to bootstrap from. We also have a bucket configuration defined that will open the Memcached bucket called "my-memcached-bucket".

3. Configure the custom Session Provider

In your Web.Config, insert the following:

This will tell ASP.NET to use the custom session provider that comes from the Couchbase ASP.NET Integration project instead of the default, in-memory one. Also very IMPORTANT note that name of the custom provider is the same name ("couchbase-session") as the CouchbaseConfigurationSection you defined earlier and that the value of the bucket element is the name ("my-memcached-bucket") of the bucket you will use.

Once this is done, run your application and instead of using the default in-memory session store, ASP.NET will use the highly scalable, distributed Couchbase server!

Addendum

1. Github project is here.
2. File a bug or request a feature here.
3. Ask a question on our forums here.