🧩 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:

Field	Description	Example
Namespace	Originating namespace	MyApp.Services.User
Class & Method	Fully-qualified method name	UserService.AuthenticateUser(string username)
Line Number	Exact source line	42
Property	(Optional) Null property name	User.ProfileImage
File Path	Optional file and path	C:\Projects\MyApp\Services\UserService.cs
FullRoad (Call Chain)	Hierarchical call sequence with layer tags	[Controller] → [Service] → [Repository]

---

⚙️ Configuration via NullGuardOptions

Option	Type	Description	Default
ProjectNamespacePrefix	string	Root namespace used for filtering	(Required)
ShowPathFile	bool	Include file path	false
ShowExceptionMessage	bool	Include original message	true
ShowCallChain	bool	Include FullRoad call analysis	true
MaxChainLength	int	Max depth for call chain	15

---

🚀 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 طراحی شده است.
در زمان وقوع خطا، این ابزار مسیر فراخوانی را بررسی کرده و فقط بخش‌هایی از کد پروژه‌ی شما را که به خطا مرتبط هستند، فیلتر و گزارش می‌کند.

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

---

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

ویژگی	نوع	توضیح	پیش‌فرض
ProjectNamespacePrefix	string	فضای نام اصلی پروژه	الزامی
ShowPathFile	bool	نمایش مسیر فایل	false
ShowExceptionMessage	bool	نمایش پیام خطا	true
ShowCallChain	bool	نمایش مسیر فراخوانی	true
MaxChainLength	int	حداکثر عمق مسیر	15

---

🚀 راه‌اندازی سریع در 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