NeonLog.CSharp 0.1.0-ci.58

C# Wrapper for neonlog-c

This directory contains a thin C# P/Invoke wrapper for the native neonlog-c library (see include/neonlog/neonlog.h). It exposes the full native ABI through managed types, supports structured message templates, built-in enrichers, log scopes, HTTP request context, Redis and console sinks, and integrates with Microsoft.Extensions.Logging.

Projects

Quick start

Build the native library and run the examples:

cmake -S . -B build
cmake --build build --config Debug
# Make neonlog.dll discoverable (add build/Debug/ to PATH, or copy next to the managed exe):
$env:PATH += ";$pwd\build\Debug"
dotnet run --project bindings/dotnet/examples/NeonLog.CSharp.Examples.csproj

API Reference

1. Core Types

NeonLogLevel — log severity (0–5)

NeonLogValue — typed log value

Wraps the native neonlog_value_t union. Supports implicit conversions from common .NET types:

NeonLogValue v1 = "hello";     // String
NeonLogValue v2 = -42L;        // Int64
NeonLogValue v3 = 42UL;        // UInt64
NeonLogValue v4 = 3.14;        // Double
NeonLogValue v5 = true;        // Bool
NeonLogValue v6 = NeonLogValue.Null; // Null

// Smaller integer types widen automatically:
int i = 123;    -> Int64
uint u = 456;   -> UInt64
short s = 7;    -> Int64
float f = 2.5f; -> Double

NeonLogProperty — named property

new NeonLogProperty("UserName", "Alice")
new NeonLogProperty("Count", 42L)
new NeonLogProperty("Enabled", true)

NeonLogStatus — native operation result

NeonLogRedisMode — Redis data structure

2. Runtime: NeonLogRuntime

uint abiVersion = NeonLogRuntime.GetAbiVersion();           // e.g. 3
NeonLogRuntime.EnsureCompatibleAbi();                        // throws if mismatch
string statusName = NeonLogRuntime.GetStatusName(status);    // "OK", "INVALID_ARGUMENT"...
string levelName  = NeonLogRuntime.GetLevelName(level);      // "INF", "ERR"...

3. Direct Logger: NeonLogger (simple API)

Create a standalone logger with NeonLogger.Create(NeonLogLoggerOptions):

var options = new NeonLogLoggerOptions
{
    MinimumLevel = NeonLogLevel.Debug,
    ConsoleEnabled = true,
};
options.Properties.Add(new NeonLogProperty("App", "my-app"));
options.Enrichers.Add(NeonLogBuiltInEnricher.Timestamp);

using var logger = NeonLogger.Create(options);

Log methods:

logger.Log(NeonLogLevel.Information, "Hello {Name}", "world");
logger.Verbose("Verbose {X}", 1);
logger.Debug("Debug {Flag}", true);
logger.Information("User {Name} logged in", "Alice");
logger.Warning("Warning {Value}", 0.95);
logger.Error("Error {Code}", 500, "TimeoutException: ...");
logger.Fatal("Fatal {Reason}", "out of memory");

// With errorMessage (exception detail):
logger.Log(NeonLogLevel.Error, "Query failed for {Id}", "qry-1", "Timeout after 30s");

Other members:

bool enabled = logger.IsEnabled(NeonLogLevel.Debug);
using var child = logger.ForContext(new NeonLogProperty("Scope", "handler"));
using IDisposable scope = logger.BeginScope(new NeonLogProperty("Tenant", "acme"));
logger.Flush();
logger.Dispose();

4. Factory Logger: NeonLoggerFactory (advanced API)

Manages a shared native pipeline (sinks + static properties). Creates multiple loggers from it:

var factoryOptions = new NeonLogLoggerFactoryOptions
{
    MinimumLevel = NeonLogLevel.Debug,
};
factoryOptions.Properties.Add(new NeonLogProperty("Application", "my-app"));
factoryOptions.ConsoleSinks.Add(new NeonLogConsoleSinkOptions { Enabled = true, UseColors = true });
factoryOptions.RedisSinks.Add(new NeonLogRedisSinkOptions { Host = "127.0.0.1", Key = "neonlog:app", ... });

using var factory = NeonLoggerFactory.Create(factoryOptions);
using var logger = factory.CreateLogger();
using var child = logger.ForContext(new NeonLogProperty("Scope", "request"));

// Flush at the factory level drains all loggers.
factory.Flush();

NeonLogConsoleSinkOptions

NeonLogRedisSinkOptions

5. Built-in Enrichers: NeonLogBuiltInEnricher

Enrichers add properties automatically to every log event. There are 4 types:

Usage:

options.Enrichers.Add(NeonLogBuiltInEnricher.Timestamp);
options.Enrichers.Add(NeonLogBuiltInEnricher.ProcessInfo);
options.Enrichers.Add(NeonLogBuiltInEnricher.Environment);
options.Enrichers.Add(NeonLogBuiltInEnricher.LogScope);
options.Enrichers.Add(NeonLogBuiltInEnricher.HttpRequest);

6. Scopes: NeonLogScope

Push ambient properties onto an AsyncLocal stack. Paired with the LogScope enricher.

using (logger.BeginScope(new NeonLogProperty("RequestId", "req-123")))
using (NeonLogScope.Push(new NeonLogProperty("Tenant", "acme")))
{
    // Both properties are attached to every log event within this scope.
    logger.Information("Processing order {OrderId}", 42);
}

// Run a callback within a scope:
NeonLogScope.Run(new[] { new NeonLogProperty("Scope", "test") }, () =>
{
    logger.Information("Inside scope");
});

7. HTTP Request Context: NeonLogHttpRequestContext

Attach HTTP request data to the ambient AsyncLocal context. Requires the HttpRequest enricher.

var request = new NeonLogHttpRequestData
{
    RequestMethod = "POST",
    RequestPath = "/api/orders",
    RequestId = "req-abc",
    UserAgent = "MyClient/1.0",
    ClientIp = "10.0.0.1",
    Host = "example.com",
};

using (NeonLogHttpRequestContext.Enter(request))
{
    logger.Information("Processing order");
    NeonLogHttpRequestContext.SetStatusCode(200);
}

// Async variant:
await NeonLogHttpRequestContext.RunAsync(request, async () =>
{
    logger.Information("Inside async context");
    await Task.CompletedTask;
});

8. Configuration from IConfiguration: NeonLogConfigurationOptions

Parse the "NeonLog" config section (appsettings.json, env vars, etc.) into typed options:

var section = config.GetSection("NeonLog");
var options = NeonLogConfigurationOptions.FromConfiguration(section);
var factoryOptions = options.ToFactoryOptions();

Accepts both wrapper-native sections (ConsoleSinks, RedisSinks, Properties, Enrich) and the original NeonLog compatibility shape (WriteTo, Properties object map, Enrich string array).

Example appsettings.json:

{
  "NeonLog": {
    "MinimumLevel": { "Default": "Debug" },
    "Properties": { "Application": "my-app" },
    "Enrich": ["Timestamp", "ProcessInfo", "Environment", "LogScope"],
    "ConsoleSinks": [
      {
        "Enabled": true,
        "UseColors": true,
        "OutputTemplate": "[{timestamp}] [{level}] {message}"
      }
    ],
    "RedisSinks": [
      {
        "Enabled": false,
        "Host": "127.0.0.1",
        "Key": "neonlog:app",
        "Mode": "Stream"
      }
    ],
    "WriteTo": [
      {
        "Name": "Console",
        "Args": { "useColors": "true", "outputTemplate": "[{level}] {message}" }
      }
    ]
  }
}

9. Microsoft.Extensions.Logging Integration

Register NeonLog as the standard ILogger<T> provider:

// Option A: from config section
builder.Logging.AddNeonLog(builder.Configuration.GetSection("NeonLog"));

// Option B: from delegate
builder.Logging.AddNeonLog(options =>
{
    options.MinimumLevel = NeonLogLevel.Debug;
    options.Enrich.Add("Timestamp");
});

// Option C: from factory options directly
builder.Logging.AddNeonLog(factoryOptions);

Mapping from ILogger<T>:

10. Error Handling

All native operations throw NeonLogException on failure:

try
{
    using var logger = NeonLogger.Create(options);
    logger.Information("Hello");
}
catch (NeonLogException ex)
{
    Console.WriteLine($"Operation failed: {ex.Message}");
    Console.WriteLine($"Status code: {ex.Status}");
}

The runtime also validates ABI compatibility at the start of every creation method. If the loaded native library reports a different ABI version than the wrapper expects, EnsureCompatibleAbi() throws NotSupportedException.

11. NuGet Packaging

Stage native assets for both platforms, then pack:

# Windows:
./bindings/dotnet/scripts/build-and-stage-native.ps1 -Configuration Release

# Linux:
./bindings/dotnet/scripts/build-and-stage-native.sh Release

# Pack (requires both win-x64 and linux-x64 staged):
dotnet pack bindings/dotnet/NeonLog.CSharp/NeonLog.CSharp.csproj -c Release

The package version defaults to 0.1.0 (from Directory.Build.props). Override with:

dotnet pack ... /p:NeonLogPackageVersion=1.0.0

The pack target fails fast if either native asset is missing.

12. Running Tests

Package consumer tests validate against the packed NuGet (not source):

# After packing:
dotnet test bindings/dotnet/NeonLog.CSharp.PackageTests/NeonLog.CSharp.PackageTests.csproj -c Release

Examples

The examples/ project contains self-contained, runnable examples:

Run:

dotnet run --project bindings/dotnet/examples/NeonLog.CSharp.Examples.csproj

Build from source

# 1. Build the native library
cmake -S . -B build
cmake --build build --config Debug

# 2. Make neonlog.dll discoverable
$env:PATH += ";$pwd\build\Debug"

# 3. Build and run the sample
dotnet run --project bindings/dotnet/NeonLog.CSharp.Sample/NeonLog.CSharp.Sample.csproj

# 4. Build and run the examples
dotnet run --project bindings/dotnet/examples/NeonLog.CSharp.Examples.csproj

# 5. Stage native assets + pack NuGet (requires .NET 8 SDK)
./bindings/dotnet/scripts/build-and-stage-native.ps1 -Configuration Release
dotnet pack bindings/dotnet/NeonLog.CSharp/NeonLog.CSharp.csproj -c Release

# 6. Run package consumer tests
dotnet test bindings/dotnet/NeonLog.CSharp.PackageTests/NeonLog.CSharp.PackageTests.csproj -c Release