NetOffice Logging Adapter for NLog

[jozefizso]

Parent

• Improve NetOffice Logging Architecture #500

What to build

Provide an optional native NetOffice adapter for NLog. A final application supplies an application-owned NLog LogFactory; the adapter exposes it through the provider-neutral NetOffice logging contract without requiring Microsoft Extensions Logging, an NLog target, or NLog in NetOfficeFw.Core.

The adapter creates and caches an NLog Logger for each NetOffice category so the category becomes the native logger name. It maps NetOffice levels to NLog levels and creates LogEventInfo records containing the original exception, original message template and parameters, and structured EventId and EventName properties. NLog remains responsible for rendering, routing, filtering, scopes, and target execution.

The category logger's native level check must run before allocating avoidable event state. The adapter must not mutate LogManager global configuration, install targets or rules, flush NLog, or dispose the supplied LogFactory. Applications that prefer the global factory can explicitly pass LogManager.LogFactory; ownership remains with the application.

The package depends only on NetOfficeFw.Core and NLog's core package. It must not reference MEL or a concrete target package. Its public configuration API must accept a specific LogFactory and configure a specific Core, with ownership behavior stated explicitly. It must remain compatible with the repository's .NET Framework and strong-name requirements.

Documentation must distinguish this native route from NLog's MEL provider used with the Microsoft Extensions Logging adapter. Configuring both routes for one Core must be explicitly discouraged because it can duplicate every event.

Acceptance criteria

• Installing this package is optional and does not add NLog to NetOfficeFw.Core.
• The adapter has no MEL or concrete target dependency.
• An application can configure a specific Core from an application-owned NLog LogFactory.
• NetOffice categories map to cached NLog loggers with matching native logger names.
• Every NetOffice level maps to the intended NLog level and respects native enablement.
• Each LogEventInfo retains the stable numeric event ID and event name as structured properties.
• The original message template and parameters remain available to NLog's structured-message processing.
• The exact original exception is attached to the NLog event.
• Disabled events avoid unnecessary LogEventInfo creation, parameter processing, and target invocation.
• The adapter does not mutate global NLog configuration, install targets or rules, flush, or dispose the supplied factory.
• Tests use a test-owned LogFactory and memory target to verify category, level, event properties, template properties, exception identity, filtering, and logger failure isolation.
• Package output is compatible with the repository's .NET Framework target and signing conventions.
• Usage guidance explains native NLog versus NLog-through-MEL and prevents accidental double logging.

Blocked by

• None (can start immediately; implement against the provider-neutral contract specified by Improve NetOffice Logging Architecture #500).