Skip to content

logging.md

Latest commit

 

History

History
78 lines (53 loc) · 2.26 KB

logging.md

File metadata and controls

78 lines (53 loc) · 2.26 KB
Raw
layout default

Logging

CHDSharp is silent by default. It integrates with Microsoft.Extensions.Logging so you can route internal diagnostics to any compatible provider.

Enabling logging

Set the static Chd.LoggerFactory before performing library operations:

using Microsoft.Extensions.Logging;
using Serilog;
using Serilog.Extensions.Logging;

var serilogLogger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console()
    .CreateLogger();

Chd.LoggerFactory = new SerilogLoggerFactory(serilogLogger);

// All subsequent Chd/ChdFile operations log through Serilog
var result = Chd.CheckFile(File.OpenRead("game.chd"), "game.chd", deepCheck: true);

Any ILoggerFactory-compatible provider works:

  • Serilog (Serilog.Extensions.Logging)
  • NLog (NLog.Extensions.Logging)
  • Microsoft.Extensions.Logging.Console
  • your own ILoggerFactory implementation

What gets logged

Area Level Examples
Verification Information / Debug progress percentages, array-pool statistics, compression-type statistics per CHD
Metadata Debug tag + length + ASCII payload of every metadata entry
Errors Warning / Error failed metadata reads, precache failures, decompression exceptions (with the inner exception and hunk number)
Per-codec Debug block summaries, repeated-block counts

Because every log call is a pre-compiled LoggerMessage.Define delegate, the overhead is negligible when logging is disabled.

Reset

To disable logging again (e.g. in tests):

Chd.LoggerFactory = null;

Example: log to a file with Serilog

Chd.LoggerFactory = new SerilogLoggerFactory(
    new LoggerConfiguration()
        .MinimumLevel.Information()
        .WriteTo.File("chdsharp.log", rollingInterval: RollingInterval.Day)
        .CreateLogger());

Notes

  • LoggerFactory is read lazily per operation, so you can swap providers at runtime; for predictable behavior, set it once at startup.
  • The logging package (Microsoft.Extensions.Logging.Abstractions) is the library's only non-Zstd dependency and is marked optional in the sense that the library functions perfectly with it never set.