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.
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:
- [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
- [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:
- Install the Couchbase ASP.NET Integration package from NuGet
- Configure the Couchbase .NET SDK to use your cluster
- 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
CouchbaseClientSectionyou 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:
Install-Package CouchbaseAspNet -Pre
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:
<section name="couchbase-session" type="Couchbase.Configuration.Client.Providers.CouchbaseClientSection, Couchbase.NetClient" />
In this case we are defining a
"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
Bucket objects that the session provider will use. In this case we have two URI's
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
3. Configure the custom Session Provider
In your Web.Config, insert the following:
<sessionState customProvider="couchbase-session" mode="Custom">
<add name="couchbase-session" type="Couchbase.AspNet.SessionState.CouchbaseSessionStateProvider, Couchbase.AspNet"
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!