Updated 7/17/2018: This package will be released in ASP.NET Core 2.2 which is going to come out in Q4 2018 currently.

CAVEAT: This is pre-released software.  There isn’t even a NuGet package for it yet.  The GitHub repo lives here – https://github.com/dotnet-architecture/HealthChecks that I cloned and manually added a project reference to a new demo app.  There is a plan for it to get made into a NuGet package, but that hasn’t happened yet.

With that said – I will keep this post updated as I see changes being made, and will eventually remove the Caveat above.

tldr;

Register your Health Checks in your ConfigureServices method.

Inject in an IHealthCheckService and call CheckHealthAsync to run all your Health Checks, or another method like RunCheckAsync or RunGroupAsync to run a subset of the Health Checks you registered in ConfigureServices.

What is a Health Check?

Health Checks are pretty much what the name implies.  They are a way of checking to see if your application is healthy.  Health Checks have become especially critical as more and more applications are moving to a microservice-style architecture.  While microservice architectures have many benefits, one of the downsides is there is a higher operations overhead to ensuring all of these services are running.  Rather than monitoring the health of one majestic monolith, you need to monitor the status of many different services, which are usually responsible for one thing and one thing only.  Health Checks are usually used in combination with a service discovery tool such as Consul that monitor your microservices for when they become healthy and unhealthy.  If you use Consul for service discovery as well, Consul will automatically route traffic away from your unhealthy microservices and only serve traffic to your healthy microservices… which is awesome.

 

How do I implement a Health Check?

There are a few different ways to do Health Checks, but the most common way is exposing an HTTP endpoint to your application dedicated to doing Health Checks.  Typically you will return a status code of 200 if everything is good, and any non-2xx code means something went wrong.  For example, you might return a 500 if something went wrong along with a JSON payload of what exactly went wrong.

 

Common scenarios to Health Check

What you Health Check will be based on what your application/microservice does, but some common things:

• Can my service connect to a database?
• Can my service query a 3rd party API?
  • Likely making some read-only call
• Can my service access the file system?
• Is the Memory and/or CPU above a certain threshold?

 

Looking at the Microsoft.AspNetCore.HealthChecks package

Microsoft is on the verge of shipping a set of Health Check packages to help you solve this problem in a consistent way.  If you look in the GitHub repo you will notice there is also a package for ASP.NET 4.x as well under the Microsoft.AspNet.HealthChecks namespace.  There is a samples folder on that GitHub repo that contains how to wire that up if you’re interested in ASP.NET 4.x.  I’m going to focus on the ASP.NET Core package for this blog post.

The Microsoft.AspNetCore.HealthChecks package targets netcoreapp1.0, but I suspect this will change to be either netcoreapp2.0 or netstandard2.0 by the time this RTM’s.  The ASP.NET 4 project targets net461, and all the other libraries target netstandard1.3which works with both .NET Core and Full Framework.

 

Getting Started

The basic flow is that you register your health checks in your IoC container of choice (such as the built-in Microsoft one, although I prefer SimpleInjector due to the fantastic feature set, blazing speed, and ridiculously good documentation, but I’ll just use the built-in one for these demos).  You register these Health Checks via a fluent HealthCheckBuilder API in your Startup‘s ConfigureServices method.  This HealthCheckBuilder will build a HealthCheckService and register it as an IHealthCheckService​ in your IoC container.

That looks something like this:

 

So to run your Health Checks you inject in an IHealthCheckService into your Controller and then call CheckHealthAsync.

 

There are a few things to note here:

1. You get back a CompositeHealthCheckResult which is a summary of all of your health checks that you registered in your AddHealthChecks method in your Startup class.
2. That CompositeHealthCheckResult class has a CheckStatus property which is an enum.  That enum has 4 options – Healthy, Unhealthy, Warning, and Unknown. You can determine what you want to do with each of those.  In my simple example above, I consider anything other than Healthy to be a problem and return a 500 if it’s not Healthy.

 

You can also loop over the results of the CompositeHealthCheckResult by looking at the Results property and get even more detail about what exactly happened.

You can optionally run a single Health Check by calling RunCheckAsync and supplying the name of the Health Check that you registered in your ConfigureServices method (more on that later).

 

Out of the box Health Checks

Microsoft ships quite a few Health Checks out of the box that fit into the Common Scenarios section above.  They are:

• URL Health Check via AddUrlCheck
• SQL Server Health Check via AddSqlCheck
• PrivateMemorySizeCheck via AddPrivateMemorySizeCheck
• VirtualMemorySizeCheck via AddVirtualMemorySizeCheck
• WorkingSetCheck via AddWorkingSetCheck
• A few Azure Health Checks (such as BLOB Storage, Table Storage, File Storage, and Queue storage).

Let’s take a look at the URL Health Check and the SQL Server Health Check.

 

URL Health Checks

The URL Health Check lets you specify a URL and then it will execute a GET to that URL and see if the URL returns a Success Status Code or not (any 2xx Status Code like 200).

You can register the URL Health Check by adding this.

Then you inject your IHealthCheckService and call CheckHealthAsync as shown above.  If you want to just run this single Health Check, and not others you may have registered, you’ll need to know that the name is not configurable.  The name will be UrlCheck(https://github.com)​.  So you would run that single check with  RunCheckAsync("UrlCheck(https://github.com)").

Another thing to note, that second parameter where I’m passing TimeSpan.FromMilliseconds(1) is the CacheDuration of the HealthCheckResult.  The default is 5 minutes.  So if you have some other service (like Consul) pinging your Health Check endpoint every minute, the HealthCheckResult will be the same for 5 minutes until the CacheDuration expires.  To me, that doesn’t make a ton of sense, and I don’t want to risk an up to 5 minute delay on being notified when my service becomes unhealthy.  So by only adding a 1 millisecond cache, I’m effectively adding no caching at all.

There is also another parameter to the AddUrlCheck method where you can pass a Func to the URL Checker.  This is nice in scenarios such as:

• You want to execute something other than a GET.
• You need to do something special with the HttpRequest in general such as add Auth Headers or something.
• You want to validate the response’s Content contains some specific words or HTML.

So the URL Check should satisfy just about any Web check you could possibly want to do with that flexibility.

 

Built-in SQL Server Health Checks

The SQL Check lets you specify a name and a connection string to connect to.

The first parameter, “SQL DB Check”, is just the name I chose.  You can make it whatever makes sense to you.  To run this check, as mentioned above, you would call this from IHealthCheckService.

 

Making your own custom Health Check

You can of course make your own custom Health Check.  For me, most of my use cases are solved by the built-in ones, as I’m usually checking if an API is available (which I could do with the URL Check and overriding the checkFunc parameter) or I’m checking to see if a SQL Server is available.  But you could implement your own if you are missing some functionality that you need such as checking if another DB store is available or how much free space a drive has.

To do that, derive from IHealthCheck and implement the interface.  Below is an example of one that checks to make sure the C drive has at least 1 GB of free space.

Then in your ConfigureServices method, register the custom Health Check with the lifestyle that makes sense for the Health Check (Singleton, Scoped, Transient, etc.) and then add it to the AddHealthChecks registration that we’ve done before.

That’s it!

 

Group your health checks together

You can group your health checks together in a HealthCheckGroup if you want (such as all performance checks like CPU, Memory, Disk Space, etc. go under a group called “performance”) or you can let them live on their own and mix and match.

This enables you to do things like only call that Group of Health Checks via the RunGroupAsync method off of IHealthCheckService.

 

Security

Reminder – this is demo code.  Some flaws include that my Health Check endpoint is unsecured and anyone can hit the endpoint.  You will likely want to secure your Health Check endpoint, especially if it is on the Internet, so someone doesn’t spam your Health Check endpoint.  There are many ways to do this, but are outside the scope of this blog post.

 

Some Feedback on the Design

Overall I think this abstraction is really useful, and I will use it myself once it RTM’s.  The built-in health checks are nice, so that you don’t have to write that logic yourself.  I’m all about punting as much logic onto someone else as possible.

There are some little things I wish were a little easier though.

1. It seems like the HealthCheckResult.CheckStatus == CheckStatus.Healthy code  is going to be extremely common.  It’d be nice if there was a helper prop off of HealthCheckResult like HealthCheckResult.IsHealthy which does that computation for you.  Much like HttpResponseMessage has a IsSuccessStatusCode property which is super useful.  Although, I understand that “Healthy” is a relative term that’s tough to globally define.  Some people might think that the CheckStatus.Warning would qualify as being Healthy and others wouldn’t.  Ubiquitous languages are hard.
2. I wish there was a way you could override the name for the built-in Health Checks.  Like the URL Health Check automatically takes on the Name UrlCheck(yourUrlHere) such as UrlCheck(http://google.com).  You’ll need this name if you want to pull out the specific results of a Health Check.  I had expected to be able to specify the name of each Health Check and store it in something like a HealthCheckConstants class for easily retrieval.  Instead, I need to follow this convention when using the constants class, which isn’t the end of the world, but being able to override the name would be nice.
3. When calling the RunGroupAsync method, I wish you could just specify the group name rather than the HealthCheckGroup instance and let the RunGroupAsync method handle getting the HealthCheckGroup instance.
4. There should be no Cache Duration on the URL Check.  5 minutes is just too long of a default, and IMO there should be no Cache Duration at all on the URL Check.  I control the frequency of how often my Health Check monitoring service hits my health check endpoint.  If I want it to check my service every minute, then I’d probably expect the Health Check result to be fresh every time and not be cached.

 

Overall, I really like this package, and it seems like it’s going to be really useful.   I plan on using this when it RTM’s, so I’ll keep this post up to date when I see they make changes to this package.

The Problem

If you’ve ever seen this message when hitting your ASP.NET Core app:

“An error occurred while starting the application.  .NET Framework <version number> | Microsoft.AspNetCore.Hosting version <version number> | Microsoft Windows <version number>”

It looks a little something like this:

 

What Happened?

It basically means something really bad happened with your app.  Some things that might have gone wrong:

1. You might not have the correct .NET Core version installed on the server.
2. You might be missing DLL’s
3. Something went wrong in your Program.cs or Startup.cs before any exception handling kicked in

 

Event Viewer (probably) won’t show you anything

If you’re running on Windows and behind IIS, you might immediately go to the Event Viewer to see what happened based on your previous ASP.NET knowledge.  You’ll notice that the error is not there.  This is because Event Logging must be wired up explicitly and you’ll need to use the Microsoft.Extensions.Logging.EventLog package, and depending on the error, you might not have a chance to even catch it to log to the Event Viewer.

 

How to figure what happened (if running on IIS)

Instead of the Event Viewer, if you’re running behind IIS, we can log the request out to a file.  To do that:

1. Open your web.config
2. Change stdoutLogEnabled=true
3. Create a logs folder
   1. Unfortunately, the AspNetCoreModule doesn’t create the folder for you by default
      1. If you forget to create the logs folder, an error will be logged to the Event Viewer that says: Warning: Could not create stdoutLogFile \\?\YourPath\logs\stdout_timestamp.log, ErrorCode = -2147024893.
   2. The “stdout” part of  the value “.\logs\stdout” actually references the filename not the folder.  Which is a bit confusing.
4. Run your request again, then open the \logs\stdout_*.log file

Note – you will want to turn this off after you’re done troubleshooting, as it is a performance hit.

So your web.config’s aspNetCore element should look something like this

 <aspNetCore processPath=”.\YourProjectName.exe” stdoutLogEnabled=”true” stdoutLogFile=”.\logs\stdout” />

 

Doing this will log all the requests out to this file and when the exception occurs, it will give you the full stack trace of what happened in the \logs\stdout_*.log file

 

 

 

Hope this helps.  This happened to me a friend of mine.  A friend.  Yep.  Definitely not me.  My apps would never bomb.

tldr;

In ASP.NET Core you can hook up a route to be your global exception handler.  Simply add the ExceptionHandler middleware to your Startup.cs Configure method:

In your HomeController’s Error action, add this code to get the exception that was raised, as well as the route that caused the exception, and then you can do something with it (log to a database, send an email/text/fax/carrier pidgeon).

You can checkout this GitHub commit if you’d prefer to see it that way.

 

The start of the non-tldr;

No ELMAH in ASP.NET Core… yet

In pre-Core versions of ASP.NET, ELMAH was a popular library for doing Global Exception Handling.  When unhandled exceptions occurred, it let you do things like log them to a database, send an e-mail, etc. automagically.  Unfortunately, ELMAH is not ported to ASP.NET Core yet, so this led me to look at what other options were out there.

You could use one of the many of the Cloud providers for this like Application Insights, elmah.io (unaffiliated with the ELMAH project) or Exceptionless, but what if your company requires you to stay on-prem?  You can use Exception Filters, but those have some limitations, and I found a simpler way (arguably) that I didn’t find a blog post on, so I thought I’d write one up.

 

Step 1 – Hook up the ExceptionHandler middleware

If you’ve done much with ASP.NET Core, this will look very familiar to you.  First you need to hook up the ExceptionHandler middleware by adding this line to the Configure method of your Startup.cs:

What that does is anytime an uncaught exception happens, it will send the request to the route listening on the path you  specified.  In the example above (and the default in the templates), that’s the Error Action on the Home Controller, obviously you can just change that to whatever you want.

Often, you’ll only want to use the Exception Handler in non-development environments, and instead use the DeveloperExceptionPage in Development, which is the new YSOD that gives you a stack trace and other good information.

A sample Configure method showing this is below:

 

Step 2 – Use IExceptionHandlerPathFeature to get the exception and the Path

Make sure you have the Microsoft.AspNetCore.Diagnostics NuGet package in your .csproj, or if you have the Microsoft.AspNetCore meta-package, then that contains the Microsoft.AspNetCore.Diagnostics package, so you’re all set.

In the action of the controller you’re listening on (in the above case, the Error action on the Home Controller).  Add the following code to your Error action.

Breaking the code down

The code is pretty straight forward, but let’s break it down.  When an exception occurs, an IExceptionHandlerPathFeature is set.  This contains two properties: 1) the Path of the route at which the exception occurred (such as /Home/Index), and 2) the Exception that occurred under the Error property.  After that, you can do whatever you want with this information such as log it to a database, send an e-mail or trigger a carrier pidgeon (I believe the CarrierPidgeon API is coming back in .NET Standard 2.0).

If you want to see the code that makes IExceptionHandlerPathFeature work, you can view go to GitHub here and see the code where they set the Path in the ExceptionHandler middleware that we rigged up in our Startup class.

 

Make sure you get the right Feature

Be careful to make sure you get an IExceptionHandlerPathFeature with the Path in the name.  There is also a IExceptionHandlerFeature without Path in the name that does not have the Path of where the exception occurred.  Obviously, it’s pretty useful to know the source route of where the exception happened.

 

Make sure you catch any Exceptions in your Exception Handler Action

Also be careful and make sure to catch any exceptions in your Exception Handler Action.  Causing a second exception in your exception handler action will cause the entire middleware to stop and you’ll end up with a blank page and a 500 status code.  A scenario where this could happen is if you’re logging the exception to a database, but your database is down causing an exception.

 

Microsoft.AspNetCore.Diagnostics.Elm

Microsoft provides a package called ELM (Error Logging Middleware) that has some similar features to what ELMAH did.  One of the main features ELM has is it allows you to see events on a web page that aggregates those events.  You can read more about that here.  However, there doesn’t seem to be any intent to extend ELM to do things like report to a database or send e-mails, based on this response from Eilon of the ASP.NET team here, and it is non-persistent through app restarts.  In my scenarios, we don’t have a ton of use for this, as we prefer to be able to look and query for logs in a database, but I thought I’d mention it in case it is useful for your scenarios.

 

Additionally – AppDomains Coming Back in .NET Standard 2.0

If you’re using .NET Core (and not full framework), AppDomains are coming back in .NET Standard 2.0 to help with global exception handling, as described by Damian Edwards in the ASP.NET Community Standup here: https://youtu.be/_3y0QsXj2e4?t=31m17s 

 

Don’t like using IExceptionHandlerPathFeature in your Controller action?

That’s ok.  There’s another way to achieve this same thing using raw middleware, even bypassing IExceptionHandlerPathFeature completely, but I’ll save that for a followup blog post, as this is approaching 1000 words.

Thanks for reading!

Update 8/29/2017: 

When running ASP.NET Core 2:

• Using .NET Core 2
  • You no longer have to do anything.  The app will precompile by default on publish.
• Using full .NET Framework
  • The only thing you need is the package reference below.

 

Below is the original post for ASP.NET Core 1

 

I didn’t see this documented on docs.asp.net yet for .csproj style projects, so I thought I’d blog about it, as it’s something I do on every project.

tldr;

Add this to your .csproj file:

Alternatively, you can check out this GitHub commit that just adds pre-compiled views here.

Also – if you’re running on .NET Core and not Full Framework, then make sure your TargetFramework is netcoreapp1.1+ and not netcoreapp1.0.

What does precompiling views do?

Without precompiling your views, none of your views are compiled until they are requested for the first time.  This results in an extra few seconds of wait time for the end user.  Instead, most developers want to take a little bit of extra time in the publish step to precompile their views, so that users don’t have to eat that performance hit on the first request on every page.

Another benefit of precompiling your views is if there is a C# error on one of your .cshtml Razor pages (such as you changed the name of a property on your View Model and the rename didn’t update your .cshtml file), you will find out up front when you go to publish (via VS or a build server) rather than at run time when a user goes to request that page.

So now that we’ve seen what it does, let’s look at what it used to be in project.json.

What did it look like in project.json?

In project.json land, the pre-compiling of Views was a little verbose.  You had to do the following:

1. Add a reference to “Microsoft.AspNetCore.Mvc.Razor.ViewCompilation.Design” under the “dependencies” section
2. Add a reference to “Microsoft.AspNetCore.Mvc.Razor.ViewCompilation.Tools” under the tools section.
3. Under buildOptions, set “preserveCompilationContext”to true
4. And finally you had to add a fairly verbose post-publish script to actually use the pre-compile tool.All of that looked like this (removing the rest of the project.json for brevity):

This then generates a .PrecompiledViews.dll in the root of your publish directory.  You will have no refs folder as well.

How does it look in .csproj?

In project.json, it was pretty verbose.  So what does it look like in .csproj?  It’s much cleaner.

1. Add <MvcRazorCompileOnPublish>true</MvcRazorCompileOnPublish>
2. Add <PackageReference Include=“Microsoft.AspNetCore.Mvc.Razor.ViewCompilation“ Version=“1.1.0“ />

 

So the final output of a .csproj might look a little something like this.  Note lines 5,6, and 32.

This will still generate a .PrecompiledViews.dll in the root of your publish directory and you will still have no refs folder.

This simplicity in order to get precompiled views is yet another win for the .csproj style ASP.NET Core projects over project.json.

tl;dr

The primary use case for fallbacks in the Script Tag Helper is checking if a CDN is down and loading a local script instead.  Another use case is you can use fallbacks to make it easy to polyfill missing JavaScript features in older browsers, while not having your users using the latest browsers take a network hit.

View this gist on GitHub

Background – What is a Polyfill?

A polyfill is a fallback, written in JavaScript, that fills in a new JavaScript feature that is missing in an older browser and replicates the same functionality that newer browsers provide natively.  This allows JavaScript code using the latest features only available in newer browsers to work on older browsers as well.

To polyfill the API, you simply just check if that API is available, and if not, load the polyfill that adds that API to your browser.  That way, if your user is using the latest browser, you don’t punish them by downloading something they don’t need and hurting their performance.

How a Polyfill works

This JavaScript code will polyfill the “new” fetch API for making AJAX calls, that is currently available in all of the latest major browsers (Chrome, Edge, Firefox, Safari, etc.), but not in any of the Internet Explorer family tree (not even IE11).

First, the code looks to see if the Promise API is available, because fetch relies on Promises in order to work.  If the API is not available, it loads a script from a CDN that polyfills the Promise API.  It does the same thing for the fetch API.

The built-in Script Tag Helper – CDN fallback

The built-in Script Tag Helper in ASP.NET Core has fallback support baked in that generates code very close to this.  The original intent of their fallback support was for attempting to load a script from a CDN.  After loading from that CDN, test to see if a JavaScript API is available, and if it’s not (due to the CDN being down, blocked, or whatever) fall back to loading a local JavaScript file.  That code looks like this:

The fallback works for polyfills too!

What I haven’t seen anyone mention is to use this to conditionally polyfill if a JavaScript feature doesn’t exist.  And it works right out of the box, simply omit the src attribute, and the rest will be taken care of:

The code above will generate nearly identical code to what’s in the first code sample.  As mentioned above, fetch needs Promises to work, so I’m also polyfilling that conditionally as well.  In the real world, I would likely bundle these two together (locally or using something like Polyfill.io) and make one network request, but using unpkg (an NPM CDN) was just for simplicity’s sake.

With the code above, I get the best of both worlds.  My code using fetch runs on older browsers, but my users who use the latest browsers don’t take a network hit for something they don’t need.  This same methodology will work for other ES2015 and above features and is nice for small apps that want to use some of the latest features and not have to deal with the build config of Babel or TypeScript transpiling down to ES5.

I’m not sure if this was an intended feature of the Script Tag Helper, but it’s a good use case for the fallback feature that I hadn’t seen anyone talk about, so I wanted to call attention to it.

And if you are lucky enough to only have to support Chrome at work.  I assume this is you right now reading the hoops us plebes have to go through to get our code to run on all browsers:

https://media.giphy.com/media/l3nWqD4ViFej9REAw/giphy.gif