Couchbase Server Quickstart - ASP.NET Core First Query

    +
    Using the Couchbase .NET SDK in an ASP.NET Core application to create new database records in Couchbase and look them up.

    Prerequisite: Run Couchbase Server

    1. Couchbase Server 6.5 is already running.

      • An empty bucket named "default" has been created.

      • Both a primary index and an adaptive index have been created and built on the default bucket.

      • If you still need to perform these tasks please use the following:

    2. Visual Studio is installed. This tutorial uses Visual Studio 2019 16.5.

    3. .NET Core Runtime is installed. This tutorial uses .NET Core 3.1

    4. A tool to make HTTP requests (e.g. cURL or Postman).

    Step 1: Start a New Project in Visual Studio

    Open Visual Studio 2019 and create a new ASP.NET Core Web Application project.

    New Project dialog in Visual Studio 2019

    Name the project, "QuickStart".

    Select the API template.

    Template select in Visual Studio

    Install the latest Couchbase.Extensions.DependencyInjection package from NuGet. This will install both the Couchbase .NET SDK and a Dependency Injection extension for ASP.NET Core.

    This open-source project is part of Couchbase Labs, and is not commercially supported by Couchbase, Inc.

    You can do this via Visual Studio’s Package Manager Console like so:

    Install-Package Couchbase.Extensions.DependencyInjection -Version 2.0.2
    Alternatively, you can use the NuGet UI by right-clicking "Dependencies" in Solution Explore and then "Manage NuGet Packages".

    Step 2: ASP.NET Core Configuration

    There are two steps to configure your new ASP.NET Core application.

    First, add a "Couchbase" section to the appsettings.json file. If you’ve followed along with the 10-minute Couchbase Docker Container Configuration, then edit your appsettings.json file to add a Couchbase section as follows:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft": "Warning",
          "Microsoft.Hosting.Lifetime": "Information"
        }
      },
      "AllowedHosts": "*",
      "Couchbase" : {
        "Servers": [ "http://localhost:8091" ],
        "Username": "Administrator",
        "Password": "password"
      }
    }

    The next step is to setup Couchbase in Startup.cs.

    To do this, first add services.AddCouchbase(Configuration.GetSection("Couchbase")); to the ConfigureServices method. Make sure to close the connection as well. You can do this in the Configure method by adding an IHostApplicationLifetime parameter. Here is the complete Startup.cs:

    using Couchbase.Extensions.DependencyInjection;
    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.Extensions.Configuration;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Hosting;
    
    namespace QuickStart
    {
        public class Startup
        {
            public Startup(IConfiguration configuration)
            {
                Configuration = configuration;
            }
    
            public IConfiguration Configuration { get; }
    
            // This method gets called by the runtime. Use this method to add services to the container.
            public void ConfigureServices(IServiceCollection services)
            {
                services.AddControllers();
    
                services.AddCouchbase(Configuration.GetSection("Couchbase")); (1)
            }
    
            // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
            public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IHostApplicationLifetime appLifetime)
            {
                if (env.IsDevelopment())
                {
                    app.UseDeveloperExceptionPage();
                }
    
                app.UseHttpsRedirection();
    
                app.UseRouting();
    
                app.UseAuthorization();
    
                app.UseEndpoints(endpoints =>
                {
                    endpoints.MapControllers();
                });
    
                appLifetime.ApplicationStopped.Register(() => (2)
                {
                    app.ApplicationServices.GetRequiredService<ICouchbaseLifetimeService>().Close();
                });
            }
        }
    }
    1 Add Couchbase service to ASP.NET Core
    2 Dispose of Couchbase on ASP.NET Core shutdown

    At this point, your ASP.NET Core application is now configured to use Couchbase.

    Step 3: Create new documents

    Start by creating a simple "model" class to represent a user. (Right Click on the project → Add New Item → Class → User.cs)

    public class User
    {
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Email { get; set; }
        public string TagLine { get; set; }
        public string Type => "User";
    }

    Let’s create two controller actions. These will correspond to two API endpoints: one will create a document and one will query a document.

    Replace the WeatherForecastController with a UserController. Create a constructor in that controller which has an IBucketProvider parameter. Use the bucketProvider to get an instance of a Couchbase bucket: _bucket = bucketProvider.GetBucket("default").

    private readonly IBucket _bucket;
    
    public UserController(IBucketProvider bucketProvider)
    {
        _bucket = bucketProvider.GetBucket("default");
    }

    Use this bucket object to insert plain C# objects into Couchbase. They will be serialized into JSON and stored with a key: _bucket.Insert(key, user);. Create an InsertData POST method in UserController like so:

    [HttpPost]
    [Route("/")]
    public string InsertUser(User user)
    {
        var key = Guid.NewGuid().ToString();
        _bucket.Insert(key, user);
        return "Inserted user with ID: " + key;
    }

    Compile and run your ASP.NET Core program locally with CTRL+F5. Use cURL or Postman or the HTTP tool of your choice to create three POSTs with JSON content to the specified route. The body of the posts should look something like these:

    // first POST
    {
        "firstName" : "Major",
        "lastName" : "Tom",
        "email" : "major.tom@acme.com",
        "tagLine" : "Send me up a drink"
    }
    
    // second POST
    {
        "email": "perry.mason@acme.com",
        "firstName": "Perry",
        "lastName": "Mason",
        "tagLine": "Who can we get on the case?"
    }
    
    // third POST
    {
        "email": "jerry.wasaracecardriver@acme.com",
        "firstName": "Jerry",
        "lastName": "Wasaracecardriver",
        "tagLine": "el sob number one"
    }

    And example of a cURL command to make this request would be:

    curl --location --request POST 'https://localhost:44316/' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "firstName" : "Major",
        "lastName" : "Tom",
        "email" : "major.tom@acme.com",
        "tagLine" : "Send me up a drink"
    }'
    If you’re using Postman, you can copy and paste the above cURL command into Postman. (File→Import→Paste Raw Text) Please make sure your port number matches what Visual Studio has set.

    When the request is successful, the response will contain the generated ID:

    Inserted user with ID: d28a19d4-0c37-447f-b0c0-66a7f2af3c97

    Now there are three documents in the default bucket. Next, let’s query them back out.

    Step 4: Query the documents

    Open the Query Workbench in the Couchbase UI. Enter a query to select everything from the default bucket:

    SELECT d.*
    FROM default d

    You should see the inserted documents in the results:

    [
      {
        "email": "perry.mason@acme.com",
        "firstName": "Perry",
        "lastName": "Mason",
        "tagLine": "Who can we get on the case?",
        "type": "user"
      },
      {
        "email": "major.tom@acme.com",
        "firstName": "Major",
        "lastName": "Tom",
        "tagLine": "Send me up a drink",
        "type": "user"
      },
      {
        "email": "jerry.wasaracecardriver@acme.com",
        "firstName": "Jerry",
        "lastName": "Wasaracecardriver",
        "tagLine": "el sob number one",
        "type": "user"
      }
    ]

    Next, create a second controller action called GetUserByEmail in UserController.cs. This will be for an API endpoint to retrieve documents, given an email address, using a query like:

    SELECT d.*
    FROM default d
    WHERE d.email = "major.tom@acme.com"

    To execute a query in .NET, start by creating a query string with a named parameter for email: var n1ql = "SELECT d.* FROM default d WHERE d.email = $email";.

    Use the string with QueryRequest.Create(…​) to create a query object. Parameters and other settings can be supplied using this query object. Finally, use the _bucket object to execute the query.

    [HttpGet]
    [Route("/")]
    public List<User> GetUserByEmail(string email)
    {
        var n1ql = "SELECT d.* FROM default d WHERE d.email = $email";
        var query = QueryRequest.Create(n1ql);
        query.AddNamedParameter("$email", email);
        var result = _bucket.Query<User>(query);
        return result.Rows;
    }

    Compile and run your ASP.NET Core program locally with CTRL+F5. Use cURL or Postman or the HTTP tool of your choice to create a GET with a querystring variable of email with the specified email address. Example of a cURL request:

    curl --location --request GET 'https://localhost:44316/?email=major.tom@acme.com'
    Since this is a GET, you can make this request from a web browser instead.

    The body of a successful response should look something like this:

    [
        {
            "firstName" : "Major",
            "lastName" : "Tom",
            "email" : "major.tom@acme.com",
            "tagLine" : "Send me up a drink"
        }
    ]

    Done

    If you’ve written SQL before, the N1QL queries in this example should look familiar. Instead of querying a table, default is the name of a bucket.

    Be sure to check out the other quick start exercises. The complete source code is available on GitHub.