Asp.Net Core Health Checks Complete Guide

Step 1: Create a New ASP.NET Core Web Application

First, let's create a new ASP.NET Core Web Application. You can do this either via the .NET CLI or Visual Studio.

Using the .NET CLI:

Open a command prompt or terminal and run the following command:

dotnet new mvc -n HealthCheckDemo
cd HealthCheckDemo

Using Visual Studio:

1. Open Visual Studio.
2. Select "Create a new project".
3. Choose "ASP.NET Core Web App (Model-View-Controller)" and click Next.
4. Set the project name to HealthCheckDemo and location, then click Create.
5. Choose .NET 6.0 (Long-term support) or later and click Create.

Step 2: Add the Health Checks Package

ASP.NET Core includes built-in packages for health checks. However, for custom health checks, you might need to add the Microsoft.Extensions.Diagnostics.HealthChecks NuGet package.

Using the .NET CLI:

Run the following command in your terminal:

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks

Using Visual Studio:

1. Right-click on your project in Solution Explorer.
2. Select "Manage NuGet Packages...".
3. Go to the "Browse" tab and search for Microsoft.Extensions.Diagnostics.HealthChecks.
4. Click Install.

Step 3: Configure Health Checks

Now, let’s configure health checks in Program.cs (in .NET 6 and later) or Startup.cs (in .NET 5 and earlier).

For .NET 6 and later:

In your Program.cs, configure the health checks as follows:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();

// Add health checks
builder.Services.AddHealthChecks();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

// Add health checks endpoints
app.MapHealthChecks("/health");

app.Run();

For .NET 5 and earlier:

In your Startup.cs, configure the health checks as follows:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllersWithViews();

        // Add health checks
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(
                name: "default",
                pattern: "{controller=Home}/{action=Index}/{id?}");

            // Add health checks endpoints
            endpoints.MapHealthChecks("/health");
        });
    }
}

Step 4: Define Custom Health Checks

You can create custom health checks to monitor specific parts of your application or external dependencies.

Create a new class CustomHealthCheck.cs:

using Microsoft.Extensions.Diagnostics.HealthChecks;
using System.Threading;
using System.Threading.Tasks;

public class CustomHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        // Implement custom health check logic here
        var isHealthy = true; // Example condition

        if (isHealthy)
        {
            return Task.FromResult(HealthCheckResult.Healthy("Custom health check is healthy"));
        }

        return Task.FromResult(HealthCheckResult.Unhealthy("Custom health check is unhealthy"));
    }
}

Step 5: Register Custom Health Checks

Register your custom health check in Program.cs or Startup.cs:

For .NET 6 and later:

In your Program.cs, add the custom health check:

// Add health checks
builder.Services.AddHealthChecks()
    .AddCheck<CustomHealthCheck>("custom_health_check");

For .NET 5 and earlier:

In your Startup.cs, add the custom health check:

services.AddHealthChecks()
    .AddCheck<CustomHealthCheck>("custom_health_check");

Step 6: Test Health Checks

Run your application and navigate to /health to see the health check status.

dotnet run

Open your browser and go to https://localhost:5001/health.

You should see a JSON response indicating the health status. If your custom health check is healthy, you will see something like:

{
  "status": "Healthy",
  "totalDuration": "00:00:00.0012345",
  "entries": {
    "custom_health_check": {
      "data": {},
      "description": "Custom health check is healthy",
      "duration": "00:00:00.0012345",
      "status": "Healthy"
    }
  }
}

Step 7: Add More Health Checks

You can add more built-in or custom health checks as needed. For example, to add a database health check:

1. Install the dependency package:

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.SqlServer

2. Update the health checks configuration in Program.cs or Startup.cs:

For .NET 6 and later:

builder.Services.AddHealthChecks()
    .AddCheck<CustomHealthCheck>("custom_health_check")
    .AddSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection"),
        "Database health check");

For .NET 5 and earlier: