Developing with ASP.NET Core

Jen O’Byrne

I have been using .NET Core for a couple of weeks now and I am enjoying it! So I thought I would take you through the great things, and the annoying things of .NET Core, while we make a simple Web API.

Tools you will need for this exercise

Let’s use the latest version of ASP.NET Core. At the time of writing this blog post the version I am using is 1.1. Download it here if you don’t already have it.

If you are using Chrome, download Postman. If you are using another browser, find an app that will allow you to send requests through. Postman allows you to test the API that we will be building today.

Get an IDE that you feel comfortable developing in. I used to use Sublime before I found out about Microsoft’s great lightweight IDE — Visual Studio Code. It is available on Mac, Windows, or Linux machine. Similar to .NET core, it is very new, and so you may experience a couple of minor bugs. I have had a few issues when trying to debug tests in Visual Studio Code. Each time I ran a test I had to shut the program and reopen it again in order to run the next set.

There are some good extensions you can get to make it better. I have the C# extension and the Nuget Package Manager extension. One warning about the Nuget Package Manager extension: it breaks with the latest version of .NET Core. If you are a TypeScript pro, you could fix it for everyone.

The great things about .NET Core and Visual Studio code are that they are open source. If you find an issue, try to fix it!

Adding a New Project

The latest version of .NET Core CLI tools comes with some basic project templates. You are now able to create a project based off one of the many different templates options. In prior versions you could only run “dotnet new” in the CLI, which would give you a new console application. Now you can add a new library, a solution, a test project or many more options. I love how powerful it is. I am still pretty slow when I create a new things, so being able to create apps through the command line is making my life a breeze.

So having said all that, let’s run through how you would get a basic Web API running using .NET Core.

Open the command line and move into the directory where you want your project to live. Once you are in the right spot, run “dotnet new webapi”. This will create a “Hello World” Web API project, and you will now have some files in your folder. Magic stuff, this .NET Core.

If you don’t have the latest version of the .NET SDK installed, you will get an error that says “… unrecognised command or argument webapi”. If you see this error, download the latest version using the link I posted above.

Next run “dotnet restore”. This will restore the Nuget packages and tools your project needs. You will see a couple of new files after running this.

If you now run “dotnet run” in the console, your project will compile and you will see that your Web API is now alive. The console will now tell you a port is listening for requests. Let’s hit that endpoint and see what we get back. But before we do this, we have to check what Controllers we have, and what actions are available for us to access.

To do this, I have opened “my-new-web-api” folder in Visual Studio code, and I am looking at the Controllers folder.

Here is an annoying issue with Visual Studio Code. Sometimes it tells you are missing references and everything displays in Visual Studio Code as an error. If it is building fine in the CLI, just ignore it. It’s lying to you. I shut the program and reopen it, and normally that fixes the errors.

Anyway, back to coding. I can see a ValuesController which has a couple of public methods. It is important to note that there is a Route attribute on ValuesController. This means when we send a request to the Controller we need to add “/api/” to the URL.

Let’s use the “Get” method from there which takes no parameters and returns a IENumerable of string.

Open Postman, and copy over the URL from the command line. Make sure that the HTTP Verb is set to “Get” — we can tell this needs to be a Get from the attribute on top of our method in the ValuesController. Before you hit execute you need to add /api/Values at the end of the request.

Sidenote: the reason we put /api/ before the controller name is to indicate this is an API. What is an API I hear you ask? Well I am glad you asked, in simple terms, an API is a way you define how other programs interact with your program.You can read more about it here.

You should now see an array of strings in the body section of Postman. This will mean that your API worked and you successfully hit the endpoints. You can have a play round and change the values, call other methods, and add your own.

Let’s make this a bit more interesting and build on top of this template. So add another class that takes a parameter. We are going to calculate if a given year is a leap year.

To start let’s rename the controller to be DateController, and remove all methods apart from our parameterless Get method. Once you have done that add a class called DateService. This class is where we will calculate if a year is a leap year or not. You can copy it over from my repository if you don’t want to start from scratch. Note that the name of the class will need to be changed to DateService, and you will need to add the corresponding namespace.

Now we need to change our method to do what we want. We want the user to give us a year, so let’s add a parameter which is an int called year. Now let’s call our new DateService from our DateController and return a string to the user based on if the year is a leap year or not. Hopefully, your code resembles something like this.

Now that everything is compiling, let’s retry this in Postman. As we have renamed ValuesController to DateController we need to update that in our request, and we also need to add “year=2017”. You can change that to any year you like. If you execute the request now, everything “should just work”.

Let’s add some tests, because tests are good

Normally, I like writing tests as I code, but we haven’t done that yet. So let’s add some retrospectively. Back to the command line we go. Move into the directory where your Web API code lives and create a new directory called “test”. Inside of test run the command “dotnet new xunit”. This will create a new test project with a test class, and a dummy test.

There are two additional commands you need to run. The first is “dotnet add reference ../{where-your-project-lives}/{project-name}.csproj”. The next is “dotnet restore” so it installs all of its dependencies.

You can now write some tests for our DateService class. If you need a head start on the tests, you can use the test class I have already written here. Once you have added the test class, run “dotnet test” in your CLI.

You should hopefully see 4 tests passing! If you don’t, I don’t know what you have done but you can step through my code and check for yourself.

Now, go roam free and have your own play around

As I said before, there are already a bunch of template projects that you can have a play with. You are also able to specify what language you want them. At the time of writing there is only C# or F# available. Again, this is all open source — so if you want to contribute to the CLI tools, go and have a look at the CLI repository.

Hopefully now you see why I like .NET Core so much. To get a simple Web API going it took all of 30 seconds. You no longer have to write your own code to get a Hello World app going, as it is already there and just waiting for you to run the templates.