NullGuard.AspNetCore.Diagnostics 1.0.1

🧩 NullGuard.Diagnostics Guide

Advanced NullReferenceException Diagnostic Toolkit for .NET

🇬🇧 English

🎯 Purpose and Core Philosophy

NullGuard.Diagnostics is a specialized .NET diagnostic tool designed to intelligently capture and analyze NullReferenceException (NRE) with rich contextual information — far beyond the standard .NET exception messages.

Unlike typical exception handlers, it filters stack frames to isolate only those from your own project code, removing internal framework noise (like Kestrel, ASP.NET Core internals, or third-party dependencies).

The resulting diagnostic report is structured to maximize debugging efficiency, pinpointing exactly where and why the null occurred.

🧠 Detailed Diagnostic Output

When an NRE is caught and processed, the following structured data is captured:

⚙️ Configuration via NullGuardOptions

🚀 Quick Setup (ASP.NET Core)

Register the service:

builder.Services.AddScoped(sp => new NullGuardService(new NullGuardOptions
{
    ProjectNamespacePrefix = "MyCompany.SuperApp",
    ShowPathFile = true,
    ShowExceptionMessage = true,
    ShowCallChain = true
}));

Register middleware (must be first):

var app = builder.Build();

app.UseMiddleware<NullGuardMiddleware>(); // place this BEFORE UseExceptionHandler()

🧩 Example Diagnostic Output

=====================================================================================
NULLGUARD DIAGNOSTIC REPORT
Timestamp (UTC): 2024-10-27T15:05:12.887Z
Exception Type: System.NullReferenceException

Failing Location Details:
Namespace: MyApp.Infrastructure.Data
Class & Method: DataService.SaveEntity(Entity e)
Line Number: 22
File Name: DataService.cs (Full Path Hidden)
Original Message: Object reference not set to an instance of an object.

FullRoad Call Chain Analysis:
[Controller] -> ApiController.Create(payload)
[Service] -> DataService.SaveEntity(e)
=====================================================================================

🇮🇷 فارسی

🎯 هدف و فلسفه اصلی

کتابخانه NullGuard.Diagnostics برای تشخیص و تحلیل هوشمند خطاهای NullReferenceException طراحی شده است.
در زمان وقوع خطا، این ابزار مسیر فراخوانی را بررسی کرده و فقط بخش‌هایی از کد پروژه‌ی شما را که به خطا مرتبط هستند، فیلتر و گزارش می‌کند.

این گزارش به شما کمک می‌کند دقیقاً بفهمید کدام متد، در چه خطی، و در چه لایه‌ای از معماری برنامه باعث بروز خطا شده است.

⚙️ تنظیمات قابل پیکربندی

🚀 راه‌اندازی سریع در ASP.NET Core

ثبت سرویس‌ها:

builder.Services.AddScoped(sp => new NullGuardService(new NullGuardOptions
{
    ProjectNamespacePrefix = "Your.Project.Namespace",
    ShowPathFile = true,
    ShowExceptionMessage = true,
    ShowCallChain = true
}));

ثبت Middleware:

var app = builder.Build();
app.UseMiddleware<NullGuardMiddleware>(); // قبل از سایر Middlewareها

🧩 مثال خروجی گزارش

NULLGUARD DIAGNOSTIC REPORT
Namespace: MyApp.Services
Class & Method: DataService.SaveEntity(Entity e)
Line Number: 22
File Name: DataService.cs
FullRoad: [Controller] -> [Service]

🧮 Advanced Topics

• Mathematical filtering model
• Precision/Recall analysis of stack frame filtering
• JSON serialization for structured logs
• Middleware interception flow diagram

(See full documentation on GitHub.)

📦 Installation

dotnet add package NullGuard.Diagnostics

© 2025 Mehran Ghaedrahmat — NullGuard.Diagnostics Project
🔗 GitHub Repository