This repo is designed to teach you how to connect to a Couchbase cluster to create, read, update, and delete documents and how to write simple parametrized N1QL queries.
Full documentation can be found on the Couchbase Developer Portal.
To run this prebuilt project, you will need:
- Follow Couchbase Installation Options for installing the lastest Couchbase Database Server Instance
- .NET SDK v5 installed
- Code Editor installed (Visual Studio Professional, Visual Studio for Mac, or Visual Studio Code)
cd src/Org.Quickstart.API
dotnet restore
Note: Nuget packages auto restore when building the project in Visual Studio Professional 2019 and Visual Studio for Mac
The Couchbase SDK for .NET includes a nuget package called Couchbase.Extensions.DependencyInjection
which is designed for environments like ASP.NET that takes in a configuration to connect to Couchbase and automatically registers interfaces that you can use in your code to perform full CRUD (create, read, update, delete)
operations and queries against the database.
All configuration for communication with the database is stored in the appsettings.Development.json file. This includes the connection string, username, password, bucket name, colleciton name, and scope name. The default username is assumed to be admin
and the default password is assumed to be P@$$w0rd12
. If these are different in your environment you will need to change them before running the application.
With this tutorial, it's required that a database user and bucket be created prior to running the application.
For Capella users, follow the directions found on the documentation website for creating a bucket called user_profile
. Next, follow the directions for Configure Database Credentials; name it admin
with a password of P@$$w0rd12
.
Next, open the appsettings.Development.json file. Locate the ConnectionString property and update it to match your Wide Area Network name found in the Capella Portal UI Connect tab. Note that Capella uses TLS so the connection string must start with couchbases://. This configuration is designed for development environments only.
"Couchbase": {
"BucketName": "user_profile",
"ScopeName": "_default",
"CollectionName": "profile",
"ConnectionString": "couchbases://yourassignedhostname.cloud.couchbase.com",
"Username": "admin",
"Password": "P@$$w0rd12",
"IgnoreRemoteCertificateNameMismatch": true,
"HttpIgnoreRemoteCertificateMismatch": true,
"KvIgnoreRemoteCertificateNameMismatch": true
}
Couchbase Capella users that do not follow these directions will get exception errors and the Swagger portal will return errors when running the APIs.
For local installation and docker users, follow the directions found on the documentation website for creating a bucket called user_profile
. Next, follow the directions for Creating a user; name it admin
with a password of P@$$w0rd12
. For this tutorial, make sure it has Full Admin
rights so that the application can create collections and indexes.
Next, open the appsettings.Development.json file and validate the configuration information matches your setup.
NOTE: For docker and local Couchbase installations, Couchbase must be installed and running on localhost (http://127.0.0.1:8091) prior to running the the ASP.NET app.
At this point the application is ready and you can run it:
dotnet run
Once the site is up and running you can launch your browser and go to the Swagger start page to test the APIs.
To run the standard integration tests, use the following commands:
cd ../Org.Quickstart.IntegrationTests/
dotnet restore
dotnet test
This project was based on the standard ASP.NET Template project and the default weather controller was removed. The HealthCheckController is provided as a santity check and is used in our unit tests.
A fully list of nuget packages are referenced below:
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.3.0" />
<PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.3.0" />
<PackageReference Include="CouchbaseNetClient" Version="3.2.8" />
<PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
<PackageReference Include="Couchbase.Extensions.DependencyInjection" Version="3.2.8" />
Setting up a basic REST API in ASP.NET with Couchbase is fairly simple, this project when run with Couchbas that creates a collection, an index for our parameterized N1QL query, and showcases basic CRUD operations needed in most applications.