NeonLog.CSharp 0.1.0-ci.73

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. ASP.NET Core Request Logging Middleware: NeonLog.CSharp.AspNetCore

A separate package that integrates with the ASP.NET Core pipeline. Writes a structured completion log event for every HTTP request.

Registration

using NeonLog.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Register NeonLog as the logging provider
builder.Logging.AddNeonLog(builder.Configuration.GetSection("NeonLog"));

var app = builder.Build();

// Add the middleware early in the pipeline (after error handling, before routing)
app.UseNeonLogRequestLogging();

app.MapControllers();
app.Run();

Dynamic log level

The GetLevel delegate receives the HttpContext, elapsed time in milliseconds, and any exception. Default logic matches the Serilog UseSerilogRequestLogging example:

app.UseNeonLogRequestLogging(options =>
{
    options.GetLevel = (httpContext, elapsedMs, ex) =>
    {
        if (ex != null) return NeonLogLevel.Error;
        if (httpContext.Response.StatusCode > 499) return NeonLogLevel.Error;

        var path = httpContext.Request?.Path.Value?.ToLowerInvariant();
        if (path == "/" || (path?.StartsWith("/health") ?? false))
            return NeonLogLevel.Verbose;

        return NeonLogLevel.Information;
    };
});

Enrichment

Custom properties from HttpContext can be added via EnrichDiagnosticContext:

app.UseNeonLogRequestLogging(options =>
{
    options.EnrichDiagnosticContext = (props, ctx) =>
    {
        props["CorrelationId"] = ctx.TraceIdentifier;
    };
});

Because the middleware populates NeonLogHttpRequestContext, the HttpRequest enricher automatically attaches request properties (method, path, user-agent, client IP, status code, elapsed) to every downstream log event within the request scope.

Options

9. 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}" }
      }
    ]
  }
}

10. 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>:

11. 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.

12. 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.

Packing NeonLog.CSharp.AspNetCore

dotnet pack bindings/dotnet/NeonLog.CSharp.AspNetCore/NeonLog.CSharp.AspNetCore.csproj -c Release

The AspNetCore package has no native assets — it depends on NeonLog.CSharp for the native runtime. Both packages are produced by CI and published to GitHub Packages on version tags.

13. 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