Jeff Morris already wrote a great blog post to introduce the Couchbase .NET Core SDK, which is now in developer preview.
I’m going to show you some of the tooling that I’m using to write .NET Core on Windows: Visual Studio Code with NuGet and other extensions.
Getting Started
Here’s what I’m using on Windows, but note that this shouldn’t be much different on Mac or Linux!
- Install .NET Core
- Install Visual Studio Code (VSC) — this is optional, but it is a great tool, and it’s free!
Once you have Visual Studio Code installed, I recommend that you install these extensions:
- C# (powered by OmniSharp) – this will give you some of the normal C# features you expect if you’ve used Visual Studio with .Net Core before: syntax highlighting, IntelliSense, and so on.
- .Net Core NuGet Project Manager
You can install these extensions right in Visual Studio Code using the UI, or you can use Ctrl+P and then type ext install net-core-project-manager or ext install csharp. Keep Ctrl+P in your mind, because once you have the NuGet Project Manager installed, you will also use it to install a NuGet package in Visual Studio Code.
Let’s write some code
Use Powershell or CMD to make a project folder. Once you are there:
dotnet new
This will create some files: Program.cs and project.json.
Then, to get the dependencies listed in project.json, run another command:
dotnet restore
You might now notice a project.lock.json file. This is generated by NuGet to figure out the dependency graph. You don’t need to commit this to your source code repository, and I’ve omitted it from the source code for my example.
Now, I’m going to open up this folder in Visual Studio Code by running:
code .
At this point, the project is ready to execute. You can go back to Powershell/CMD if you’d like, or you can use Ctrl+` to use the Integrated Terminal within VSC. To run the program:
dotnet run
If you ran that now, you’d get a “Hello World”. Let’s add some Couchbase to this project.Start with Ctrl+P, then type “>nuget” until “Add New Package” appears. Enter a search term, like “couchbase”. “CouchbaseNetClient” should appear in the list. Select it, and then you should be able to select a version.
Currently, for .NET Core, you’ll need to select 2.4.0-dp2, since .NET Core support is still a “developer preview”.
Once you have this added to your project, working with the .NET Core SDK should be familiar to you if you’ve used the .NET SDK. Inside of the Main method, here’s how you connect to a cluster and setup a bucket:
|
1 2 3 4 5 |
// connect to a cluster, get a bucket ClusterHelper.Initialize(new ClientConfiguration { Servers = new List { new Uri("couchbase://localhost")} }); var bucket = ClusterHelper.GetBucket("default"); |
Next, I’m inserting an “electric bill” document using the bucket object. Note that I’m using the Async method. According to Jeff’s blog post, the synchronous API may be going away, so I’m trying to get used to the asychonous API. I’m using Task.WaitAll, so it’s still running synchronously for the purposes of this sample console app.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
// insert a document with some random values var document = new Document { Id = Guid.NewGuid().ToString(), Content = new { invoiceNumber = Path.GetRandomFileName(), amountDue = new Random().Next(10,300), type = "electricbill" } }; Task.WaitAll(bucket.InsertAsync(document)); // wait for async method to finish Console.WriteLine("New electric bill created."); Console.WriteLine(); |
Next, I’m executing a parameterized N1QL query with RequestPlus consistency to list all of the electric bills.
|
1 2 3 4 5 |
// get all electric bills with N1QL and list them var query = Couchbase.N1QL.QueryRequest.Create("SELECT b.* FROM `default` b WHERE type = $1"); query.AddPositionalParameter("electricbill"); query.ScanConsistency(ScanConsistency.RequestPlus); var result = bucket.QueryAsync(query).Result; // calling QueryAsync synchronously |
Again, this is using the Async API, but since I’m calling .Result, it’s functionally synchronous. Finally, based on the results of the N1QL query, I’m either outputting error information or I’m looping through the results and writing them to console.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
Console.WriteLine("Success: " + result.Success); if(!result.Success) { Console.WriteLine("Message: " + result.Message); Console.WriteLine("Exception: " + result.Exception?.GetType().Name); Console.WriteLine("Exception Message: " + result?.Exception?.Message); result.Errors.ForEach(e => Console.WriteLine("Error: " + e?.Message)); return; } Console.WriteLine(); Console.WriteLine("Bills:"); Console.WriteLine("------"); foreach(var bill in result.Rows) { Console.WriteLine($"{bill.invoiceNumber} - {bill.amountDue.ToString("C")}"); } |
When I run this program, it will create a new document (each time) and list all the documents it’s created cumulatively.
Note: if you are having trouble getting started with Couchbase Server, or you are getting errors, especially in regards to N1QL indexing, you may want to revisit some of my “Getting Started” blog posts: Couchbase with Windows Part 1 and Couchbase with Windows Part 2 in particular.
What’s different?
For the most part, this feels very much like working with full Visual Studio and .NET. Visual Studio Code is not as full-featured, yet, but already has a great library of extensions. For Couchbase developers, working with the .NET Core SDK is practically identical.
One thing that it may take some time to get used to is the lack of ReSharper. I don’t know if ReSharper is going to come to VSC (JetBrains has their own light-weight C# IDE called Rider). I have a habit of using Alt+Enter to add using statements, and that same keyboard shortcut doesn’t work in VSC (by default). The refactoring lightbulbs still show up, and here are the namespaces for the record:
|
1 2 3 4 5 6 7 |
using System; using System.Collections.Generic; using System.IO; using System.Threading.Tasks; using Couchbase; using Couchbase.Configuration.Client; using Couchbase.N1QL; |
It’s also a little strange to create a project with dotnet new instead of File→New, but that’s something I can get used to.
Summary
Even if you don’t plan on writing .NET Core code just yet, you should still check out Visual Studio Code. It’s a great text editor, if nothing else. If you are currently writing .NET with Couchbase, the Couchbase part of your transition to .NET Core should be painless (your mileage may vary getting used to the new .NET Core tooling).
What do you like or not like about VSC and .NET Core? Leave a comment below or let me know on Twitter. I’m @mgroves. If you are having any trouble with .NET, .NET Core, or Couchbase Server, I’m here to help you.
English