PAS_SA_Chocolate 2.0.1

Chocolate Logger (ChocoLogger)

A high-performance, asynchronous logging library for .NET 8 applications with support for structured log formatting and Windows Event Log integration.

Overview

ChocoLogger is a lightweight, static logging utility designed for WPF and .NET applications that provides:

• Asynchronous logging using a background queue to prevent blocking caller threads
• Structured log format with timestamp, log level, class name, method name, and line number
• Configurable log levels (DEBUG, INFO, HIGHLIGHT, WARN, ERROR)
• Automatic log rotation when file size exceeds limits
• Windows Event Log integration (optional)
• Caller context tracking using C# attributes for automatic source file, method, and line number capture

Features

• ✅ Thread-safe asynchronous logging
• ✅ Minimal performance overhead on calling threads
• ✅ Graceful shutdown with buffered log flushing
• ✅ Bootstrap logging for initialization errors
• ✅ Exception formatting with stack traces
• ✅ Configurable minimum log level filtering
• ✅ Auto-rotation/deletion at 5 MB file size
• ✅ Cross-platform support (Windows Event Log on Windows only)

Installation

Add a project reference to Chocolate.csproj:

<ProjectReference Include="..\Chocolate\Chocolate.csproj" />

Or install the NuGet package (if published):

dotnet add package PAS_SA_Chocolate

Quick Start

Initialization

Initialize the logger once at application startup:

using Chocolate;

// Basic initialization
ChocoLogger.Initialize("C:\\Logs\\app.log");

// With custom log level
ChocoLogger.Initialize("C:\\Logs\\app.log", "INFO");

// Enable Windows Event Log (Windows only, requires admin rights)
ChocoLogger.EnableWindowsEventLog("MyAppSource", "Application");

Logging Messages

// Different log levels
ChocoLogger.Debug("Debugging information");
ChocoLogger.Info("General information");
ChocoLogger.Highlight("Important information");
ChocoLogger.Warn("Warning message");
ChocoLogger.Error("Error occurred");

// With exception details
try
{
    // Your code
}
catch (Exception ex)
{
    ChocoLogger.Error("Failed to process request", ex);
}

Shutdown

Ensure all logs are flushed before application exit:

// On application shutdown
ChocoLogger.Shutdown();

Log Format

Logs are written in a structured, pipe-delimited format:

HH:mm:ss.fff LEVEL | ClassName          | MethodName:LineNumber     | Message
14:23:45.123 INFO  | MyClass     | ProcessData:42            | Processing started
14:23:45.456 ERROR | DatabaseService    | SaveRecord:128            | Connection failed
  Exception: System.InvalidOperationException: Database unavailable
  StackTrace: at DatabaseService.SaveRecord() in C:\Code\Database.cs:line 128

Log Levels

Configuration

Minimum Log Level

Set the minimum log level to filter out less important messages:

// Only INFO and above will be logged
ChocoLogger.Initialize("app.log", "INFO");

Log File Size Management

• Maximum file size: 5 MB (configurable via MaxLogFileSizeBytes)
• Behavior: When exceeded, the current log file is deleted and a new one is created
• Alternative: Uncomment ArchiveLogFile() in WriteLog() to archive instead of delete

Testing

The project includes xUnit tests in the Chocolate.Tests project:

dotnet test Chocolate.Tests

Test coverage includes:

• Logger initialization
• Log message enqueueing
• Log parsing (multiple formats)
• Error handling

Architecture

Components

• ChocoLogger: Main static class exposing logging methods
• BlockingCollection<Action>: Thread-safe queue for log actions
• Background Task: Long-running task processing queued log actions
• Bootstrap Logger: Fallback logging for initialization errors

Threading Model

1. Calling thread: Enqueues log action (non-blocking)
2. Background thread: Processes queue and writes to file
3. Shutdown: Completes queue and waits for flush (max 1.5s timeout)

Best Practices

1. Initialize early: Call Initialize() as soon as possible in your application startup
2. Shutdown gracefully: Always call Shutdown() before application exit
3. Use appropriate levels: Follow log level guidelines for clarity
4. Handle exceptions: Use Error() with exception parameter for full stack traces
5. Avoid sensitive data: Never log passwords, tokens, or PII

Platform Support

• .NET 8.0 (Windows-specific features require net8.0-windows)
• WPF applications
• Windows Event Log (Windows only, requires appropriate permissions)

License

Copyright (c) [2025] PAS SA. All rights reserved.
Proprietary and Confidential.

This software is licensed exclusively to PAS SA for internal development
and operational purposes. Unauthorized copying, distribution, or use
is strictly prohibited.

Support

For issues or questions, contact the PAS SA development team.

Project: Chocolate Logger
Version: .NET 8.0
Build Date: October 31, 2025