One of the most overlooked features of .net core is the new “dotnet watch” command. With it, it allows you to have a “live reload” of your ASP.net core site running without having to either run the “dotnet run” command, or worse do the “Stop the process in Visual Studio. Write your changes. Recompile and run again” routine. The latter can be very annoying when all you are trying to do is do a simple one line fix.

If you are used to watches in other languages/tooling (Especially task runners like Gulp), then you will know how much of a boost watches are to productivity.

The Basics

I highly recommend creating a simple ASP.net core project to run through this tutorial with. The tooling can be a little finicky with large projects so it’s easier to get up and running with something small, then take what you’ve learned onto something a little larger.

First you need to install the nuget package that actually runs the watcher tool. Run the following from your package manager console.

For this demo, I have a simple controller that has a get method that returns a string value.

Open a command prompt in your project directory. Run the command “dotnet watch run”. Note that if you previously have run the “dotnet run” command with other flags (e.g. “dotnet run -f net451” to specify the framework), this will still work using the watch command. You should see something similar to the following :

This means you are up and running. If I go to http://localhost:5000/api/home, I should see my controller return “Old Value”.

Now I head back to my controller and I change the Get action to instead return “New Value”. As soon as I hit save on this file I see the following in my console window :

The first line tells us that it immediately picked up on the fact that we changed something in HomeController.cs and so it starts recompiling immediately. When we browse to http://localhost:5000/api/home we see our “New Value” shown immediately and we didn’t have to do anything else in terms of recompiling.

Debugging With Dotnet Watch

And now the big caveat of this feature. There doesn’t seem to be a way to always have your Visual Studio debugger on the latest instance of the running code. The dotnet watch command itself spins up kestrel to host your code, but it’s hard to identify the PID of this particular process. I assume that you should be able to attach your debugger to this process once you find it, but as soon as you edit your code, a new process is created, rendering your debugger useless.

For the most part, errors will flash by on your console window when they happen so should be easy to spot. Then when you actually need the full debugger experience like breakpoints, you will be able to attach it. Just don’t expect it to be “always on”.

This article is old and outdated. The official MS Documentation on testing has a wealth of information that is more up to date. I’m leaving this here in the slim chance it helps someone out who is on an extremely old version of .NET Core (<1.1), but otherwise, to the official documentation we go!


With .net core comes a new way to build and run unit tests with a command line tool named “dotnet test”. While the overall syntax of writing tests using MSTest, XUnit or NUnit hasn’t changed, the tooling has changed substantially from what people are used to. There is even a couple of gotchas that are enough to cause migraines if you aren’t careful.

Annoyingly, many of the packages you need to get started are in pre-release, and much of the documentation is locked into the old style DNX tooling. This article focuses on .net Core 1.1 – Preview 2. If you are already running Preview 4 then much of this will still apply, but you will be working with csproj files instead of project.json. Once Preview 4 gets a proper release, this article will be updated to reflect the (likely) many changes that go along with it.

Let’s get started.

The Basics Using MSTest

We will go over the basics using the MSTest framework. If you prefer to use NUnit or XUnit there are sections below to explain how they run within dotnet test, but still read through this section as it will give you the general gist of how things work.

Create a .net core console project in your solution. Now you are probably used to creating a class library for unit tests or maybe even a “unit test” project. We do not use the “Unit Test” project type as there is no such type for .net core, only the full framework. And we do not use a class library only for the reason that it defaults the target framework to .net standard, not .net core. It’s not that we are going to be building a console application per-say, it’s that the defaults for a console application in terms of project.json are closer to what we need.

Once the project is created, if you are on .net core 1.1 or lower, open up project.json. Delete the entire “buildOptions” node. That’s this node :

You can also go ahead and delete the Program.cs file as we won’t be needing it.

Inside that project, you need to install a couple of packages.

You first need to install the MSTest Framework package from here. At this point in time it is still in Pre-Release so you need the “Pre” flag (At some point this will change).

And now install the actual runner package from here. Again, it’s in Pre-Release so you will need the “Pre” flag.

Now go back to your project.json and add in a “testrunner” node at the top level called “mstest”. All in all, your project.json should look like the following :

Great! Now, for the purpose of this article we will create a simple class called “UnitTests.cs”, and add in a couple of tests. That file looks like the following :

Open a command prompt in your unit test directory. Run “dotnet test”. You should see something like the following :

And you are done! You now have a unit test project within .net core.

Using NUnit With Dotnet Test

Again, follow the steps above to create a console application, but remove the buildOptions node in your project.json.

Add in your NUnit nuget package by running the following from the package manager console :

Now you need to add the NUnit test runner. Install the following nuget package. Note that at the time of this article, the package is only in pre-release so you need the Pre flag :

Inside your project.json, you need a top level node called “testRunner” with the value of “nunit”. If you’ve followed the steps carefully, you should have a project.json that resembles the following :

For the purpose of this article, I have the following test class :

Open a command prompt inside your project folder and run “dotnet test”. You should see something similar to the following :

Using XUnit With Dotnet Test

Again, follow the steps above to create a console application, but remove the buildOptions node in your project.json.

Add in XUnit Core nuget package to your project. In your package manager console run :

Now add in the XUnit test runner with the following command  in your package manager :

Open up your project.json. Add in a top level node named “testrunner” with the value of “xunit”. All going well, your project.json should resemble something close to the following :

For this article, I have the following test class :

Open up a command prompt in your project folder. Run the command “dotnet test” and you should see something similar to the following :

GZIP is a generic compression method that can be applied to any stream of bits. In terms of how it’s used on the web, it’s easiest thought of a way that makes your files “smaller”. When applying GZIP compression to text files, you can see anywhere from 70-90% savings, on images or other files that are usually already “compressed”, savings are much smaller or in some cases nothing. Other than eliminating unnecessary resource downloads, enabling compression is the next best way to improve the loading speed of your web app.

Enabling At The Code Level (Dynamic)

You can dynamically GZIP text resources on request. This is great for content that may change (Think dynamic html, text, not JS, CSS). The reason it’s not great for static content such as CSS or JS, is that those files will not change between requests, or really even between deployments. There is no advantage to dynamically compressing these each time they are requested.

The code you need to make this work is contained in a nuget package. So you will need to run the following from your package manager console.

In your ConfigureServices method in your startup.cs, you need to add a single line to add the dependencies that GZIP compression is going to need.

Note that there are a couple of options you may wish to use in this call.

The EnableForHttps flag does exactly what it says. It enables GZip compression even over SSL (By default this is switched off). The second turns on (Or off in some cases) GZip of certain mimetypes. The default list at the time of writing is the following (Taken from the Github source here) :

Then in your configure method of startup.cs, you then just need a single line to get going.

Note that the order is very important! While in this case we only have two pieces of middleware that don’t cause issues, other middleware (such as the Static Content middleware), actually send the response back to the user before GZip has occured if it’s first in the list. For safety sake, just keep UseResponseCompression as the first middleware in your list.

To test you have everything up and running just fine, try loading your site and watching the requests go past. You should see the Content-Encoding header come back as “Gzip”. In Chrome it looks like the following :

Enabling At The Code Level (Static)

The issue with enabling GZip compression inside .net core is that if your content is largely static (As in it doesn’t change), then it’s being re-compressed over and over again. When it comes to javascript and CSS, there is really no reason for this to be done on the fly. Instead we can GZip these files beforehand and deploy them “pre” GZip’d.

For this you will need to use a task runner such as Gulp to GZIP your static files in your pipeline. There is a very simple gulp package for this named “gulp-gzip”. Have a search around and get used to how it works. But your gulp file should look something similar to the following :

This is a very simple case, you will need to know a bit more about Gulp to customize it to your needs.

However importantly, you need to map Gzip files to actually return their real result. First install the static file middleware. Run the following from your Package Manager console.

Now in your Configure method in startup.cs, you need to add some code like so :

What does this do? Well first it says that serving static files without running the MVC gamut is A-OK. But next it says, if you come across a file that ends in .js.gz, you can send it out, but instead tell the browser that it’s actually javascript and that it’s just been encoded with gzip. Otherwise it just returns the file as a plain old GZip file that a user could download for example.

Next on your webpage, you actually need to be referencing the .gz file not the .js file. So it should look something like so :

And that’s it, your static content is now compressed!

Enabling At The Server Level

And lastly, you can of course always enable GZip compression at the web server level (IIS, NGinx, Apache etc). For this it’s better to consult the relevant documentation. You may wish to do this as it keeps the configuration out of code (And allows a bit more easier access for configuration on the fly).

Attempting to install a nuget package the other day I got the following error :

Package ‘xyz’ uses features that are not supported by the current version of NuGet. To upgrade NuGet, see http://docs.nuget.org/consume/installing-nuget.

Following the link takes you to this page. Because I am using the inbuild package manager console from Visual Studio, I followed the steps inside VS that say to go Tools > Extensions and Updates and then click the Updates tab to see if I had an update waiting.

I didn’t. Still stuck. Damn.

After a bit of searching I came across this page that has the Visual Studio extensions to be downloaded manually and installed. After downloading the package and installing manually, with a quick restart of visual studio we are up and running on the latest version of Nuget!

If you are unsure if you are on the latest version of Nuget, you can type “nuget help” in your package manager console and it will tell you the version.

If you’re using Gulp across many projects (especially across many open source ones), you may come across errors that look similar to the following :

The issue is caused by having a local gulp install for your project and one installed globally. You can check this by running the command “gulp -v” from a command line. You should see something similar to :

How to fix it? Well first it’s maybe better to understand why this is the case. Why do we have a “local” version of gulp and a global version installed?

The local version is there because it ensures that gulp runs the same on any machine the code is run on. Including your build server or other development machines. Ensuring that the same version is run everywhere is a great way to ensure consistency.

The global version is there because it allows you to type “Gulp” from the command line essentially. Having the executable in your system path is very handy.

The Sledgehammer Fix

I call this the sledgehammer fix because it’s really just brutalizing a solution that happens to work. This fix is to simply update both your CLI and Local Gulp to the same version. You can do this by going into your web project in a command prompt and calling :

Warning. If for any reason your local version or global version was on a specific version of gulp, then you’ve just massacred it. If you’re working in a team you should ask before you do this or be prepared to lose friends in the workplace. Of course, if you’re a one man band and you haven’t picked a version of gulp for any particular reason, then this will work just fine.

The “Slightly More Elegant” Fix

The second fix does take a while of getting used to. Inside your package.json file you can add the following :

You can now run the local installed version of gulp (Without calling the global version), by typing “npm run gulp” from a command line inside your web project. It does take some getting used to if you’ve always just typed straight “gulp” from the command line.

What this does mean is that passing in various options and flags for gulp gets a bit gnarly. You usually end up with something more like the following :

Essentially spelling out all your different options for gulp (Including watches etc) within your scripts section.

The “Elegant” Fix

A more elegant fix is actually by removing gulp entirely from your globals and installing only the CLI. Run the following

This first command removes gulp globally (But not from local installs such as in your web project). The second command installs Gulp-CLI. The CLI is the command line interface for gulp and is the minimum amount to run gulp from the command line, but not actually have any of it’s “working parts” if you will globally. This is great because as above, we learned that the only reason we really have gulp globally is for the command line, not for any working parts. This solves our issue perfectly!