Platform Introduction

  • tutorial
    Discover how to get up and running developing applications with the Couchbase .NET SDK 3.0+ using Visual Studio Code.

    A simple .NET orientation intro for non-.NET folk who are evaluating the Couchbase .NET SDK.

    Is This Page for You?

    This page is to help evaluate the Couchbase .NET SDK, if .NET is not where you spend the majority of your working day. It is aimed at Software Architects, QE folk, managers, and anyone else who needs to run through using the .NET SDK without necessarily being comfortable with C# and the .NET environment. If this is not you, head back to the rest of the Couchbase .NET SDK documentation.

    Installing .NET SDK Core

    This is required if you are using VSCode. (If instead you install a full IDE like Visual Studio or Jetbrains Rider instead, a .NET SDK will be installed by default.)
    • Start at the download page

    • Windows and Macintosh will run an installer, for Linux you will have to navigate to specific instructions for your distro.

    • We currently recommend the latest .NET 5.0, and our sample code will generally target this.

    • You may prefer to use the LTS (Long Term Support) version .NET Core 3.1., or an earlier version as used in your organization.

    • You can install multiple SDKs, to be able to run code targeting different versions. Use the dotnet command to list which versions are available. Here’s an example output with 5.0 and 3.1 SDKs installed:

    ❯ dotnet --list-runtimes
    Microsoft.AspNetCore.App 3.1.16 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
    Microsoft.AspNetCore.App 5.0.3 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
    Microsoft.NETCore.App 3.1.16 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
    Microsoft.NETCore.App 5.0.3 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
    ❯ dotnet --list-sdks
    3.1.410 [/usr/local/share/dotnet/sdk]
    5.0.103 [/usr/local/share/dotnet/sdk]

    If you’re just starting with .NET or C# then is a great starting point into the ecosystem.

    Using a Code Editor (Visual Studio Code)

    Visual Studio Code is a free code editor which runs on Windows, Linux and MacOS and can be downloaded here. Once downloaded, follow the installation details for the relevant platform:

    we’ve given instructions for VS Code as it’s a currently popular, cross-platform, multi-language editor that’s seeing widespread use, and is easy to set up and get started. If you’re planning to primarily develop in C#, you may prefer to look into using a full IDE like Visual Studio (the 2019 Community edition and the Mac edition are both free) or Jetbrains’s Rider.

    Adding C# Development Support

    VSCode is a flexible editor, with support for various programming languages. Though basic syntax highlighting for .NET languages is included in the box, you’ll find it useful to add an extension with support for development — debugging, discovery, and navigation — in your chosen programming language.

    For .NET, we suggest using ms-dotnettools.csharp, "C# for Visual Studio Code (powered by OmniSharp)" by Microsoft, which facilitates development in C#, the most commonly used .NET language.

    1. You can install from within VSCode itself:

      • Open VSCode

        • When you first open a C# project, you will be auto-prompted to install the recommended package.

        • Alternatively, select the Extensions button on the left hand side.

        • Type ms-dotnettools.csharp into the Search Extensions in Marketplace textbox and hit enter.

        • Select and install the language extension into the editor.

    2. Alternatively, use the VSCode marketplace:

    Adding the code command

    If you work from the command-line, you’ll want to add the code command to allow you to edit a file directly.

    In VSCode, View the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and search for Shell command: Install 'code' command in PATH and press Enter.

    You can now type code MyExample.cs to open a single file in VSCode, or code . to view the current directory.

    Creating a project

    An increasingly common way of setting up projects, building, and running code, is by using the dotnet executable that is installed along with the .NET SDK.

    In the following example, we’ll open our terminal, make a new directory, set up a bare-bones "console" project, install the Couchbase client library, and run the scaffolding code.

    $ mkdir CouchbaseExample
    $ cd CouchbaseExample
    # create a basic "console" application
    $ dotnet new console
    $ dotnet run
    Hello World!
    $ dotnet add package CouchbaseNetClient
    $ ls
    $ cat CouchbaseExample.csproj
    <Project Sdk="Microsoft.NET.Sdk">
        <PackageReference Include="CouchbaseNetClient" Version="3.2.0" />
    $ code Program.cs

    You should see a Hello World message printed in your terminal, which means the application has run successfully.

    Now you can launch VSCode and open the CouchbaseExample directory to start editing the Program.cs file.

    Running Couchbase examples

    As you read through the docs, you will see that many code examples link to the .NET SDK docs Github repository. If you wish to run those examples to try things out for yourself, you can clone this repository and run the examples in any directory that contains a .csproj file:

    $ dotnet run

    You can read the .csproj file to check which external libraries (such as the Couchbase SDK) are included.

    Some examples have been tweaked to use dotnet script, which allows you to run a single .csx file from the command-line, without the full overhead of the project/solution wrapper. This is an extension, so you will have to install it first.

    $ dotnet tool install -g dotnet-script
    $ dotnet script modules/howtos/examples/EncryptingUsingSdk.csx

    Next steps

    That’s it! You are now ready to start developing your Couchbase application.