KryptonExceptionDialog - Quick Start Guide

5-Minute Getting Started

Installation

KryptonExceptionDialog is part of the Krypton.Utilities assembly (delivered via Krypton.Standard.Toolkit / Krypton.Toolkit metapackages, depending on how you reference the suite). No separate Utilities-only package is required when you already use the standard suite packages.

Namespace (V110+): Krypton.Utilities — add using Krypton.Utilities;.

Basic Usage

Simple Exception Display

try
{
    // Your code that might throw an exception
    int result = 10 / int.Parse("0");
}
catch (Exception ex)
{
    // Show exception dialog with copy button and search box enabled
    KryptonExceptionDialog.Show(ex, showCopyButton: true, showSearchBox: true);
}

Using Default Values

catch (Exception ex)
{
    // Simple display - no copy button or search box (defaults)
    KryptonExceptionDialog.Show(ex);
    
    // Or explicitly use null to get defaults (both false)
    KryptonExceptionDialog.Show(ex, null, null);
}

With Custom Highlight Color

catch (Exception ex)
{
    // Custom highlight color for search matches
    KryptonExceptionDialog.Show(ex, Color.LightCyan, true, true);
}

With Bug Report Feature

catch (Exception ex)
{
    // Include bug report button with callback
    KryptonExceptionDialog.Show(
        ex, 
        Color.LightYellow,
        showCopyButton: true, 
        showSearchBox: true,
        bugReportCallback: (exception) => 
        {
            // Send to error tracking service
            ErrorTracker.Report(exception);
        }
    );
}

Common Scenarios

Development/Debug Mode

catch (Exception ex)
{
    #if DEBUG
        // Full details in debug mode
        KryptonExceptionDialog.Show(ex, true, true);
    #else
        // User-friendly message in release
        KryptonMessageBox.Show(
            "An error occurred. Please contact support.",
            "Error",
            KryptonMessageBoxButtons.OK,
            KryptonMessageBoxIcon.Error
        );
        
        // Log the exception internally
        LogException(ex);
    #endif
}

Global Exception Handler

static class Program
{
    [STAThread]
    static void Main()
    {
        Application.ThreadException += (sender, e) =>
        {
            KryptonExceptionDialog.Show(e.Exception, true, true);
        };
        
        Application.Run(new MainForm());
    }
}

With Auto-Context Capture

using Krypton.Toolkit;

try
{
    ProcessData();
}
catch (Exception ex)
{
    // Automatically captures file name, line number, and method name
    KryptonExceptionHandler.CaptureException(
        ex,
        title: "Data Processing Failed",
        showStackTrace: true,
        useExceptionDialog: true
    );
}

Key Features at a Glance

Feature Description Parameter
Exception Tree Navigate exception hierarchy Always visible
Search Search exceptions and stack traces showSearchBox
Copy to Clipboard Copy formatted exception details showCopyButton
Stack Traces View complete call stack with line numbers Always visible
Inner Exceptions Drill down into exception chains Always visible
Exception Data View custom exception data Always visible if present
Theming Matches current Krypton theme Automatic

Method Signatures

KryptonExceptionDialog

// Overload 1: Simple display (defaults)
KryptonExceptionDialog.Show(Exception exception);

// Overload 2: With highlight color
KryptonExceptionDialog.Show(Exception exception, Color? highlightColor);

// Overload 3: With copy and search controls
KryptonExceptionDialog.Show(
    Exception exception,      // Required: the exception to display
    bool? showCopyButton,    // Optional: show copy button (default: false)
    bool? showSearchBox      // Optional: show search box (default: false)
);

// Overload 4: With highlight color and controls
KryptonExceptionDialog.Show(
    Exception exception,
    Color? highlightColor,   // Optional: highlight color (default: LightYellow)
    bool? showCopyButton,    // Optional: show copy button (default: false)
    bool? showSearchBox      // Optional: show search box (default: false)
);

// Overload 5: Full featured with bug report callback
KryptonExceptionDialog.Show(
    Exception exception,
    Color? highlightColor,           // Optional: highlight color (default: LightYellow)
    bool? showCopyButton,            // Optional: show copy button (default: false)
    bool? showSearchBox,             // Optional: show search box (default: false)
    Action<Exception>? bugReportCallback  // Optional: callback for bug report button
);

KryptonExceptionHandler

// Advanced API with auto-context capture
KryptonExceptionHandler.CaptureException(
    Exception exception,                  // Required
    string title = "Exception Caught",   // Optional
    [CallerFilePath] string callerFilePath = "",     // Auto-captured
    [CallerLineNumber] int lineNumber = 0,           // Auto-captured
    [CallerMemberName] string callerMethod = "",     // Auto-captured
    bool showStackTrace = false,                     // Optional
    bool? useExceptionDialog = true                  // Optional
);

// Log to file
KryptonExceptionHandler.PrintStackTrace(
    Exception exception,
    string fileName
);

Dialog Controls

What Users See

Left Panel (Exception Tree):

  • Root exception with type and message
  • Stack Trace node (expandable)
    • Each stack frame with file/line info
  • Inner Exception node (if present)
    • Recursive exception chain
  • Data node (if custom data present)
    • Key-value pairs

Right Panel (Details):

  • Type: Exception type name
  • Message: Exception message
  • Stack Trace: Formatted call stack
  • Inner Exception: Inner exception info or "None"

Bottom:

  • Copy button (copies all details to clipboard)
  • OK button (closes dialog)

Search Functionality

When search is enabled:

  1. Type in the search box at the top of the tree panel
  2. Tree automatically filters to matching nodes
  3. Matches are highlighted in bold with yellow background
  4. Result count displayed (e.g., "3 results found")
  5. Click the X button to clear search

Common Patterns

Pattern 1: Try-Catch-Display

try
{
    DoWork();
}
catch (Exception ex)
{
    KryptonExceptionDialog.Show(ex, true, true);
}

Pattern 2: Try-Catch-Log-Display

try
{
    DoWork();
}
catch (Exception ex)
{
    Logger.Error(ex, "Failed to do work");
    KryptonExceptionDialog.Show(ex, true, true);
}

Pattern 3: Try-Catch-Save-Display

try
{
    DoWork();
}
catch (Exception ex)
{
    string logFile = $"error_{DateTime.Now:yyyyMMdd_HHmmss}.log";
    KryptonExceptionHandler.PrintStackTrace(ex, logFile);
    KryptonExceptionDialog.Show(ex, true, true);
}

Pattern 4: Conditional Display

try
{
    DoWork();
}
catch (Exception ex)
{
    if (AppSettings.ShowDetailedErrors)
    {
        KryptonExceptionDialog.Show(ex, true, true);
    }
    else
    {
        KryptonMessageBox.Show("An error occurred.", "Error");
    }
}

Customization

Localization

All strings are customizable via KryptonManager.Strings.ExceptionDialogStrings:

// Set at application startup
KryptonManager.Strings.ExceptionDialogStrings.WindowTitle = "Error Details";
KryptonManager.Strings.ExceptionDialogStrings.SearchBoxCueText = "Type to search...";
KryptonManager.Strings.ExceptionDialogStrings.StackTrace = "Call Stack";
KryptonManager.Strings.ExceptionDialogStrings.CopyDetailsButtonText = "Copy";
KryptonManager.Strings.ExceptionDialogStrings.ReportBugButtonText = "Report Bug";
// ... etc

Hide Features

// No search or copy features
KryptonExceptionDialog.Show(ex, showCopyButton: false, showSearchBox: false);

// Just the tree and details

Best Practices

✅ DO

  • Use in development/debug builds
  • Use in admin/diagnostic tools
  • Log exceptions before showing dialog
  • Use meaningful exception messages
  • Provide context with KryptonExceptionHandler.CaptureException

❌ DON'T

  • Show to end users in production (too technical)
  • Use for validation errors (use specific messages)
  • Call from background threads without Invoke
  • Display for expected/recoverable errors
  • Forget to log exceptions before showing

Thread Safety

Always invoke from the UI thread:

Task.Run(() =>
{
    try
    {
        BackgroundWork();
    }
    catch (Exception ex)
    {
        // Marshal to UI thread
        if (mainForm.InvokeRequired)
        {
            mainForm.Invoke(() => KryptonExceptionDialog.Show(ex, true, true));
        }
        else
        {
            KryptonExceptionDialog.Show(ex, true, true);
        }
    }
});

Troubleshooting

Dialog doesn't appear

  • Check if exception is null
  • Verify you're on the UI thread
  • Check if application is in interactive mode

Copy button is disabled

  • Click on an exception node in the tree (not "Stack Trace" or "Inner Exception" parent nodes)
  • Details panel must have text

Search not working

  • Ensure showSearchBox is explicitly set to true (defaults to false)
  • Try clicking in the search box

More Information

For comprehensive API documentation, see:

For related components:

  • KryptonMessageBox
  • KryptonForm
  • Exception Handling Best Practices