🌐 Global Error Handling in ASP.NET Core with Custom Middleware and Serilog

Error handling is a fundamental part of building reliable APIs. In this post, I’ll walk you through how to implement global error handling in ASP.NET Core using custom middleware — with clean JSON error responses and Serilog for structured logging.

🧠 Why Use Global Error Handling?
Instead of wrapping every controller action in a try-catch, we can centralize error handling using middleware. This gives us:

✅ Clean, consistent error responses
✅ Less duplicated code
✅ Easy error tracing with unique IDs
✅ Integration with logging libraries like Serilog

🔧 Step 1: Create the Middleware Class

using System.Net; namespace MyApp.Middlewares { public class ExceptionHandlerMiddleware { private readonly ILogger<ExceptionHandlerMiddleware> _logger; private readonly RequestDelegate _next; public ExceptionHandlerMiddleware(ILogger<ExceptionHandlerMiddleware> logger, RequestDelegate next) { _logger = logger; _next = next; } public async Task InvokeAsync(HttpContext httpContext) { try { await _next(httpContext); } catch (Exception ex) { var errorId = Guid.NewGuid(); // Log the error with a unique identifier _logger.LogError(ex, $"[{errorId}] Unhandled exception: {ex.Message}"); httpContext.Response.StatusCode = (int)HttpStatusCode.InternalServerError; httpContext.Response.ContentType = "application/json"; var error = new { Id = errorId, ErrorMessage = "Something went wrong. Please contact support with the error ID." }; await httpContext.Response.WriteAsJsonAsync(error); } } } } 

📝 This middleware:

• Catches any unhandled exceptions
• Logs them with a unique Guid
• Returns a friendly error message in JSON format

⚙️ Step 2: Register the Middleware in Program.cs
Make sure it's registered early in the request pipeline:

var app = builder.Build(); // Add our global exception handler middleware app.UseMiddleware<ExceptionHandlerMiddleware>(); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.MapControllers(); 

🧪 Step 3: Throw an Error in a Controller to Test

[HttpGet] public IActionResult Crash() { throw new Exception("Simulated crash!"); } 

Call this endpoint. You should see:

• A clean JSON response with an error ID
• An error logged in console/file (if Serilog is configured)

✍️ Bonus: Integrate Serilog for Logging
Add Serilog via NuGet:

dotnet add package Serilog.AspNetCore dotnet add package Serilog.Sinks.Console dotnet add package Serilog.Sinks.File 

Then, update your Program.cs:

using Serilog; Log.Logger = new LoggerConfiguration() .MinimumLevel.Information() .WriteTo.Console() .WriteTo.File("Logs/log.txt", rollingInterval: RollingInterval.Day) .CreateLogger(); builder.Logging.ClearProviders(); builder.Logging.AddSerilog(); 

Now all _logger.LogError() calls in your middleware (and anywhere else) will log to both the console and Logs/log.txt.

🧼 Best Practices

• ❗ Keep your middleware early in the pipeline.
• ✅ Always return consistent JSON error structures.
• ➕ Add contextual info like UserId, RequestPath, etc., if needed.
• 📋 Consider logging HTTP context data (cautiously) in production.
• 💡 Use log enrichment with Serilog for deeper insights.

✅ Final Thoughts
Global exception handling with custom middleware is a clean and scalable way to handle API errors. It improves developer experience, user experience, and observability — especially when paired with Serilog.