ASP.NET is a platform for building web APIs with C# and .NET. It’s commonly used for app backends, and can automatically serialize classes to JSON. We’ll walk through setting up a service that talks to a database and stores a list of objects.
Creating a Project
We’ll be using Visual Studio, as it provides great .NET support out of the box. Create a new project using the “ASP.NET Core Web Application” template:
Give it a name, and select “API,” as we’re not building a ASP.NET frontend here.
This will initialize your solution with all the boilerplate needed to get a basic API up and running. If you click the run button (labelled IIS Express, which starts an IIS web server), you’ll see the API displaying some dummy data about the weather.
We’ll use this base to set up a simple API that will connect to a database and read and write custom objects. In this case, it’s a collection of user data, but the API will largely work the same for more complicated entity models.
Connecting a Database
It’s a good idea to split up the logic of handling requests and the logic of handling talking to the database. We’ll create a database service with some functions for reading and writing, then an a API controller that will respond to requests by talking to the database service. The first thing to do, though, is get ASP.NET talking to a database in the first place.
We’ll need to install some packages for working with a database. Click on Tools > NuGet Package Manager, and select “Manage NuGet Packages For Solution.”
If you’re using a SQL database, the database connection is handled with specific plugin packages that implement EntityFrameworkCore for the underlying database. This is a framework that maps C# objects to a relational database, and allows you to use LINQ queries and other native tools to interact with it. You can find a full list of database providers here for most popular relational databases.
We’ll be going with MongoDB here, because NoSQL document databases translate to a List
Install the MongoDB.Driver package:
Create a new folder at the root of your project called “Models.” In it, create an entity model called User.cs, which will be the schema for the collection that gets stored in the database. You can use the [BsonId] and [BsonRepresentation(BsonType.ObjectId)] attributes to tell the MongoDB driver that this ID string should be interpreted as the collection ID, and can be passed as type string even though Mongo internally wants type ObjectId.
In this same folder, create a file called DatabaseSettings.cs, which will store a class and interface for the database settings.
We can populate these property values in appsettings.json, by adding the following configuration:
You will, of course, need to create or rename the Example database, as well as create the Users collection in it.
Finally, we will add some code in Startup.cs in the ConfigureServices method, which will fetch the settings from the appsettings.json file, and register the interface through Dependency Injection:
You will need to add a directive at the top using your Models namespace.
Writing a CRUD Database Service
Once the database is connected, you can add the service that will do the talking. The following class contains an IMongoCollection that represents the MongoDB collection in a format with which C# can easily interact. Reads, writes, updates and deletes will directly affect the underlying collection.
The constructor method takes the database settings, starts up a new client, fetches the database, then initializes the _users collection.
The rest of the class is simply a set of CRUD operations for interacting with the database. Feel free to implement any custom logic here.
Back in Startup.cs, you’ll want to add this as a service on startup:
You’ll again need another using directive, this time for ExampleService.Services.
Setting Up an API Controller
Next, you’ll need a controller to handle API actions. Luckily Visual Studio makes this easy; you can right-click on “Controllers” to add a new controller, with read/write actions. This will create a new controller with some basic methods.
The route is defined at the top. By default, this is set to /api/controller, where controller is the controller name (minus the “Controller” part). You can change this if you’d like, but this is a good pattern for most people.
You’ll want to add a reference to your database service at the top of the class, and populate it in the constructor:
You’ll want to change the HttpGet method to return an ActionResult<List
If you want to add another Get method, but on a different route, you can pass it as a parameter in the attribute:
Then for the HttpPost method, call the Create method of your database service, and return CreatedAtRoute, which will send a 201 response to the client informing them that the object creation was successful.
For the other routes, you can configure them how you’d like. The general idea is to handle the user input, perform any validations you need to, and call the proper database actions, returning the user a something useful or a status code telling them what happened.
At this point though, you should be able to hit the IIS Express run button at the top, and test the API. This will default the route to be the weather services API that came with the boilerplate, so rather than typing it out every time, you can change the debug route under Project > Properties > Debug and changing the Launch Browser option.
Once you want to test on a remote server, you can create a production build from Build > Publish Service. Select file output, and edit the configuration to suit your needs. For example, you can choose to build as self-contained, which will package all the .NET dependencies with the build, and also to publish as a single executable. You can change the target runtime here as well.
If you want to publish to Linux, you’ll need to add a runtime identifier to your .csproj file.
Of course, the API featured here is unsecured. ASP.NET has a great authentication system, offering support for JWT based tokens, and can be configured to work with OAuth providers like Google and Facebook.
