This codebase was created to demonstrate a fully fledged fullstack application built with ASP.NET + Couchbase including CRUD operations, authentication, routing, pagination, and more.
I've gone to great lengths to adhere to the ASP.NET and Couchbase community styleguides & recommendations.
For more information on how to this works with other frontends/backends, head over to the RealWorld repo.
This is a Conduit backend implementation for the RealWorld project. It is meant to be a working reference implementation.
The code is meant to be readable, and simple enough to follow along. If you can't, please create a GitHub issue, so the problem can be addressed!
You'll need to understand at least a little bit:
- .NET 8
- C#
- ASP.NET Core - web framework for .NET
- Couchbase Capella (or Couchbase Server) - NoSQL database
- Mediatr
- Other good things to understand: BCrypt, NUnit, TestContainers.net, JSON serialization, REST APIs, dependency injection, SQL
-
Conduit.Web - This is the most important project. It's where the actual implementation is. The project is "sliced" by feature as much as possible. That is, grouping together objects with common functionality.
- DataAccess folder - this is where data access objects are kept. These objects are used only for database interaction. There are also some VSCode Notebooks for the queries that are used in the project (uses the Couchbase VSCode Extension).
- Sliced folders - these contain ASP.NET Core Controller(s), Mediatr request, response, and handler classes, viewmodels, and services for the functionality of the slice.
- Users - Authorization/authentication, JWT, registration, login, anything for Users
- Follows - Follow/unfollow
- Articles - Articles, favorites, comments, and tags for articles
- Extensions folder - extension methods for ASP.NET functionality
-
Conduit.Tests - Automated tests for Conduit.Web.
- Unit folder - this is where unit tests live. The folder structure within mirrors the Conduit.Web folders as much as possible.
- Integration folder - this is where integration tests live. The folder structure within mirrors the Conduit.Web folders as much as possible.
- Functional folder - this is where tests for controller actions that test all the way from request-to-database-to-response. The folder structure within mirrors the Conduit.Web folders as much as possible.
- Extensions folder - this is for tests of base level extensions in the Conduit.Web project
- TestHelpers folder - various helpers to make test writing faster and more readable. Data helpers are for helpers for objects used directly by the data layer. Dto folder is for Handler and ViewModel DTO helpers.
-
Conduit.Migrations - Automated creation of database structures. This project uses NoSqlMigrator (see below).
This Conduit implementation is being streamed live on Twitch. You can follow along with the recordings on YouTube.
- Create a Couchbase Capella account / database, or install Couchbase Server (both community and enterprise edition will work).
- Configure Couchbase
- Create a "Conduit" bucket
- Enable database access
- Capella: Create Database Access with read/write permission to all collections in the Conduit bucket
- Couchbase Server: Create a user with read/write permission (key-value, query) to all collections in the Conduit bucket. (Or if you aren't in production, use the admin credentials)
- Run the migrations in the Conduit.Migrations project (see NoSqlMigrator).
- (Manual alternative to step 3) Create the database objects collections, indexes, documents, indexes as described in the comments of the classes of the Conduit.Migrations project.
- Configure Conduit.Web, Conduit.Tests and Conduit.Migrations
- Add User Secrets to Conduit.Tests, Conduit.Web, and/or Conduit.Migrations, following secrets.json.template examples
- Compile and run Conduit.Web
- Standard compile/run from command line/VSCode/Visual Studio/Rider should work fine
- You can use Postman to exercise the endpoints. RealWorld has a Postman collection available for your convenience (which is currently checked into this repo, but beware--if you have issues, fall back to the official one).
- You can also use the generated SwaggerUI to exercise the endpoints.
I have included a small set of data that you can load into Couchbase with cbimport if you want.
Note that the fields _dockey, _scopeName, and _collectionName are only for use with import, and can be removed once the data is loaded into a Couchbase bucket.
For each user in this seed data, every password is "StrongPassword01!".
Here's an example command to import seeddata.json:
> & 'C:\Program Files\Couchbase\Server\bin\cbimport.exe' json -c localhost -b Conduit -d file://seeddata.json -f list -u Administrator -p password --scope-collection-exp %_scopeName%.%_collectionName% --generate-key %_dockey% --ignore-fields _collectionName,_dockey,_scopeName
This will vary based on where cbimport is installed, which operating system you're using, your credentials, etc. The above example uses PowerShell on Windows, with Couchbase Server installed.
The creation of this implementation of Conduit is being done (mostly) on a live coding stream. Here are all the recordings:
An overview of the goals of this project and the Real World Conduit project, featured on the On .NET Live show: https://www.youtube.com/watch?v=DGrPQqyOpcU