What is a REST API?

Due to the increasing number of different varieties of clients (mobile apps, browser-based SPAs, desktop apps, IOT apps, etc.), we need better ways for transferring data from servers to clients, independent of technology and server stacks.

REST APIs solve this problem. REST stands for representational state transfer. REST APIs are HTTP-based and provide applications the ability to communicate using lightweight JSON format. They run on web servers.

REST consists of the following entities:

Resource: Resources are uniquely identifiable entities (for example: data from a database, images, or any data).

Endpoint: A resource can be accessed through a URL identifier.

HTTP method: HTTP method is the type of request a client sends to a server. Operations we perform on the resource should follow this.

HTTP header: An HTTP header is a key-value pair used to share additional information between a client and server, such as:

• Type of data being sent to server (JSON, XML).
• Type of encryption supported by client.
• Authentication-related token.
• Customer data based on application need.

Data format: JSON is a common format to send and receive data through REST APIs.

What is a JWT Token?

In the previous section, we saw what a REST API is, and here we will see what a JWT bearer token is, which secures the REST APIs.

JWT stands for JSON Web Token. It is open standard and defines a better way for transferring data securely between two entities (client and server).

A JWT is digitally signed using a secret key by a token provider or authentication server. A JWT helps the resource server verify the token data using the same secret key, so that you can trust the data.

JWT consists of the following three parts:

Header: encoded data of token type and the algorithm used to sign the data.

Payload: encoded data of claims intended to share.

Signature: created by signing (encoded header + encoded payload) using a secret key.

The final JWT token will be like this: Header.Payload.Signature. Please find the token workflow in the following.

Step 1: Client requesting token

The client sends a request to the authentication server with the necessary information to prove its identity.

Step 2: Token creation

The authentication server receives the token request and verifies the identity. If it is found valid, a token will be created (as explained previously) with the necessary claims, and a JWT token will be sent back to the client.

Step 3: Client sends token to resource server

For each request to Resource or the API server, the client needs to include a token in the header and request the resource using its URI.

Step 4: Resource server verifies the token

Follow these steps to verify the token:

• Read the token from authentication header.
• Split the header, payload, and signature from token.
• Create signature of received header and payload using the same secret key used when creating the token.
• Check whether both newly created signature and signature received from token are valid.
• If the signatures are the same, the tokens are valid (not altered in the middle) and they provide access to the requested resource.
• If the signatures are different, an unauthorized response will be sent back to the client. (In the middle, if claims are alerted, they will generate a different signature, hence resource access will be restricted.)

Don’t share confidential information using a JWT, since a JWT can be decoded and the claims or data it possesses can be viewed.

The following section explains how to create a REST API and secure it using a token.

Create an ASP.NET Core REST API application

Follow these steps to create an ASP.NET Core application in Visual Studio 2019:

Step 1: Go to File > New, and then select Project.

Step 2: Choose Create a new project.

Step 3: Select ASP.NET Core Web Application template.

Step 4:  Enter the Project name, and then click Create. The Project template dialog will be displayed.

Step 5: Select .NET Core, ASP.NET Core 3.1, and API template (highlighted in the following).

Step 6: Click Create. The sample ASP.NET Core API application will be created. Find the project structure in the following screenshot.

By default, a sample WeatherForecast API is created. We can remove this.

Install necessary NuGet packages

Add the following NuGet packages to work with SQL Server database and scaffolding, and run the following commands in Package Manager Console (Click Tools -> NuGet Package Manager ->  Package Manager Console).

This package helps generate controllers and views.

• Install-Package Microsoft.VisualStudio.Web.CodeGeneration.Design -Version 3.1.4

This package helps create database context and model classes from the database.

• Install-Package Microsoft.EntityFrameworkCore.Tools -Version 3.1.8

Database provider allows Entity Framework Core to work with SQL Server.

• Install-Package Microsoft.EntityFrameworkCore.SqlServer -Version 3.1.8

It provides support for creating and validating a JWT token.

• Install-Package System.IdentityModel.Tokens.Jwt -Version 5.6.0

This is the middleware that enables an ASP.NET Core application to receive a bearer token in the request pipeline.

• Install-Package Microsoft.AspNetCore.Authentication.JwtBearer -Version 3.1.8

Create database and connect it to application

I hope you have installed SQL Server 2017 in your machine. (You can also use SQL Server 2008, 2012, or 2016.)

Step 1: Create a new database (Inventory).

Step 2: For this application, I am going to create tables called Products and UserInfo with basic attributes. Paste the following SQL query into the Query window to create necessary tables.

Create Table Products(
ProductId Int Identity(1,1) Primary Key,
Name Varchar(100) Not Null,
Category Varchar(100),
Color Varchar(20),
UnitPrice Decimal Not Null,
AvailableQuantity Int Not Null)
GO
Create Table UserInfo(
UserId Int Identity(1,1) Not null Primary Key,
FirstName Varchar(30) Not null,
LastName Varchar(30) Not null,
UserName Varchar(30) Not null,
Email Varchar(50) Not null,
Password Varchar(20) Not null,
CreatedDate DateTime Default(GetDate()) Not Null)
GO
Insert Into UserInfo(FirstName, LastName, UserName, Email, Password) 
Values ('Inventory', 'Admin', 'InventoryAdmin', 'InventoryAdmin@abc.com', '$admin@2017')

Step 3: Run the following scaffold command in Package Manager Console to reverse engineer the database to create database context and entity POCO classes from tables. The scaffold command will create POCO class only for the tables that have a primary key.

Scaffold-DbContext “Server=******;Database=Inventory;Integrated Security=True” Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

• Connection: Sets connection string of the database.
• Provider: Sets the provider to be used to connect database.
• OutputDir: Sets the directory where the POCO classes are generated.

In our case, the Products class and Inventory context class will be created as shown in the following screenshot.

In the autogenerated InventoryContext class file, the database credentials you can see are hard coded in the OnConfiguring method. It is not a good practice to have SQL Server credentials in C# class, considering the security issues. So, remove the following OnConfiguring method and parameterless constructor from context file (highlighted).

Add a connection string to the appsetting.json file.

using InventoryService.Models;
using Microsoft.EntityFrameworkCore;

Then this context service is injected with the required controllers via dependency injection.

Build REST APIs

Now, we have database and entity classes in place. Follow these steps to create Products API:

Step 1: Right–click the Controllers folder, choose Add, and then click Controller.

Step 2: Select API Controller with actions using the Entity Framework template.

Step 3: Choose the Products model class and InventoryContext context class, and then name the control ProductsController.

When we click Add, the API is automatically created using the ASP.NET CORE scaffolding code generation technique.

The following APIs are created:

• To list all products: HTTP Get method
• Get product detail: HTTP Get method
• Update product detail: HTTP Put method
• Create product: HTTP Post method
• Delete product: HTTP Delete method

As per REST best practice, each endpoint is assigned with respective HTTP methods based on its operation.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using InventoryService.Models;
using Microsoft.AspNetCore.Authorization;

namespace InventoryService.Controllers
{
    [Authorize]
    [Route("api/[controller]")]
    [ApiController]
    public class ProductsController : ControllerBase
    {
        private readonly InventoryContext _context;

        public ProductsController(InventoryContext context)
        {
            _context = context;
        }

        [HttpGet]
        public async Task<ActionResult<IEnumerable<Products>>> GetProducts()
        {
            return await _context.Products.ToListAsync();
        }


        // GET: api/Products/5
        [HttpGet("{id}")]
        public async Task<ActionResult<Products>> GetProducts(int id)
        {
            var products = await _context.Products.FindAsync(id);

            if (products == null)
            {
                return NotFound();
            }

            return products;
        }

        // PUT: api/Products/5
        // To protect from overposting attacks, please enable the specific properties you want to bind to, for
        // more details see https://aka.ms/RazorPagesCRUD.
        [HttpPut("{id}")]
        public async Task<IActionResult> PutProducts(int id, Products products)
        {
            if (id != products.ProductId)
            {
                return BadRequest();
            }

            _context.Entry(products).State = EntityState.Modified;

            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException)
            {
                if (!ProductsExists(id))
                {
                    return NotFound();
                }
                else
                {
                    throw;
                }
            }

            return NoContent();
        }

        // POST: api/Products
        // To protect from overposting attacks, please enable the specific properties you want to bind to, for
        // more details see https://aka.ms/RazorPagesCRUD.
        [HttpPost]
        public async Task<ActionResult<Products>> PostProducts(Products products)
        {
            _context.Products.Add(products);
            await _context.SaveChangesAsync();

            return CreatedAtAction("GetProducts", new { id = products.ProductId }, products);
        }

        // DELETE: api/Products/5
        [HttpDelete("{id}")]
        public async Task<ActionResult<Products>> DeleteProducts(int id)
        {
            var products = await _context.Products.FindAsync(id);
            if (products == null)
            {
                return NotFound();
            }

            _context.Products.Remove(products);
            await _context.SaveChangesAsync();

            return products;
        }

        private bool ProductsExists(int id)
        {
            return _context.Products.Any(e => e.ProductId == id);
        }
    }
}

Now, we are going to make the following modifications to the Get Products API to filter the products:

• Return the products that are in stock.
• Support limiting the number of results returned.

[HttpGet]
        public async Task<ActionResult<IEnumerable<Products>>> GetProducts(bool? inStock, int? skip, int? take)
        {
            var products = _context.Products.AsQueryable();

            if (inStock != null) // Adds the condition to check availability 
            {
                products = _context.Products.Where(i => i.AvailableQuantity > 0);
            }

            if (skip != null)
            {
                products = products.Skip((int)skip);
            }

            if (take != null)
            {
                products = products.Take((int)take);
            }

            return await products.ToListAsync();
        }

Change the launch URL to api/products in launchSettings.js.

Run and test APIs using Postman

Click Run to view the Inventory service.  A new browser tab will open, and we’ll be able to see the product listing.

Our Inventory REST service is up and running.

Note: The localhost port number may be different in your development machine.

In this section, we will see how to consume our service using Postman (Postman is an API testing tool that helps developers consume and check how an API works).

Follow these steps to view the products list:

Step 1: Open Postman and enter this endpoint: https://localhost:44305/api/products.

Step 2: Choose the GET method and click Send. Now, all the products will be listed as shown in the following screenshot.

Now, apply the filter to return products that are in stock and fetch only necessary items using skip and take.

Enter the following endpoint into Postman: https://localhost:44305/api/products?instock=true&skip=2&take=3

Now, you can see only the products that are in stock. It skips the first two records and displays the next three records.

Follow these steps to view the details of a product:

Step 1: Open Postman and enter this endpoint: https://localhost:44305/api/products/1.

Step 2: Choose GET method and click Send. Now, you can see the details of the product. Here, the product id is 1.

Note: Change ProductId based on records available in your database.

Follow these steps to update the product:

Step 1: Enter this endpoint into Postman: https://localhost:44305/api/products/7.

Step 2: Choose the PUT method and set as header: ‘Content-Type’: ‘application/json’.

Step 3: Under Body > Raw, choose type JSON (application/javascript) and paste the product details.

By clicking Send, a product is created, and by loading the product listing page, you can see the newly created product.

Follow these steps to update the product:

Step 1: Enter this endpoint into Postman: https://localhost:44305/api/products/7.

Step 2: Choose the PUT method and set as header: ‘Content-Type’: ‘application/json’.

Step 3: Under Body > Raw, choose type JSON (application/javascript) and paste the product details.

By clicking Send, the product details are updated.

Note: ProductId must be the same in the endpoint and product details (see the red highlight in the previous image), otherwise the API will throw bad request.

Follow these steps to delete a product:

Step 1: Enter this endpoint into Postman: https://localhost:44305/api/products/7.

Step 2: Choose the DELETE method and click Send. Now, the product will be deleted from the database.

Create a JWT

We can consume and test our API using Postman, but the problem here is anyone who knows the endpoint can consume it. So this is not the case, we need an option to control who can consume our service. This is achieved by a JWT bearer token.

Here, we will see how to create a token:

Step 1: Create an empty API controller called TokenController.

Step 2: Paste the below JWT configuration into the appsetting.json file.

Step 3: Add the action method under TokenController to perform the following operations:

• Accept username and password as input.
• Check users’ credentials with database to ensure users’ identity:
  • If valid, access token will be returned.
  • If invalid, bad request error will be returned.

The following code example demonstrates how to create a token.

using InventoryService.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.IdentityModel.Tokens;
using System;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using System.Threading.Tasks;

namespace InventoryService.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TokenController : ControllerBase
    {
        public IConfiguration _configuration;
        private readonly InventoryContext _context;

        public TokenController(IConfiguration config, InventoryContext context)
        {
            _configuration = config;
            _context = context;
        }

        [HttpPost]
        public async Task<IActionResult> Post(UserInfo _userData)
        {

            if (_userData != null && _userData.Email != null && _userData.Password != null)
            {
                var user = await GetUser(_userData.Email, _userData.Password);

                if (user != null)
                {
                    //create claims details based on the user information
                    var claims = new[] {
                    new Claim(JwtRegisteredClaimNames.Sub, _configuration["Jwt:Subject"]),
                    new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
                    new Claim(JwtRegisteredClaimNames.Iat, DateTime.UtcNow.ToString()),
                    new Claim("Id", user.UserId.ToString()),
                    new Claim("FirstName", user.FirstName),
                    new Claim("LastName", user.LastName),
                    new Claim("UserName", user.UserName),
                    new Claim("Email", user.Email)
                   };

                    var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_configuration["Jwt:Key"]));

                    var signIn = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

                    var token = new JwtSecurityToken(_configuration["Jwt:Issuer"], _configuration["Jwt:Audience"], claims, expires: DateTime.UtcNow.AddDays(1), signingCredentials: signIn);

                    return Ok(new JwtSecurityTokenHandler().WriteToken(token));
                }
                else
                {
                    return BadRequest("Invalid credentials");
                }
            }
            else
            {
                return BadRequest();
            }
        }

        private async Task<UserInfo> GetUser(string email, string password)
        {
            return await _context.UserInfo.FirstOrDefaultAsync(u => u.Email == email && u.Password == password);
        }
    }
}

Follow these steps to check the token endpoint using Postman:

Step 1: Enter this endpoint https://localhost:44305/api/token.

Step 2: Choose the POST method and set the header to ‘Content-Type’: ‘application/json’.

Step 3: Under Body > Raw, choose type JSON (application/javascript) and paste the product details.

By clicking Send, user credentials will be checked, and a token will be generated and returned. See the highlighted body section.

Secure API endpoint

Now, we have a JWT token and will see how to secure our API.

Step 1: Add the following namespaces to the startup file:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

Step 2: Configure authorization middleware in the startup configureService method.

We have passed the security key used when creating the token, and we have also enabled validation of Issuer and Audience.

Also, we have set SaveToken to true, which stores the bearer token in HTTP Context. So we can access the token in the controller when needed.

Step 3: Inject the authorization middleware into the Request pipeline.

Step 4: Add authorization attribute to the controller.

Here I have added authorization to the whole controller, so all the APIs under this controller will be secured with the token. You can also add authorization to a particular API method.

Follow these steps to test whether the APIs are secured by the JWT:

Step 1: In Postman, enter this endpoint: https://localhost:44305/api/products.

Step 2: Choose the GET method and then click Send. Now, you can see the Status code is 401 Unauthorized.

The anonymous access has been blocked and the APIs have been secured. Now, we will see how to access the APIs using the token.

Step 3: Copy the token that was created in earlier steps.

Step 4: Prepend text Bearer with this token, and finally you will have a token as follows.

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJJbnZlbnRvcnlTZXJ2aWNlQWNjZXNzVG9rZW4iLCJqdGkiOiIwMGY2MjcwYy05NmFlLTQwMDUtOWUwOS00YWVkMjU5NWNjMTIiLCJpYXQiOiIxMS8yOS8yMDE5IDY6MTc6MDIgQU0iLCJJZCI6IjEiLCJGaXJzdE5hbWUiOiJJbnZlbnRvcnkiLCJMYXN0TmFtZSI6IkFkbWluIiwiVXNlck5hbWUiOiJJbnZlbnRvcnlBZG1pbiIsIkVtYWlsIjoiSW52ZW50b3J5QWRtaW5AYWJjLmNvbSIsImV4cCI6MTU3NTA5NDYyMiwiaXNzIjoiSW52ZW50b3J5QXV0aGVudGljYXRpb25TZXJ2ZXIiLCJhdWQiOiJJbnZldG9yeVNlcnZpY2VQb3N0bWFuQ2xpZW50In0.r3gDqAL9FmH2LA_-nfyLDrihfhuY5ODk1bGOLECaKcI

Step 5:  Now, come back to the product list. Under the Authorization header, paste the previous token in the Value field, and then click Send. Now you can see the products from our API.

• In code-behind, when we pass the authorization header to the API, authentication middleware parses and validates the token. If it is found valid, it will set UIdentity.IsAuthenticated to true.
• The Authorize attribute added to the controller will check whether the request is authenticated. If it is true, the API can be accessed.
• If UIdentity.IsAuthenticated returns false, and a 401 unauthorized error will be returned.
• If you need to, you can read claims from Identity.

Conclusion

In this blog, we have learned how to create a REST API using ASP.NET Core 3.1 and Entity Framework Core to perform basic CRUD operations, create a JWT token, and secure the API. I hope you found this blog useful.

In this post I’ll show you how it’s done using the Entity Framework Core Scaffolder in Visual Studio.

What you will need:

• Visual Studio (most recent version, right now it’s 2019) with .Net Core 2.1 or more recent;
• MySQL server installed;
• MySQL Workbench or any other UI to help you create tables and the like. If you feel like a pro, you can also use the command line with MySQL Shell.

1. Install the Tools!

Let’s get our environment setup and install all the necessary tools, I’ll stick with MySQL Workbench/MySQL Community combination but you can do as you like. Go to the download page and download MySQL Community full setup for Windows.

Once it’s installed, you will have to add a new connection to your MySQL Server to be able to connect from Workbench to your server. Here are some sample settings if you’ve installed MySQL to your local machine. Your root password will be asked once you connect to the server.

2. Create a Database

We’ll simply create a test database with two tables joined with a relationship. The classic Classes -> Students example will apply, one class can have many students. Normally we would say that one student can attend many classes but this would complicate the example for no real benefit with a many to many relationship.

Database Creation

Launch MySQL Workbench and create a new Database and give it a name. Then click Apply in the bottom right corner.

You might get prompted by the window below, just click Apply again to run the SQL statement.

The next thing you will want to do is to set the newly created schema (database) as default. That will make sure all the queries we run will apply to this database. Right-click on the schema and click on Set as detault schema.

Create the Tables

We will now create two tables. Creating a table is very easy with MySQL Workbench! Right-click on the schema and click on Create table.

Below is the Student table. You might notice that I have put the utf8mb4 charset to conform to the standard UTF8, that will enable us to put special characters in our table. Also, I want to bring your attention on the abbreviations that MySQL seems to expect you to know. Here are the most important ones.

• PK – Primary Key
• NN – Not null (element cannot be left null, good, I hate nulls!)
• UQ – Must be unique. By default the primary key is always unique.
• AI – Auto incremented column, let’s say 1, 2, 3, 4, … The database engine will automatically keep the count and increment as you add rows.

Data types are not exactly the same as in MSSQL but some are similar like VARCHAR and INT which I use in this example for storing strings and numbers respectively.

And now here is the Class table below. For more information, the Level is the year that the student is now in, that is (1, 2, 3, …) depending on your education system.

Once you’ve clicked apply on both tables, it should give you a database just like in this image, but we are still missing the relationship.

Add the Foreign Key

We will add the foreign key by going into the table that will contain it, which is Students because one Class can have MANY Students but one student can only belong to one class (again for the simplicity of the example).

Give your foreign key a name and select the referenced table in the left panel. Then, in the right panel select the affected column and the referenced column. This will create a reference and an index. Finally, click Apply and we’re done!

3. Create a New Project in Visual Studio

Create a new .Net Core 2.1+ project in Visual Studio. Any type will work, you can also create a .Net Framework project and add the nuget packages to it.

4. Install Required Nuget Packages

Right-click on the target project and click on Manage Nuget Packages and head over to Browse.

Use the User Interface

You will need to install two packages :

• MySql.Data.EntityFrameworkCore.Design
• Microsoft.EntityFrameworkCore.Tools

Search for them in the Browse tab and click on Install. They will both install many packages required to scaffold and use the Entity Framework Core with MySQL. Simply click ok and accept on the prompts.

Or Use the Package Manager Console

You can also use the Package Manager Console with the Install-Package commands below.

Install-Package MySql.Data.EntityFrameworkCore.Design
Install-Package Microsoft.EntityFrameworkCore.Tools

5. Scaffolding

Open the Package Manager Console. If you can’t find it, go into View -> Other Windows -> Package Manager Console in the top menu. It should open a panel like the one below.

You have to enter the following command in the panel to scaffold your database. You can also create a folder where the created classes will reside.

Scaffold-DbContext "server=localhost;port=3306;user=root;password=yourpassword;database=test_scaffolding" MySql.Data.EntityFrameworkCore -OutputDir DataAccess\DataObjects -f

If you want to specify tables, use the following:

Scaffold-DbContext "server=localhost;port=3306;user=root;password=yourpassword;database=test_scaffolding" MySql.Data.EntityFrameworkCore -OutputDir DataAccess\DataObjects -Tables class,student -f

Also, the -f will force the recreation of the generated classes even if you’ve made changes, so be careful! Make sure that the right project is selected before running commands in the Package Manager Console or you will affect another project (red rectangle in the image below).

As you can see, the first run went well and created the classes as intended, but when I tried to re-run the command on a specific table, I needed to add the -f force argument to overwrite.

Use the Created Context

Once the context has been created with the command above, you will get one class per table plus one Context that you’ll use to access the data.

Now it’s time to head to Program.cs in our console application and call the DataContext.

using System;
using System.Linq;
 
using ScaffoldingWithMySQL.DataAccess.DataObjects;
 
namespace ScaffoldingWithMySQL
{
    class Program
    {
        static void Main(string[] args)
        {
            test_scaffoldingContext dataContext = new test_scaffoldingContext();
             
            //Create a new student object to add to the class
            Student newStudent = new Student()
            {
                CardNumber = "TEST329812",
                Level = 1,
                FirstName = "Simon",
                LastName = "Test"
            };
             
            //Create a new class object
            Class newClass = new Class()
            {
                Department = "English",
                Level = 1,
                Title = "English Class",
                Year = 2019
            };
 
            //Let's add a student to the class and then add the class to the classes in the database.
            newClass.Student.Add(newStudent);  
            dataContext.Class.Add(newClass);
 
            //Don't forget to save changes!
            dataContext.SaveChanges();
        }
    }
}

The above code is an example of how you can use your newly create DataContext to access your data. If you want more information about the process of Scaffolding with MySQL, you can go on the MySQL Website. I hope this post will be useful for a few of you!

Having Some Errors or Issues?

I found recently that using different versions of NuGet packages can lead to strange behaviours from the MySQL scaffold engine. What I would recommend is that you have a look at this link from the MySQL Website which gives you the version compatibility. Make sure the Microsoft.EntityFrameworkCore and MySQL.Data.EntityFrameworkCore versions are correct according to the previous documentation.

Conclusion

Done! You have learned how to scaffold your MySQL database with Entity Framework. If you found this article helpful, please feel free to share it. Thank you

We’ll start with an example .NET 6 CRUD API from a tutorial I posted recently, it uses the EF Core InMemory db provider by default for testing, we’ll update it to connect to a SQL Server database and run EF Core migrations to auto generate the database and tables from code. 

Requirements!

To follow the steps in this tutorial you’ll need the following:

• .NET SDK – includes the .NET runtime and command line tools.
• Visual Studio Code – code editor that runs on Windows, Mac and Linux. If you have a different preferred code editor that’s fine too.
• C# extension for Visual Studio Code – adds support to VS Code for developing .NET applications.
• SQL Server – you’ll need access to running SQL Server instance for the API to connect to, it can be remote (e.g. Azure, AWS etc) or on your local machine. The Express edition of SQL Server is available for free at https://www.microsoft.com/sql-server/sql-server-downloads.

Download & Run the example .NET 6 API

Follow these steps to download and run the .NET 6 CRUD API on your local machine with the default EF Core InMemory database:

1. Download or clone the tutorial project code from https://github.com/cornflourblue/dotnet-6-crud-api
2. Start the api by running dotnet run from the command line in the project root folder (where the WebApi.csproj file is located), you should see the message Now listening on: http://localhost:4000.
3. You can test the API directly with a tool such as Postman.

Starting in debug mode

You can also start the application in debug mode in VS Code by opening the project root folder in VS Code and pressing F5 or by selecting Debug -> Start Debugging from the top menu, running in debug mode allows you to attach breakpoints to pause execution and step through the application code.

Update .NET 6 API to use SQL Server

Add SQL Server database provider from NuGet

Run the following command from the project root folder to install the EF Core database provider for SQL Server from NuGet:

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Add connection string to app settings

Open the appsettings.json file and add the entry "ConnectionStrings" with a child entry for the SQL Server connection string (e.g. "WebApiDatabase"), the connection string should be in the format "Data Source=[DB SERVER URL]; Initial Catalog=[DB NAME]; User Id=[USERNAME]; Password=[PASSWORD]", or to connect with the same account that is running the .NET API use the connection string format "Data Source=[DB SERVER URL]; Initial Catalog=[DB NAME]; Integrated Security=true".

When EF Core migrations generates the database, the Initial Catalog value will be the name of the database created in SQL Server.

The updated appsettings.json file with the connection string should look something like this:

{
    "ConnectionStrings": {
        "WebApiDatabase": "Data Source=localhost; Initial Catalog=dotnet-6-crud-api; User Id=testUser; Password=testPass123"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    }
}

Update Data Context to Use SQL Server

The DataContext class located at /Helpers/DataContext.cs is used for accessing application data through Entity Framework. It derives from the Entity Framework DbContext class and has a public Users property for accessing and managing user data.

Update the OnConfiguring() method to connect to SQL Server instead of an in memory database by replacing options.UseInMemoryDatabase("TestDb"); with options.UseSqlServer(Configuration.GetConnectionString("WebApiDatabase"));.

The updated DataContext class should look like this:

namespace WebApi.Helpers;

using Microsoft.EntityFrameworkCore;
using WebApi.Entities;

public class DataContext : DbContext
{
    protected readonly IConfiguration Configuration;

    public DataContext(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        // connect to sql server with connection string from app settings
        options.UseSqlServer(Configuration.GetConnectionString("WebApiDatabase"));
    }

    public DbSet<User> Users { get; set; }
}

Create SQL Database from code with EF Core Migrations

Install dotnet ef tools

The .NET Entity Framework Core tools (dotnet ef) are used to generate EF Core migrations, to install the EF Core tools globally run dotnet tool install -g dotnet-ef, or to update run dotnet tool update -g dotnet-ef. For more info on EF Core tools see https://docs.microsoft.com/ef/core/cli/dotnet

Add EF Core Design package from NuGet

Run the following command from the project root folder to install the EF Core design package, it provides cross-platform command line tooling support and is used to generate EF Core migrations:

dotnet add package Microsoft.EntityFrameworkCore.Design

Generate EF Core migrations

Generate new EF Core migration files by running the command dotnet ef migrations add InitialCreate from the project root folder (where the WebApi.csproj file is located), these migrations will create the database and tables for the .NET Core API.

Execute EF Core migrations

Run the command dotnet ef database update from the project root folder to execute the EF Core migrations and create the database and tables in SQL Server.

Check SQL Server and you should now see your database with the tables Users and __EFMigrationsHistory.

Restart .NET 6.0 CRUD API

Stop and restart the API with the command dotnet run from the project root folder, you should see the message Now listening on: http://localhost:4000 and the API should now be connected to SQL Server.

The below steps show how to use a SQLite database in development and a SQL Server database in production, but you could switch these to any database providers you like that are supported by EF Core.

Create Main EF Core DB Context for SQL Server

Create the main DB context class that defines the entities available in the database via public DbSet<TEntity> properties, and configure it to connect to the production database (SQL Server in this case).

Below is the main DB context from the example ASP.NET Core api linked above, it has the class name DataContext and is located in the /Helpers directory of the project, but you can choose any class name and directory you prefer.

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using WebApi.Entities;

namespace WebApi.Helpers
{
    public class DataContext : DbContext
    {
        protected readonly IConfiguration Configuration;

        public DataContext(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        protected override void OnConfiguring(DbContextOptionsBuilder options)
        {
            // connect to sql server database
            options.UseSqlServer(Configuration.GetConnectionString("WebApiDatabase"));
        }

        public DbSet<User> Users { get; set; }
    }
}

Create Development EF Core DB Context for SQLite

Create a development DB context that inherits from the main DB context above and overrides the database provider in the OnConfiguring() method.

Below is the development DB context from the example ASP.NET Core api that overrides the database provider to connect to SQLite instead of SQL Server. Having a second EF Core DB Context that derives from the main DB context is what enables the project to support multiple different database providers.

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace WebApi.Helpers
{
    public class SqliteDataContext : DataContext
    {
        public SqliteDataContext(IConfiguration configuration) : base(configuration) { }

        protected override void OnConfiguring(DbContextOptionsBuilder options)
        {
            // connect to sqlite database
            options.UseSqlite(Configuration.GetConnectionString("WebApiDatabase"));
        }
    }
}

Generate SQLite EF Core Migrations

Run the following command to generate EF Core migrations for SQLite and store them in their own folder.

dotnet ef migrations add InitialCreate --context SqliteDataContext --output-dir Migrations/SqliteMigrations

Generate SQL Server EF Core Migrations

Run the following command to generate EF Core migrations for SQL Server and store them in their own folder.

The environment variable ASPNETCORE_ENVIRONMENT needs to be set to Production so the SQL Server DataContext class is configured with the .NET Core dependency injection system, see the ConfigureServices() method below.

Configuring environment variables from the command line is slightly different on MacOS and Windows.

Windows

set ASPNETCORE_ENVIRONMENT=Production
dotnet ef migrations add InitialCreate --context DataContext --output-dir Migrations/SqlServerMigrations

MacOS

ASPNETCORE_ENVIRONMENT=Production dotnet ef migrations add InitialCreate --context DataContext --output-dir Migrations/SqlServerMigrations

Configure Startup.cs to use SQLite in Development and SQL Server in Production

Below is a cut down version of the Startup.cs file from the example ASP.NET Core api that just includes the bits related to the EF Core DB context configuration and automatic database migration.

Lines 23 - 26 configure which type of data context is injected by the .NET Core dependency injection system when a DataContext instance is required by a class. In production an instance of the main DataContext class is used which connects to SQL Server, otherwise (i.e. in development) an instance of the SqliteDataContext is used.

An instance of the DataContext is injected as a parameter into the Configure() method, the data context instance is then used to apply any pending migrations to the database by calling the dataContext.Database.Migrate() method on line 35.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Hosting;
using WebApi.Helpers;

namespace WebApi
{
    public class Startup
    {
        private readonly IWebHostEnvironment _env;

        public Startup(IWebHostEnvironment env)
        {
            _env = env;
        }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // use sql server db in production and sqlite db in development
            if (_env.IsProduction())
                services.AddDbContext<DataContext>();
            else
                services.AddDbContext<DataContext, SqliteDataContext>();

            ...
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env, DataContext dataContext)
        {
            // migrate any database changes on startup (includes initial db creation)
            dataContext.Database.Migrate();
            
            ...
        }
    }
}