ProphetsWay.Logger
4.0.0
Prefix Reserved
dotnet add package ProphetsWay.Logger --version 4.0.0
NuGet\Install-Package ProphetsWay.Logger -Version 4.0.0
<PackageReference Include="ProphetsWay.Logger" Version="4.0.0" />
<PackageVersion Include="ProphetsWay.Logger" Version="4.0.0" />
<PackageReference Include="ProphetsWay.Logger" />
paket add ProphetsWay.Logger --version 4.0.0
#r "nuget: ProphetsWay.Logger, 4.0.0"
#:package ProphetsWay.Logger@4.0.0
#addin nuget:?package=ProphetsWay.Logger&version=4.0.0
#tool nuget:?package=ProphetsWay.Logger&version=4.0.0
ProphetsWay.Logger
Route log messages to console, file, event, or custom destinations with per-destination severity and label selection.
Current tree: unreleased v4 work. The app variables select
4.0.0; v4 remains unreleased. Logger's optional Linux/macOS jobs are configured and enabled for CI. Initial hosted Linux/macOS attempts failed; no passing native Linux/macOS verification is recorded. Hosted reruns remain required; Windows success and ABI declaration proxies do not certify them. Explicit-registration route isolation and ordered membership snapshots (M2-B) are implemented. Native M3 scopes, entry annotations, full captured context, registration settings and whole-entry label selection are now implemented alongside the six native severities. M4-A adds shared UTC event time, invariant value rendering and quoted single-line text with native scope boundaries. M4-B1 implements explicit-file append/reset, fixed-path output and physical encoding/termination. M4-B2 now integrates ordinary and exact-Tautomatic output into one shared UTF-8 session file, with initial-only recovery and remembered initialization failure. M5 carrier data and both explicit Microsoft bridge directions are implemented in current source: Microsoft-to-Logger inbound and opt-in Logger-to-Microsoft outbound. Configuring one direction does not enable the reverse. Supplied destinations use guarded entrypoints and protectedLogCorehooks; subclasses must migrate their oldLogoverrides. This describes current source, not the published NuGet package, a completed final acceptance gate, or release certification.
Why Logger
When you need both a detailed log and a warning/error view, repeating each logging call for each output adds unnecessary work. Configure destinations once at application startup; plain Logger calls reach enabled registered destinations whose severity and label restrictions accept the entry.
- Send the same message to console, files, or callbacks with different reporting levels.
- Pass application metadata to typed destinations without putting it into message text.
- Carry application-defined labels and scope properties, withholding the whole entry from destinations whose configured policies reject it.
- Evaluate the same label policy independently when you need a membership-only decision.
Configure your intended destinations explicitly. The automatic file is quick-start behavior, not a substitute for choosing output paths, access controls, and retention.
Install
For a published package, use the .NET CLI:
dotnet add package ProphetsWay.Logger
Or use Visual Studio's NuGet Package Manager Console:
Install-Package ProphetsWay.Logger
These commands do not install the unreleased API merely because it is documented here.
To use the native severity, scope/context, label-policy, text/formatter examples, or either Microsoft
logging bridge direction now, reference the current
library project from your application.
app-variables.yml selects 4.0.0 for this unreleased v4 work; no v4 package
or release is claimed.
Current Source Targets
| Project | Targets | Meaning |
|---|---|---|
| Library | netstandard2.0;net10.0 |
.NET Standard 2.0 compatibility floor plus a dedicated .NET 10 asset. |
| Tests | net48;net10.0 |
Windows Framework verification uses the Standard 2.0 library; .NET 10 tests use its dedicated asset. |
| Example | net10.0 |
Console example, built but not run in the focused validation below. |
There is no separate net48 library asset. Older modern runtimes compatible with
.NET Standard 2.0 can still use that floor; removing their dedicated assets does not
automatically strand them. Consumers requiring pre-Standard-2.0 reach cannot use this
new target set. Verification is currently Windows-focused, not equivalent Mac/Linux proof.
The library's sole direct package reference is Microsoft.Extensions.Logging.Abstractions
10.0.12, unconditional for both targets. It flows to consumers together with its normal
transitive dependencies through NuGet resolution. Both Microsoft bridge directions described
below are implemented in current source. This does not mean the currently published package
contains either bridge.
Package Contents And Source Metadata
The unreleased M6 packaging update retains both library assets above. The local package
inspection on 2026-09-29 EDT verified the outputs below before the
Microsoft.Extensions.Logging.Abstractions dependency was added. These are historical
observations, not a package built or validated from the current dependency-bearing candidate:
| Package detail | Verified output or setting |
|---|---|
| Library and XML documentation | The .nupkg contains DLL/XML pairs for netstandard2.0 and net10.0, with 177 documented member entries per XML file. GenerateDocumentationFile is true; missing public XML comments still produce compiler warnings, so this is not complete API documentation. |
| Symbols | IncludeSymbols=true and SymbolPackageFormat=snupkg produce a separate .snupkg with one portable PDB per library asset. |
| Source metadata | PublishRepositoryUrl=true and EmbedUntrackedSources=true are enabled. Each inspected PDB has 38 document records, two embedded sources and a Source Link map targeting commit e7cbc016ffe47a66559ed67750d87641c6e7ca6b. This does not mean every source file is embedded. |
| Package metadata | The package retains its README, changelog and icon, and now carries the repository homepage, tags logging, logger, diagnostics, and repository kind git. |
These settings are in the library project.
Its reproducibility-related ContinuousIntegrationBuild setting is true only when
TF_BUILD is True; local evaluation left it unset, while CI-mode evaluation returned true.
Property evaluation is not proof of reproducible binaries. The measured Source Link metadata
also does not prove remote-source availability or an end-to-end debugger experience.
As of 2026-10-01, recorded restore reuse is accepted under the narrow SDK-01 exception
for the SDK-owned library-packs source; restore was not rerun. The fresh R3 Windows baseline
passed three builds and 672 selected tests on each of net48 and net10.0, with zero failures,
skips or test identity changes. Baseline results alone do not establish independent assertion equivalence,
final verification, current-candidate package qualification or bridge completion. The earlier package
observations above remain historical.
This is historical, partial M6 evidence, not full qualification or release approval. At the time of this 2026-10-01 record, inbound was present and outbound had not yet been implemented; later M5 source adds outbound destinations, described below. Remaining assertion migration, the owner-handled test-project rename, broader consumer/security qualification and deferred non-Windows proof remain separate. At that historical checkpoint the version file selected the pre-v4 release; this update changed neither that selection nor publication status.
2026-10-24 annotation: D025 records explicit owner approval of the test-project rename and accompanying infrastructure/docs. The deferral above describes the historical M6 checkpoint, not a pending approval request. Approval and updated guidance do not establish completed rename verification.
Quick Start
Each C# block below is independent, with its own imports, enclosing types and static entry
method, written for C# 7.3 library compilation. Call its Main or Run method only when you
intend its output. Examples use current declarations and test call patterns. Expected output
describes the source contract, not a recorded execution of these programs.
Log To The Console
Register before logging to avoid implicit file creation. Retain the destination reference so you can remove it. This follows the calls in ConsoleDestinationTests.cs.
Illustrative — not currently present in the repo.
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;
public static class Program
{
public static void Main()
{
var destination = new ConsoleDestination(LogLevels.Trace);
Logger.AddDestination(destination);
try
{
Logger.Trace("Detailed startup trace.");
Logger.Debug("Hello World!");
}
finally
{
Logger.RemoveDestination(destination);
}
}
}
The messages use invariant UTC timestamps, quoted single-line text and exact emitted levels,
TraceOnly and DebugOnly; see Record Layout.
The explicit Trace destination mask accepts all six severities; the constructor's
unchanged default Debug mask does not accept Trace.
Logger.ClearDestinations() clears plain registrations; Logger.ClearDestinations<T>()
clears registrations for that metadata type. Removing or clearing does not dispose your
destinations. Do not log after removing the last destination unless you intend fallback.
For no-setup output and optional startup configuration, see Automatic File Output.
Evaluate A Label Policy
This example does not call Logger or write a log file. The identifiers are synthetic, not predefined classifications. The rules and copied-membership behavior are exercised in DestinationLabelPolicyTests.cs.
Illustrative — not currently present in the repo.
using System;
using System.Collections.Generic;
using ProphetsWay.Utilities;
public static class Program
{
public static void Main()
{
var personal = new SensitivityLabel("PII");
var internalUse = new SensitivityLabel("Internal");
var configured = new List<SensitivityLabel>
{
personal, internalUse, new SensitivityLabel("PII")
};
var allow = new DestinationLabelPolicy(LabelFilterMode.AllowOnly, configured);
configured.Clear();
Console.WriteLine(personal.Equals(new SensitivityLabel("PII")));
Console.WriteLine(allow.Mode);
Console.WriteLine(allow.Labels.Count);
Console.WriteLine(allow.Allows(new[] { personal, internalUse }));
Console.WriteLine(allow.Allows(new[] { new SensitivityLabel("pii") }));
Console.WriteLine(allow.Allows(new SensitivityLabel[0]));
var exclude = new DestinationLabelPolicy(LabelFilterMode.Exclude, new[] { personal });
Console.WriteLine(exclude.Allows(new[] { internalUse }));
Console.WriteLine(exclude.Allows(new[] { personal, internalUse }));
var noFilter = new DestinationLabelPolicy(LabelFilterMode.NoFilter, new SensitivityLabel[0]);
Console.WriteLine(noFilter.Allows(new[] { personal }));
}
}
Expected output from the source/test contract, not a recorded execution of this snippet:
True
AllowOnly
2
True
False
False
True
False
True
Allows returns only label eligibility. It neither registers a destination nor intercepts
a later Logger.Debug call by itself. Attach the policy through registration settings or a
supplied destination's LabelPolicy to enforce it during delivery.
Attach Scopes And Read Delivered Context
Use scopes for labels and properties shared by an operation, and LogAnnotated for labels
specific to one entry. This event recipient accepts only entries whose complete effective
label set is nonempty and contained in its configured membership. All data here is synthetic;
the example creates no file. The scope and context assertions live in
LoggerTests.cs.
Illustrative — not currently present in the repo.
using System;
using System.Collections.Generic;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;
public static class ScopeExample
{
public static void Run()
{
var internalUse = new SensitivityLabel("Internal");
var personal = new SensitivityLabel("PersonalData");
var policy = new DestinationLabelPolicy(
LabelFilterMode.AllowOnly, new[] { internalUse, personal });
var destination = new EventDestination(LogLevels.Trace);
destination.LoggingEvent += ReadEntry;
Logger.AddDestination(destination,
new DestinationRegistrationSettings(true, LogLevels.Trace, policy));
var properties = new List<KeyValuePair<string, object>>
{
new KeyValuePair<string, object>("Step", "Receive"),
new KeyValuePair<string, object>("Step", "Validate")
};
try
{
using (Logger.BeginScope(null, properties))
{
properties.Clear();
using (Logger.BeginScope(new LogAnnotations(new[] { internalUse, internalUse })))
{
Logger.LogAnnotated(new LogAnnotations(new[] { personal }),
LogLevels.InformationOnly, message: "Synthetic request.");
}
}
Logger.SetDestinationSettings(destination, new DestinationRegistrationSettings(
true, LogLevels.Trace,
new DestinationLabelPolicy(LabelFilterMode.AllowOnly, new SensitivityLabel[0])));
Logger.Info("Deliberately rejected without activating fallback.");
}
finally
{
Logger.RemoveDestination(destination);
}
}
private static void ReadEntry(object sender, EventDestination.LoggerEventArgs entry)
{
var context = entry.Context;
Console.WriteLine(entry.RawMessage);
foreach (var label in context.Labels.EffectiveLabels)
Console.WriteLine("Effective label: {0}", label.Identifier);
foreach (var origin in context.Labels.Origins)
Console.WriteLine("{0}: scope {1}, occurrence {2}", origin.Label.Identifier,
origin.ScopeIndex.HasValue ? origin.ScopeIndex.Value.ToString() : "entry",
origin.OccurrenceIndex);
foreach (var frame in context.Scopes)
foreach (var property in frame.Properties)
Console.WriteLine("{0}: {1}", property.Key, property.Value);
}
}
The unlabeled outer frame keeps both Step pairs despite properties.Clear(). The repeated
Internal label contributes separate origins but one effective identity. Origin scope indices
address context.Labels.ScopeAnnotations, so they do not count that unlabeled outer frame.
The final settings replacement keeps an enabled reject-all registration; it does not remove
the recipient or cause automatic output. The callback explicitly formats its synthetic property
values; Logger itself does not implicitly format arbitrary scope objects.
Core Concepts
Namespaces
The package and assembly are ProphetsWay.Logger; the utility namespace deliberately differs.
| Import | Use |
|---|---|
ProphetsWay.Utilities |
Logger, LogLevels, ordinary destination contracts/bases, label/policy types, LogAnnotations, scope/context types and DestinationRegistrationSettings. |
ProphetsWay.Utilities.LoggerDestinations |
ConsoleDestination, FileDestination, EventDestination, GenericEventDestination<T>, TextBasedDestination, GenericTextBasedDestination<T>. |
ProphetsWay.Utilities.Generics |
ILoggingDestination<T>, IContextLoggingDestination<T>, BaseLoggingDestination<T>, ILoggerMetadata, and metadata extension methods. |
Severity Selection
These are the current source values in LogLevels.cs. Each helper emits one exact bit; an inclusive destination setting accepts that severity and every more severe one.
| Helper | Exact message bit | Inclusive destination mask | Accepted severities |
|---|---|---|---|
Trace |
TraceOnly = 32 |
Trace = 63 |
Trace, Debug, Information, Warning, Error, Critical. |
Debug |
DebugOnly = 16 |
Debug = 31 |
Debug, Information, Warning, Error, Critical. |
Info |
InformationOnly = 8 |
Information = 15 |
Information, Warning, Error, Critical. |
Warn |
WarningOnly = 4 |
Warning = 7 |
Warning, Error, Critical. |
Error |
ErrorOnly = 2 |
Error = 3 |
Error, Critical. |
Critical |
Critical = 1 |
Critical = 1 |
Critical only. |
LogLevels is an Int32 flags enum with these eleven names. There is no CriticalOnly,
None, or All alias. Use an exact bit as the destination mask for just that severity,
or combine bits with |. Security and SecurityOnly have been removed.
Destination masks accept every integer from 0 through 63, including unnamed combinations.
Zero is an active reject-all destination, not an absent registration or a reason to use fallback.
Raw/direct message masks accept 1 through 63, never zero. Eligibility requires
(messageLevel & destinationMask) == messageLevel: message mask 9 passes destination 15
but fails destination 8. A valid mismatch returns normally without delivery.
The core's enum, integer and string constructors preserve equivalent accepted bits.
Strings use case-sensitive Enum.TryParse<LogLevels> grammar: decimal Int32 text or
comma-separated recognized names, with its surrounding/token whitespace handling.
Signs and leading zeroes follow that parser too: " +009 " is 9 and "-0" is zero.
"0", "9", " +9 ", and "Critical, InformationOnly" are valid; duplicate names combine
by OR. Empty/whitespace-only text, wrong-case names, removed/unknown names, empty comma
tokens, "Critical|InformationOnly", "Critical, 8", "1, 8", "0x9", overflow, negative
values and unknown bits are rejected. Invalid text no longer silently selects Information.
Prefer named masks; configure LogLevels.Trace explicitly when you need all six severities.
Label Identity
SensitivityLabel.cs defines a sealed immutable
reference value. Identifier retains exactly what you supplied: 1 through 256 UTF-16 code
units, with no unit accepted by Char.IsWhiteSpace or Char.IsControl on the executing runtime.
There is no other syntax restriction, trimming, case folding, Unicode normalization, or registry.
Use Equals or collection value comparisons: separate labels with the same ordinal identifier
are equal; PII and pii are distinct. No value-equality == operator is supplied. Equal labels
have equal hashes, but hashes are neither unique nor a persistent or cryptographic identity.
See SensitivityLabelTests.cs.
Annotation Occurrences
LogAnnotations.cs provides a sealed immutable value
for one explicit label attachment. Construct it with
LogAnnotations(IEnumerable<SensitivityLabel> labels) and read its getter-only
ReadOnlyCollection<SensitivityLabel> LabelOccurrences. Construction copies the complete
finite sequence before returning: empty is valid, order and every repeated occurrence survive,
and later source additions, removals or replacements cannot change the captured value.
These are occurrences, not the deduplicated membership used by DestinationLabelPolicy.
Labels retain SensitivityLabel's ordinal value equality; LogAnnotations does not define
annotation-value equality. Reusing a value does not combine attachments or merge their origins.
Construction alone attaches nothing. Pass it to Logger.BeginScope or Logger.LogAnnotated;
ordinary and typed convenience helpers inherit scopes without adding an entry annotation.
See LogAnnotationsTests.cs.
Scopes And Captured Context
Logger.BeginScope(annotations) opens a label-only frame; the two-argument form also captures
an ordered sequence of KeyValuePair<string, object>. A null annotation means no attachment;
a non-null empty annotation is retained as an explicit empty attachment. Neither subtracts
outer labels. Opening a scope does not log anything or change registrations.
Read the completed LogContext from a permitted event or contextual recipient:
| Readback | Meaning |
|---|---|
context.EventTimestampUtc |
Getter-only DateTimeOffset with offset zero, captured once for this call before recipient callbacks. |
context.Scopes |
Every frame, outermost first, including inherited, empty and unlabeled frames. Each exposes Annotations and Properties. |
context.Labels.EntryAnnotations |
This entry's explicit attachment, or null. |
context.Labels.ScopeAnnotations |
The ordered non-null annotation projection of Scopes; empty attachments and repeated uses remain separate. |
context.Labels.Origins |
One record per occurrence, scope attachments first then entry; each has Label, ScopeIndex and OccurrenceIndex. |
context.Labels.EffectiveLabels |
The complete ordinal-identity union of all origins, with duplicates removed; ordering is unspecified. |
All selected contexts and supplied text records from one originating call share that UTC value, including same-call internal forwarding. Retained contexts keep it after scope exit. Recursive Logger calls and supplied-base public direct calls sample anew; distinct or increasing values and cross-thread ordering are not promised. This is event time, not filename or output time.
ScopeIndex is zero-based into ScopeAnnotations, not Scopes; null identifies the entry.
OccurrenceIndex is zero-based within that attachment's LabelOccurrences. Empty attachments
occupy projection positions but contribute no origins. Inherited-only labels count as labeled.
Context/frame/origin values are library-created, with no public constructors or ambient-capture
factory; readback is data, not reusable delivery permission.
Properties are copied membership, not a dictionary or a deep clone. Pair order, duplicate keys,
null/empty/whitespace keys, default pairs and original values/references survive. Later source-list
changes and scope exit cannot alter captured membership; nested objects can still change.
Logger does not inspect getters, enumerate nested values, call their ToString, classify them
or strip capabilities already reachable through them. Retaining recipients own safe retention
and later cleanup. See LogScopeFrame.cs and
LogContext.cs.
Use using blocks and dispose each handle only in the opening operation or its normal
continuation, including across await. Normally captured child work inherits active frames;
its own scope additions/cleanup do not change parent or sibling frames. A child can outlive
parent scope exit and retain the captured labels. Deliberately suppressing execution-context
flow prevents inheritance by newly queued work, without clearing the caller or earlier captures.
Explicitly passed objects still require your classification.
Cleanup removes the handle's frame when current, throws InvalidOperationException without
mutation when it is below another active frame, and is a no-op when locally absent, including
repeat cleanup after unrelated scopes open. Handles are non-transferable: do not delegate their
disposal to independent work. There is no creator-ID/fork workflow or promise to detect every
inherited-handle misuse. Supported inner scopes cannot remove inherited labels; deliberate or
accidental handle misuse is not sandboxed. Ending a scope disposes neither destinations nor
property values and does not revoke or erase captures. This is the accepted D024 discipline in
docs/decision-log.md.
Policy Membership
LabelFilterMode is not a flags enum. Construct a policy with exactly one mode and a
non-null sequence of non-null labels. Mode is getter-only; Labels is an owned
ReadOnlyCollection<SensitivityLabel> containing one representative per configured identity,
even for NoFilter. Later changes to the source collection cannot change the policy.
| Mode | Result for valid effective labels |
|---|---|
NoFilter = 0 |
Always true, including unlabeled input; still validates input. |
Exclude = 1 |
True only when no effective identity is configured. Any intersection denies. |
AllowOnly = 2 |
True only for nonempty effective membership wholly contained in configured membership. |
Empty Exclude permits every valid input; empty AllowOnly denies every valid input. Duplicates
and ordering do not change matching. Unknown valid identities participate normally.
When calling Allows yourself, supply all effective labels, including inherited ones: the
predicate alone does not collect scopes or origins. Logger supplies the full captured union
when enforcing registration and supplied-destination policies.
Registration Settings
DestinationRegistrationSettings(bool enabled, LogLevels reportingLevel, DestinationLabelPolicy labelPolicy)
requires all three arguments and exposes getter-only Enabled, ReportingLevel and LabelPolicy.
Pass it to Logger.AddDestination(destination, settings) or its exact-T overload. The original
one-argument add means enabled, registration mask Trace (63), and empty NoFilter: no added
restriction, not an override of the recipient's own severity mask.
Logger.SetDestinationSettings(destination, settings) and its generic form replace all settings
atomically on an existing registration, preserving its insertion position. They are not upserts.
Existing captures keep their old settings; later captures, including recursive logging, see
published replacements. Sharing a settings value across routes does not couple future replacements.
An enabled registration suppresses fallback even when its mask is zero or its policy rejects everything. A disabled registration retains its position and duplicate identity but is neither attempted nor counted for fallback suppression. Disabling the last enabled recipient can therefore reactivate existing fallback behavior; disabling and rejecting are not interchangeable.
Supplied destinations also expose LabelPolicy, initially empty NoFilter, through
LoggingDestinationCore. Replacing it atomically changes that destination's own restriction,
including direct calls, not its registration settings. Delivery must pass the registration mask,
recipient severity permission, registration policy and supplied policy. Logger captures supplied
policies before callbacks too; an earlier callback cannot change a later recipient's checks for
the current call. No global transaction across separate destination objects is promised.
M5 Carrier Data
The current source implements three public data types in ProphetsWay.Utilities, with
internal, library-only constructors. There is no public constructor or entry-construction
factory; the inbound provider described below creates entries from Microsoft logging calls.
| Type | Captured data |
|---|---|
LogBridgeEntry.cs: LogBridgeEntry |
Common view: CategoryName, nullable EventId, full nonzero native OriginalLevel, separate RawMessage and cached FormattedMessage, original Exception, ordered Properties, external Scopes, explicit Annotations, original NativeContext and separate BridgeMetadata. |
LogBridgeEntryOfT.cs: LogBridgeEntry<TState> |
Sealed typed entry retaining original State and exact ProducerFormatter delegate, including absent/default inputs. StateType is the declared typeof(TState); OriginalState and OriginalProducerFormatter expose the common views. |
LogBridgeScope.cs: LogBridgeScope |
Sealed external frame retaining opaque/scalar State, ordered Properties and explicitly mapped Annotations; data, not a live scope or disposal handle. |
Owned read-only membership preserves supplied order, duplicate keys, null keys/values,
default pairs, repeated frames and label occurrences despite later source-list edits.
An absent EventId differs from a present default value; available identity includes its
name. An absent annotation differs from a present-empty attachment. Bridge-owned metadata
does not overwrite identically named application properties.
NativeContext keeps its original native frames and origin indices. External origins belong
to the entry attachment or a position in Scopes, then that attachment's occurrence position.
The domains remain separate, without reindexing or inventing cross-system order.
Read-only membership is not deep freezing or authorization. Original state, exception and nested objects can remain mutable or sensitive; the retained delegate is an executable capability. Construction/readback does not invoke it, inspect nested graphs, classify payloads, open ambient scopes or dispose supplied objects. You own safe retention and later handling.
The carriers themselves perform no delivery, scope replay or private cycle control. Their construction/readback specifications concern this data component, not current-package qualification or release readiness.
The public IMicrosoftLogLabelMapper
interface in ProphetsWay.Utilities is also available in current source. MapEntry<TState>
and MapScope return optional LogAnnotations for an external entry or scope frame,
respectively; null means no attachment. Both accept ordered, read-only properties as
ReadOnlyCollection<KeyValuePair<string, object>>; state and nested values are not frozen.
You supply classification explicitly; this is not automatic classification or sanitization.
Microsoft Logging Inbound Bridge
The current source exposes MicrosoftLoggerFactoryExtensions.AddProphetsWay(ILoggerFactory, IMicrosoftLogLabelMapper = null). An explicit call creates one MicrosoftLoggerProvider, registers
that provider with the supplied factory, and returns the same provider. It is a factory extension,
not dependency-injection or host configuration. MicrosoftLoggerProvider.CreateLogger creates
category-bound MicrosoftLogger instances that share the provider's lifetime and scope source.
Inbound entries are dispatched through the exact LogBridgeEntry metadata route; the payload retains
its concrete LogBridgeEntry<TState> type. The optional mapper is borrowed and is invoked only when
explicitly supplied to map external entries and scope frames to optional annotations. The factory is
also borrowed. The host must arrange provider cleanup, either by explicitly disposing the returned
provider or through the factory/provider's normal lifetime handling; provider disposal is idempotent.
The provider does not dispose the factory, mapper, a caller-supplied external scope source, or native
destinations. The provider starts with its own logical-flow scope source; a source supplied
through factory scope integration is borrowed. The caller/factory remains responsible for
disposing scope handles through that source's normal cleanup.
This is current unreleased source behavior, not a claim that the published package includes the bridge. Enabling inbound does not install outbound; the outbound direction is a separate, explicitly registered destination path described next. This documentation does not claim M5/M6 completion, current-package qualification, or release readiness.
Microsoft Logging Outbound Destinations
To send native Logger entries to Microsoft logging abstractions, construct and explicitly register
a destination. Construction alone does not register it, create an inbound provider, or configure a
host. The ordinary and exact-declared-T destinations have these public constructors:
| Destination | Public constructors |
|---|---|
MicrosoftLoggerDestination |
MicrosoftLoggerDestination(LogLevels reportingLevel, ILoggerFactory factory, string defaultCategoryName = "ProphetsWay.Logger"); MicrosoftLoggerDestination(LogLevels reportingLevel, ILogger logger) |
GenericMicrosoftLoggerDestination<T> |
GenericMicrosoftLoggerDestination<T>(LogLevels reportingLevel, ILoggerFactory factory, string defaultCategoryName = "ProphetsWay.Logger"); GenericMicrosoftLoggerDestination<T>(LogLevels reportingLevel, ILogger logger) |
Register the ordinary destination with Logger.AddDestination(destination) and an exact route
with Logger.AddDestination<T>(destination), where T is the declared native metadata type used
by that route. Runtime subtype compatibility does not select the exact-T route. The factory and
fixed logger overloads are alternatives; the factory overload creates a logger for each admitted
attempt, using the source category when available and defaultCategoryName only when that category
is null. Empty or whitespace categories are retained as supplied. A fixed logger keeps its own
category. The default factory category is ProphetsWay.Logger.
The reportingLevel constructor argument must be a known native mask from 0 through 63; zero is
a valid active reject-all mask. Native registration severity and label policies are evaluated before
Microsoft callbacks. The adapter maps the lowest set bit of the permitted native mask to one
Microsoft level (Critical, Error, Warning, Information, Debug, or Trace) and retains the
complete original mask in the bridge entry. It calls ILogger.IsEnabled once for that mapped level; false is an ordinary
rejection, not a failure or a reason to activate fallback. A composite mask is not expanded into
multiple Microsoft records.
For a fresh ordinary native call, the entry's typed state is the original message string; for an
exact-T call, it is the original declared-T metadata, including null or default(T). The
completed LogBridgeEntry retains available category/event identity, original mask, exception,
state, formatted text, and ordered structured properties when metadata supplies
IEnumerable<KeyValuePair<string, object>>, as well as annotation/context facts. Other metadata
remains opaque; application property membership and duplicate keys are preserved rather than
flattened. A controlled
return from the inbound bridge preserves its original typed entry and producer-formatter association
rather than wrapping the entry as new metadata or re-running its producer formatter; a fresh call
with carrier-shaped metadata is still a new event. Private transfer bookkeeping suppresses only a
route already visited by that same controlled entry; the guard is not enumerable state, and fresh or
unrelated recursive calls remain eligible. The Microsoft call receives an internal ordered transport
envelope with three separate items: ProphetsWay.Entry, ProphetsWay.NativeContexts, and
ProphetsWay.ExternalScopes. The native-context group retains the source capture first, then distinct
controlled/current captures in encounter order; only a capture already present by reference is
omitted, not a distinct capture with overlapping frames or labels. Event properties remain inside
the entry; native contexts and external scope frames are not flattened
into application properties. Scope replay supplies a separate one-frame envelope per native or
external frame, preserving each frame's state/properties/annotations and occurrence; native frames
follow context order and each capture's outer-to-inner order, then external frames follow their
retained order. Existing Microsoft host scopes remain in place; successfully returned scope handles are cleaned up in
reverse opening order. A null BeginScope result means there is no handle to clean up, not a failed
scope capture.
Native labels and explicitly mapped external annotations remain distinct from application
properties and are evaluated as whole-entry policy before the destination's Microsoft callbacks.
The bridge does not infer labels from property names, classify or sanitize payloads, or promise
that consumer-owned state is safe to retain. The destination borrows its supplied factory or fixed
logger; Logger registration, removal, clearing, or replacement does not dispose them. The adapter
owns only per-attempt transport/bookkeeping and returned scope-handle cleanup. Calls are synchronous;
there is no category cache, queue, retry, remote-delivery receipt, or durability guarantee. An
IsEnabled rejection is normal; factory, logger, scope, or cleanup failures follow Logger's safe
output-failure reporting and propagation contract after independent eligible attempts.
API Reference
The tables summarize the current declarations, not proposed APIs.
| Member | Current use |
|---|---|
SensitivityLabel(string identifier) |
Create an immutable identity; read Identifier, compare with Equals, use GetHashCode for collections. |
LogAnnotations(IEnumerable<SensitivityLabel> labels) |
Copy one attachment's ordered label occurrences, including repeats; empty input is valid. |
MicrosoftLoggerDestination(...) |
Opt-in ordinary outbound route to a borrowed Microsoft logger or factory. |
GenericMicrosoftLoggerDestination<T>(...) |
Opt-in outbound route for exactly declared native metadata type T. |
LogAnnotations.LabelOccurrences |
Getter-only ReadOnlyCollection<SensitivityLabel>; captured occurrence count and order stay fixed. |
DestinationLabelPolicy(LabelFilterMode mode, IEnumerable<SensitivityLabel> labels) |
Required mode and configured membership; no default constructor. |
DestinationLabelPolicy.Mode / Labels |
Read the selected mode and copied, unique, read-only membership. |
DestinationLabelPolicy.Allows(IEnumerable<SensitivityLabel> effectiveLabels) |
Synchronous Boolean membership decision; no output operation. |
Logger.AddDestination / RemoveDestination / ClearDestinations |
Manage plain registrations; generic overloads manage registrations keyed by T. |
Logger.ConfigureAutomaticFileHostDirectory(string directory) |
Set only the automatic file's primary directory before initial establishment starts; no filesystem I/O or recipient registration. |
ILoggerMetadata / MetadataExtensions |
Optional empty marker and the six metadata extension helpers below. |
Native Scope And Delivery Members
These producer methods belong to Logger; generic T is unconstrained. The settings and
context types are in ProphetsWay.Utilities.
| Member | Current use |
|---|---|
BeginScope(LogAnnotations annotations) |
Return a LogScopeHandle; null opens an unlabeled frame with empty properties. |
BeginScope(LogAnnotations annotations, IEnumerable<KeyValuePair<string, object>> properties) |
Capture the complete property sequence before opening the frame. |
LogAnnotated(LogAnnotations annotations, LogLevels level, string message = null, Exception ex = null) |
Ordinary raw entry with optional explicit annotations and mask 1-63. |
LogAnnotated<T>(LogAnnotations annotations, LogLevels level, T metadata, string message = null, Exception ex = null) |
Exact-T raw entry; metadata remains separate from annotations. |
AddDestination(ILoggingDestination newDest, DestinationRegistrationSettings settings) |
Register an ordinary borrowed recipient with explicit settings. |
AddDestination<T>(ILoggingDestination<T> newDest, DestinationRegistrationSettings settings) |
Register only on the declared metadata route. |
SetDestinationSettings(ILoggingDestination destination, DestinationRegistrationSettings settings) |
Replace an existing ordinary registration's complete settings. |
SetDestinationSettings<T>(ILoggingDestination<T> destination, DestinationRegistrationSettings settings) |
Replace settings only on that exact-T route. |
LoggingDestinationCore.LabelPolicy |
Get/replace the supplied destination's additional immutable policy, including direct delivery. |
IContextLoggingDestination.LogWithContext(LogContext context, LogLevels level, string message = null, Exception ex = null) |
Optional ordinary full-context receiver. |
Generics.IContextLoggingDestination<T>.LogWithContext(LogContext context, LogLevels level, T metadata, string message = null, Exception ex = null) |
Optional exact-T full-context receiver. |
Logger.DispatchFailed / LogDispatchException.Report |
Observe bounded original-failure facts; see the distinct return/throw policies below. |
LogAnnotated uses raw rules: null message/exception and null annotations are valid, even at
ErrorOnly or Critical. It is not a convenience helper with their required arguments. Null/default
metadata is valid, and even T = LogAnnotations is only metadata, never an implicit label source.
Use an explicit generic invocation when inference would not select the route you intend.
All Eighteen Helper Forms
All helpers return void. Ordinary and typed methods belong to ProphetsWay.Utilities.Logger;
typed T is unconstrained. Extensions belong to ProphetsWay.Utilities.Generics.MetadataExtensions
and each has only where T : ILoggerMetadata. Parameter order and optional defaults are:
| Ordinary Logger method | Typed Logger method | Metadata extension declaration |
|---|---|---|
Trace(string message) |
Trace<T>(string message, T metadata) |
Trace<T>(this T metadata, string message) |
Debug(string message) |
Debug<T>(string message, T metadata) |
Debug<T>(this T metadata, string message) |
Info(string message) |
Info<T>(string message, T metadata) |
Info<T>(this T metadata, string message) |
Warn(string message, Exception ex = null) |
Warn<T>(string message, T metadata, Exception ex = null) |
Warn<T>(this T metadata, string message, Exception ex = null) |
Error(Exception ex, string message = null) |
Error<T>(Exception ex, T metadata, string message = null) |
Error<T>(this T metadata, Exception ex, string message = null) |
Critical(Exception ex, string message) |
Critical<T>(Exception ex, T metadata, string message) |
Critical<T>(this T metadata, Exception ex, string message) |
Trace/Debug/Info/Warn require a non-null message. Warn's exception may be omitted or null. Error requires a non-null exception; its context message may be omitted or null. Critical requires both exception and message. Empty and whitespace-only messages are valid and are not trimmed or replaced. Required-null checks run before routing, eligibility checks, rendering or fallback effects, even when every destination would reject the entry.
Metadata is a required argument, not a required non-null value: null and default(T) are
valid. Extension receivers may also be null or value-type marker implementations. Destinations
must handle the metadata values they accept; Logger does not clone or transform them.
Destinations
| Destination or extension point | Current use |
|---|---|
ConsoleDestination |
Text output; reporting level defaults to Debug, excluding Trace. |
FileDestination |
Required filename; defaults: Debug (excluding Trace), resetFile: false (append), EncodingOptions.UTF8; no added BOM. |
EventDestination |
Required reporting level; subscribe to LoggingEvent. |
GenericEventDestination<T> |
Typed callback; event arguments also expose Metadata. |
ILoggingDestination / ILoggingDestination<T> |
Log receives severity, optional message/exception, and metadata for the generic form; IDestination supplies ValidateMessageLevel. |
BaseLoggingDestination / BaseLoggingDestination<T> |
Pass a reporting level to the base constructor and override protected LogCore; public Log and LogWithContext are nonvirtual guards. |
LoggingDestinationCore |
Shared severity/exception handling and the protected value-formatting hook. |
TextBasedDestination / GenericTextBasedDestination<T> |
Ordinary/exact-T text bases; render captured context, then call your protected PrintLogEntry(string message) override once with no terminator. The typed base adds metadata. |
LoggingDestinationCore.FormatValue(object value) |
Protected virtual string hook for metadata/property values; return unescaped text or null, or delegate to the closed scalar default. |
LogContext.EventTimestampUtc |
Immutable call-time UTC readback; distinct from event arguments' legacy local Timestamp. |
For a reusable application-specific destination, including a database destination, implement
your own storage behavior behind the appropriate base. The new ordinary hook is
protected override void LogCore(LogContext context, LogLevels level, string message, Exception ex);
the generic hook is
protected override void LogCore(LogContext context, LogLevels level, T metadata, string message, Exception ex).
Neither hook declares optional arguments. This replaces the old public Log override and
is a source and binary break for subclasses: rebuild and move the output body to the matching
hook, using its supplied context. Existing direct callers retain the public Log signatures
and optional null message/exception defaults. Independent implementations of the old destination
interfaces need not adopt a context interface.
No database context, schema, or WriteLogRecord API is provided by this library.
The core and these bases/event destinations accept LogLevels reportingLevel,
string strReportingLevel, or int intReportingLevel constructors. Console/file constructors
forward the same mask rules. ValidateMessageLevel(LogLevels messageLevel) queries eligibility
without dispatching or changing the captured mask. There is no public raw Logger.Log method;
Logger.LogAnnotated is the raw producer API, while destination Log methods are direct entrypoints.
Common Scenarios
Keep Detailed And Warning Logs
Choose paths whose contents and access you control. This example writes files beneath
local application data and explicitly appends. With the explicit Trace mask, Debug.log
receives all six severities; Warnings.log receives Warning/Error/Critical.
Illustrative — not currently present in the repo.
using System;
using System.IO;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;
public static class Program
{
public static void Main()
{
var directory = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"ProphetsWay.Logger.Example");
var detailed = new FileDestination(Path.Combine(directory, "Debug.log"),
LogLevels.Trace, resetFile: false);
var warnings = new FileDestination(Path.Combine(directory, "Warnings.log"),
LogLevels.Warning, resetFile: false);
Logger.AddDestination(detailed);
Logger.AddDestination(warnings);
try
{
Logger.Trace("Trace detail.");
Logger.Debug("Detailed diagnostic.");
Logger.Warn("Check configuration.");
Logger.Critical(new InvalidOperationException("Example failure."), "Cannot continue.");
}
finally
{
Logger.RemoveDestination(detailed);
Logger.RemoveDestination(warnings);
}
}
}
For Debug/Information only, choose LogLevels.DebugOnly | LogLevels.InformationOnly.
All three existing FileDestination overloads now default to resetFile: false; the example
spells out that append choice. Explicit resetFile: true deletes only the selected existing
file during construction, not on each write. Use it only for an intentional reset. Construction
prepares missing parent directories but does not create a missing log file; eligible output
creates it. Constructor preparation is separate from per-entry severity and label selection.
The fourth parameter, encoder, accepts FileDestination.EncodingOptions.ASCII,
BigEndianUnicode, Unicode, UTF8 (the constructor default), or UTF32.
default(FileDestination.EncodingOptions) is ASCII, not the optional UTF8 default.
Each write appends the selected BCL encoding's bytes for the completed native record followed
by exactly one Environment.NewLine. It adds no leading newline, extra blank line or encoding
preamble/BOM. Encoding replacement follows the selected BCL encoding; ASCII does not promise
arbitrary Unicode round-tripping.
Appending leaves all existing bytes untouched, including any existing BOM. It does not inspect or transcode old content, detect binary or incompatible encoding, or insert a corrective separator after an unterminated prefix. You choose compatible existing content and encoding. See Explicit File Output for path and failure boundaries. The behavior is exercised in FileDestinationTests.cs, which remains deliberately separate from the default local check below.
Receive Messages In A Callback
Subscribe before registering the destination. Callbacks run synchronously on the logging
thread; marshal to your UI thread in your own handler when needed. Event arguments expose
Message, RawMessage, Exception, LogLevel, Timestamp, and Context.
Illustrative — not currently present in the repo.
using System;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;
public static class Program
{
public static void Main()
{
var destination = new EventDestination("Critical, InformationOnly");
destination.LoggingEvent += (sender, entry) =>
Console.WriteLine($"{entry.LogLevel}: {entry.RawMessage}");
Logger.AddDestination(destination);
try
{
Logger.Info("Ready.");
destination.Log(LogLevels.Critical | LogLevels.InformationOnly, "Composite.");
}
finally
{
Logger.RemoveDestination(destination);
}
}
}
The first callback prints InformationOnly: Ready. The direct call also passes: its full
mask 9 is present in the destination's mask 9. It would be rejected by InformationOnly = 8.
The callback receives that complete composite mask, not a single-bit reduction.
The registration/event pattern is also in
EventDestinationTests.cs.
Both event argument types expose non-null Context on actual library delivery, even with no
scopes or labels. Their existing public constructors leave Context null and perform no ambient
capture. Normal LoggingEvent multicast rules remain: a throwing handler stops that invocation
and counts as one output failure; other independent destinations are still attempted. This differs
from the individually contained subscribers of the safe Logger.DispatchFailed event.
Carry Metadata And Use Extension Calls
Typed logging accepts your application object; it does not require ILoggerMetadata.
Implement that empty marker only when you want the convenience extension calls as well.
This example replaces a hypothetical database writer with an actual typed event destination.
Illustrative — not currently present in the repo.
using System;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.Generics;
using ProphetsWay.Utilities.LoggerDestinations;
public sealed class DbMetadata : ILoggerMetadata
{
public int UserId { get; set; }
public string EntryPointMethod { get; set; }
public object Permissions { get; set; }
}
public static class Program
{
public static void Main()
{
var destination = new GenericEventDestination<DbMetadata>(LogLevels.Trace);
destination.LoggingEvent += (sender, entry) =>
Console.WriteLine($"{entry.Metadata.UserId}: {entry.RawMessage}");
Logger.AddDestination(destination);
var metadata = new DbMetadata
{
UserId = 42, EntryPointMethod = nameof(Main), Permissions = "Synthetic example"
};
try
{
Logger.Trace("Routing detail.", metadata);
Logger.Debug("Starting.", metadata);
metadata.Info("Finished.");
Logger.Error(new InvalidOperationException("Example failure."), metadata, "Stopped.");
metadata.Critical(new InvalidOperationException("Critical failure."), "Cannot continue.");
}
finally
{
Logger.RemoveDestination(destination);
}
}
}
Expected output is 42: Routing detail., 42: Starting., 42: Finished., 42: Stopped.,
then 42: Cannot continue. Metadata remains available as an object; this callback chooses
what to print. See the real call patterns in
GenericLoggerTests.cs and
MetadataLoggerTests.cs.
Ordinary explicit registrations and every exact declared-T route are independent, including
interface types such as T = ILoggingDestination. Typed routing does not search base types,
implemented interfaces, or the metadata object's runtime subtype. If that exact type has no
enabled registered destination, its automatic recipient uses the native typed renderer and the
same session file as ordinary automatic output. It retains metadata, including null/default values,
with the original annotation, native scopes and UTC event time. Rendering still follows the
closed scalar rules, not arbitrary object serialization.
Typed calls never forward to ordinary registrations. Any enabled compatible explicit recipient
suppresses only its own route's automatic output, even when it rejects or fails; another route
can still use the shared file.
Implement A Guarded Custom Destination
Move an old public Log override into protected LogCore. Keep formatting/output inside that
hook so the supplied guards run first, and use its context instead of recapturing ambient state.
This callback sink needs no files or external service; its added constructor belongs to the
example, not the library. The base requires a reporting level and has no parameterless constructor.
Illustrative — not currently present in the repo.
using System;
using ProphetsWay.Utilities;
public sealed class CallbackDestination : BaseLoggingDestination
{
private readonly Action<LogContext, LogLevels, string, Exception> _write;
public CallbackDestination(LogLevels reportingLevel,
Action<LogContext, LogLevels, string, Exception> write)
: base(reportingLevel)
{
if (write == null)
throw new ArgumentNullException(nameof(write));
_write = write;
}
protected override void LogCore(LogContext context, LogLevels level,
string message, Exception ex)
{
_write(context, level, message, ex);
}
}
public static class CustomDestinationExample
{
public static void Run()
{
var personal = new SensitivityLabel("PersonalData");
var destination = new CallbackDestination(LogLevels.Trace,
(context, level, message, exception) =>
Console.WriteLine("{0}: {1} ({2} labels)",
level, message, context.Labels.EffectiveLabels.Count));
destination.LabelPolicy = new DestinationLabelPolicy(
LabelFilterMode.Exclude, new[] { personal });
Logger.AddDestination(destination);
try
{
using (Logger.BeginScope(new LogAnnotations(new[] { personal })))
{
Logger.Info("Withheld before the callback.");
destination.Log(LogLevels.InformationOnly, "Direct call also withheld.");
}
Logger.Info("Synthetic public message.");
}
finally
{
Logger.RemoveDestination(destination);
}
}
}
The generic base uses the same pattern, adding T metadata between level and message
in LogCore. Neither hook has optional parameters; the inherited public Log methods still
default message and ex to null. MassageLogStatement and PrintLogEntry overrides retain
their existing signatures. Hook or callback exceptions are output failures handled by the
invoking guarded boundary, not a request to retry or activate another output.
Capture A Text Record In Memory
Override PrintLogEntry to receive a fully rendered ordinary record without a terminator.
This sink stores one string; it neither opens a file nor writes to the console. Explicit
registration avoids fallback, but any other registered recipients can still receive the call.
Use these in-memory examples with one synchronous producer and no unrelated recipients;
they are not concurrent storage implementations.
Illustrative — not currently present in the repo.
using System.Collections.Generic;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;
public sealed class RecordingTextDestination : TextBasedDestination
{
public RecordingTextDestination() : base(LogLevels.Trace)
{
}
public string Record { get; private set; }
protected override void PrintLogEntry(string message)
{
Record = message;
}
}
public static class TextRecordExample
{
public static string Run()
{
var destination = new RecordingTextDestination();
Logger.AddDestination(destination);
try
{
var label = new SensitivityLabel("Internal");
var properties = new[]
{
new KeyValuePair<string, object>("Step", "Receive"),
new KeyValuePair<string, object>("Step", "Validate"),
new KeyValuePair<string, object>(null, null)
};
using (Logger.BeginScope(new LogAnnotations(new[] { label, label }), properties))
{
Logger.LogAnnotated(new LogAnnotations(new SensitivityLabel[0]),
LogLevels.InformationOnly, message: "First line.\nSecond line.");
}
return destination.Record;
}
finally
{
Logger.RemoveDestination(destination);
}
}
}
On delivery, the returned string has one escaped message token, entryLabels=[], and one
scope with labels=["Internal","Internal"] and
properties=[("Step","Receive"),("Step","Validate"),(null,null)]. No duplicate is flattened.
A null returned record means no print occurred; normal return alone is not proof of delivery.
The public example types above are application code, not additional library APIs.
Extend Typed Value Formatting
Derive from GenericTextBasedDestination<T> to retain exact-T routing and render metadata.
This example explicitly reads two known application properties and delegates other values to
the default formatter. Return ordinary text: the base quotes and escapes it afterward, including
the newline and quotes in Stage. The same hook formats scope values.
Illustrative — not currently present in the repo.
using System.Collections.Generic;
using System.Globalization;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;
public sealed class OrderMetadata
{
public int OrderId { get; set; }
public string Stage { get; set; }
}
public sealed class OrderTextDestination : GenericTextBasedDestination<OrderMetadata>
{
public OrderTextDestination() : base(LogLevels.Trace)
{
}
public string Record { get; private set; }
protected override string FormatValue(object value)
{
var order = value as OrderMetadata;
if (order != null)
return string.Format(CultureInfo.InvariantCulture,
"Order {0}: {1}", order.OrderId, order.Stage);
return base.FormatValue(value);
}
protected override void PrintLogEntry(string message)
{
Record = message;
}
}
public static class FormatterExample
{
public static string Run()
{
var destination = new OrderTextDestination();
Logger.AddDestination<OrderMetadata>(destination);
try
{
var metadata = new OrderMetadata { OrderId = 42, Stage = "Queued\n\"Review\"" };
var properties = new[]
{
new KeyValuePair<string, object>("Attempt", 2),
new KeyValuePair<string, object>("Unformatted", new object())
};
using (Logger.BeginScope(null, properties))
{
Logger.LogAnnotated<OrderMetadata>(null, LogLevels.InformationOnly,
metadata, message: "Synthetic order.");
}
return destination.Record;
}
finally
{
Logger.RemoveDestination<OrderMetadata>(destination);
}
}
}
The metadata token is "Order 42: Queued\n\"Review\""; the scope values are "2" and
"[no formatter: Object]". Without the override, this metadata would be
"[no formatter: OrderMetadata]", not an automatic property dump. These are expected tokens,
not captured program output. The sink has the same single-producer/registration assumptions
as the previous example. No ILoggerMetadata marker or formatter registration is needed.
See TextRenderingTests.cs for the real
in-memory text, explicit formatter, rejection and escaping specifications.
Behavior And Limitations
Native Argument Errors
These errors apply to the core and its forwarding constructors, helpers, registrations,
and supplied direct Log implementations, as indicated. Valid rejection is not an error.
| Invalid input | Exception | ParamName |
|---|---|---|
| Enum destination mask outside 0-63 | ArgumentOutOfRangeException |
reportingLevel |
| Integer destination mask outside 0-63 | ArgumentOutOfRangeException |
intReportingLevel |
| Null string destination mask | ArgumentNullException |
strReportingLevel |
| Any other invalid string mask, including parsed negative/unknown bits or overflow | ArgumentException |
strReportingLevel |
Raw mask outside 1-63 passed to ValidateMessageLevel |
ArgumentOutOfRangeException |
messageLevel |
Raw mask outside 1-63 passed to a supplied destination's Log |
ArgumentOutOfRangeException |
level |
| Null required helper message or exception | ArgumentNullException |
message or ex |
Null ordinary or typed AddDestination argument |
ArgumentNullException |
newDest |
Same object reference added again on the same ordinary or exact-T route |
ArgumentException |
newDest |
| Null registration settings on add or replacement | ArgumentNullException |
settings |
| Null/absent destination on settings replacement | ArgumentNullException / ArgumentException respectively |
destination |
| Null policy in settings construction / supplied policy assignment | ArgumentNullException |
labelPolicy / value respectively |
Null property sequence for BeginScope |
ArgumentNullException |
properties |
Invalid raw mask for LogAnnotated |
ArgumentOutOfRangeException |
level |
Null/noncurrent context on a supplied LogWithContext call |
ArgumentNullException / ArgumentException respectively |
context |
No competing-error priority is promised when both Critical arguments are null. Exception message text is not a configuration contract. Equivalent valid mask representations have the same eligibility, but invalid strings deliberately use different errors from invalid enums/integers.
Dispatch And Direct Calls
For enabled ordinary and exact-T registrations, every registration and supplied-destination
restriction must permit the full captured entry before handoff. Logger invokes a custom
ValidateMessageLevel callback at most once per attempted recipient and requires true; an
earlier rejection may skip it. No ordering among rejecting checks is promised. Label denial
withholds message, exception, metadata and the complete context, including scope properties,
before recipient-owned formatting, hooks, callbacks or export. Permitted recipients continue.
A recipient implementing the optional IContextLoggingDestination or exact-T counterpart
receives one LogWithContext handoff instead of the legacy Log, never both. Independent
implementations of the old interfaces remain valid and receive no new context parameter.
Supplied bases deliver once through Logger's internal captured path to LogCore, without
recapturing callback-mutated scopes or repeating policy checks/reporting. That path is internal,
not a consumer API or reusable permission token; public reentry always starts a new guarded attempt.
The supplied bases' public Log and LogWithContext are nonvirtual guards, inherited by
event/text/console/file destinations. Direct Log captures active frames with no entry annotation
and checks the destination's own mask and LabelPolicy, not registration settings. A valid
mismatch returns without massage, hook, event construction, text composition, output or fallback.
Invalid masks throw before recipient work, even without event subscribers.
Direct LogWithContext requires the same ordered scope openings currently active, including empty
and unlabeled frames. Equal labels/properties from a different opening are insufficient. Both
empty frame lists match; the supplied entry annotation may be non-null. Reuse while those openings
remain current still rechecks current destination configuration. Added, ended or replaced frames
make the context noncurrent and cause a local argument error before output. Possession or earlier
successful delivery is not authorization. Arbitrary independent direct implementations, hidden or
reimplemented members, and consumer methods calling their own hooks are not sandboxed.
An accepted supplied-base LogWithContext invocation delivers a newly stamped context with
that direct call's UTC time and the supplied immutable scope/label facts, including entry
annotations. It does not mutate the retained context or replace its facts with current labels.
Timestamp equality is not part of the current-opening check and grants no delivery permission.
Direct/raw content is distinct from helper preconditions: message and exception may each be
absent, even at Critical or ErrorOnly. Typed metadata may still be null/default. For accepted
callbacks, RawMessage, Exception, the complete LogLevel mask, and typed Metadata retain
their supplied values/references. Message contains the massaged text, not a replacement raw
payload; Error's omitted context remains null in RawMessage.
Without an exception, the base MassageLogStatement returns the original message, including
null, empty or whitespace. With an exception, it preserves context and includes exception and
nested-exception messages and available stack traces at every valid mask, including warnings
and composites. It does not serialize exception Data, redact content, or clone raw objects.
Timestamp remains each event carrier's construction-time local DateTime.Now, not a shared UTC
timestamp. Use the delivered Context.EventTimestampUtc for shared call time instead. Event
Message and RawMessage are not text-record tokens: message/exception text stays unescaped,
and metadata and scope values retain original references. Accepted raw objects are not sanitized
reporting objects; framing a neighboring text destination does not make a callback safe to export.
Label And Policy Arguments
| Invalid input | Exception | ParamName |
|---|---|---|
| Null identifier | ArgumentNullException |
identifier |
| Empty, overlong, whitespace-containing or control-containing identifier | ArgumentException |
identifier |
| Mode other than 0, 1, or 2, including combined value 3 | ArgumentOutOfRangeException |
mode |
| Null configured/effective sequence | ArgumentNullException |
labels / effectiveLabels respectively |
| Null element anywhere in a finite sequence | ArgumentException |
labels / effectiveLabels respectively |
NoFilter and a decisive match do not bypass finite-input validation. Sequence-access failure
completes exceptionally, without a usable partial policy or Boolean result. Exact foreign
exception details and competing-error precedence are unspecified. Supplied sequence code can
have side effects; the policy does not sandbox it, undo those effects, or bound nonterminating inputs.
Keep inputs stable during capture. Repeated/concurrent evaluation of unchanged valid membership
preserves policy state and results, but concurrent producer mutation is unsupported. Readback order,
collection-reference identity, and representative label-reference identity are unspecified.
Mutation through readback collection interfaces throws NotSupportedException.
Annotation Capture And Readback
Supply a finite, stable, non-null sequence of non-null labels to LogAnnotations.
Null labels throws ArgumentNullException; a null element anywhere throws ArgumentException.
Both name labels in ParamName; exception wording is not promised.
Sequence access includes enumerator acquisition, iteration, element access and disposal. If any fails, construction produces no usable partial value. Foreign sequence errors are local construction errors, not sanitized dispatch reports; their details, competing-error precedence and access counts are unspecified. Caller code may have side effects: capture does not sandbox or roll them back, support mutation during capture, or guarantee termination for unbounded input.
After successful construction, LabelOccurrences is non-null and supports concurrent reads.
Writes through its collection interfaces throw NotSupportedException; its ICollection.SyncRoot
does not expose occurrence storage. View and representative label-reference identity are unspecified.
These readback guarantees describe LogAnnotations specifically.
Scope-property capture follows the same complete-before-publication discipline, including
enumerator disposal. A null sequence or failed acquisition/iteration/current/disposal publishes
no scope or usable handle and emits no dispatch report. Opening cannot undo side effects in
caller sequence code, bound an infinite input or support concurrent producer mutation. Scope
cleanup errors are local errors too, not LogDispatchException or DispatchFailed notifications.
Failure Reports And Return Policy
On explicit or automatic routes and supplied guarded direct calls, failure handling depends on the observed boundary, not foreign exception text or type. Valid severity/label rejection is not a failure and does not activate fallback. Independent recipients are attempted once in captured order, without rollback or retries; another recipient succeeding does not cancel a mandatory failure.
| Original failure | Safe fact | Result after independent attempts and reporting |
|---|---|---|
| Logger-invoked severity callback throws | LogFailureStage.Eligibility = 1 |
Throw LogDispatchException. |
| Selected legacy/contextual invocation, delivery hook, rendering or callback throws | LogFailureStage.Output = 2 |
Throw LogDispatchException. |
| Automatic initial establishment fails at both locations, remembered initial failure, or automatic output fails | One LogFailureStage.Output descriptor at the implicit slot after all captured explicit slots; no core-capture failure |
Throw LogDispatchException; qualifying initial secondary success is normal success. |
| Opted-in label-policy evaluation unexpectedly fails | LogFailureStage.LabelCheck = 3 |
Withhold that recipient, report and return unless a mandatory failure also occurred. |
| Shared entry/context capture unexpectedly fails | CoreCaptureFailureCount = 1, no recipient descriptor |
Withhold the incomplete entry from all affected recipients, report and return. |
No strict-mode selector is supplied by these APIs. A normal return proves neither delivery nor successful capture/checks. Value/scope construction and argument errors remain local exceptions, not fabricated dispatch failures. A mandatory failure still throws if its descriptor falls beyond the retained limit; result selection is not inferred from the truncated descriptor list.
If neither initial automatic location is usable, Logger remembers a safe failure marker, not
the raw causes. Later default-dependent calls get fresh reports/correlations and exceptions without
new path or permission probes. LogDispatchException.Message, ToString() and best-effort stderr
give fixed guidance to make an appropriate default location writable or configure a compatible
destination, never the resolved path or payload. Fixing permissions alone does not retry this session:
use a compatible enabled explicit recipient to bypass failure only on its route, or start a fresh
loaded Logger session. Removing/disabling/clearing that recipient exposes the same remembered failure.
LogFailureReport contains a generated CorrelationId, at most eight immutable Failures in
encounter order, OverflowCount for further failed recipients, and CoreCaptureFailureCount
(zero or one). A core-only report has an empty recipient list and zero overflow. Total failures
are (long)report.CoreCaptureFailureCount + report.Failures.Count + report.OverflowCount.
Each descriptor's RegistrationId is a one-based position in this call's full capture,
including preceding disabled, rejected and successful slots. A supplied direct attempt uses 1;
zero is never a fabricated core recipient. These are not durable registration IDs.
Reports retain no entry, labels, origins, properties, destinations, delegates, raw causes or
control backlinks. Their owned membership remains unchanged across observers and later calls.
LogDispatchException.Report carries the same safe facts, with no raw inner cause. Its initial
diagnostic view uses fixed prose, allowed IDs/codes/counts, null InnerException/HelpLink, empty
Data, fixed Source, and null StackTrace. This does not erase CLR diagnostic state or sanitize
reflection, debugger access, serialization, inherited post-catch mutation or a whole object graph.
Logger.DispatchFailed captures subscribers after attempts, invokes each synchronously outside
registry locks, then attempts a safe stderr summary bounded to 512 UTF-16 units including its
terminator. Subscriber/writer failures are contained and add no original failures or escalation.
On the same managed-thread reporting stack, nested logging still runs with its own result policy
but emits no nested event/stderr report; other threads are independent. No timeout, cross-thread
cycle prevention, guaranteed observation or process-fatal containment is promised.
Native capture and policy checks use library-owned membership and sealed label/policy values, with no ordinary deterministic consumer fault path for the unexpected capture/LabelCheck branches. Those branches require code review, not a fabricated report presented as execution coverage. Allocation/runtime faults may prevent reporting itself: out-of-memory survival is not guaranteed. Consumer callbacks and raw payloads are not made safe by these bounded reporting facts.
Text rendering follows the same boundary: a throwing massage, FormatValue override or
composition step causes no PrintLogEntry call for that recipient. Independent recipients
continue, then an Output failure requires safe reporting and LogDispatchException. A print
failure may already have effects; there is no rollback or retry. Valid rejection reaches neither
formatter nor print, and a null formatter result is valid text absence, not a failure.
Neither rendered content, event time, original values nor the formatter's raw exception is
added to LogFailureReport. Intended log records are unbounded, potentially sensitive content;
they are not the bounded diagnostic channel. Custom inspection and retention remain your responsibility.
Current Logging And Text Output
- With no enabled compatible explicit recipient on the captured ordinary or exact-
Troute, Logger selects one implicit automatic recipient without registering it or consulting another route. It usesTraceand no label filter, covering all six bits and valid composite levels. Ordinary and typed automatic records share one UTF-8 session file; typed metadata is retained. See Automatic File Output for location, configuration and failure rules. - Explicit registration uses reference identity, never recipient equality or hashing. Distinct equal objects remain distinct; the same instance may register on different compatible routes. Duplicate same-route adds leave membership unchanged. Removal targets only the exact reference; null/absent removal is a no-op, and clear affects only the selected route. After removal/clear, a successful re-add goes last.
- For a route with explicit recipients, mutations and captures are atomic: each call captures one complete insertion-ordered membership and its registration settings before callbacks. Native context and supplied policies are also captured before recipient callbacks, without promising a global transaction across registry and flow state. Registry locks span no consumer code. Callback add/remove/clear/settings changes, including self-removal, affect later captures only; an older capture can still call a removed recipient after mutation returns. Recursive logging is a new call with a fresh capture.
- Explicit destinations are borrowed: removal/clear never dispose them and do not drain calls. Stop producers and await synchronous calls before disposing your recipients. Membership capture does not serialize callers or shared recipients, impose cross-thread delivery order, or freeze custom recipient state, eligibility results, metadata or exception graphs.
- The failure rules above cover explicit and automatic dispatch and supplied guarded direct attempts, not arbitrary independent direct code or a guarantee that all I/O completes. Borrowed lifetime and retained-object responsibilities remain.
Automatic File Output
Ordinary and every exact-T automatic route share one session in the loaded static Logger state.
Separate processes, AppDomains or independently loaded assembly copies do not share that state.
An enabled compatible explicit recipient suppresses only its own route, including rejection or
failure. Removing or disabling the last one resumes the same automatic session, not a new file.
The normal primary directory is the host's AppContext.BaseDirectory, not the current working
directory, Logger's assembly location or the dotnet installation. To choose a different primary,
configure it during startup before any automatic establishment begins:
Illustrative — not currently present in the repo.
ProphetsWay.Utilities.Logger.ConfigureAutomaticFileHostDirectory("logs");
Then, with no enabled ordinary recipient, ProphetsWay.Utilities.Logger.Trace("Startup");
uses automatic output. The relative logs directory is resolved once against the current directory
at configuration time using DirectoryInfo.FullName. Configuration creates no directory/file,
checks no permissions and registers no recipient. Later successful configuration calls replace the
override only before initialization; once establishment starts, even the same path is rejected with
InvalidOperationException. Null throws ArgumentNullException; empty or framework-rejected path
syntax throws ArgumentException. Other path-normalization errors remain ordinary local errors,
not sanitized dispatch diagnostics. Failed calls change nothing; invalid-input/state precedence is
unspecified. Null/empty are not reset requests.
Only initial primary establishment failure permits a secondary attempt: one app- directory
component followed by the full 64 lowercase SHA-256 hex digits of the normalized host-base key,
directly under Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData).
The key comes from the captured host base, not the primary override. Unavailable naming/root
inputs fail that location; Logger does not substitute CWD or another profile. This is host-base
association, not logical-application identity: equal keys share the directory, and physical aliases
need not share a key. It supplies no tenant isolation, ACL protection or confidentiality.
Filesystem establishment waits for a selected, fully rendered record. Initial allocation uses
Default Log <UTC>-<Guid token>.log, invariant UTC and exclusive CreateNew, leaving occupied
candidates untouched. Once selected, every later call appends or creates a missing file at that
same pathname, regardless of later CWD changes or route suppression/reactivation. Each record
is UTF-8 with one Environment.NewLine suffix, no added BOM and no leading blank line. Existing
content is neither inspected nor repaired. See the exact path rules in
AutomaticFilePaths.cs and session behavior in
AutomaticFileSession.cs.
File effects are serialized across automatic routes and handles close after each attempt; rendering, callbacks, registration changes and reporting remain outside that coordination. Once a path is selected, write/flush/close failures or later open failures cannot select the secondary, replay the entry or allocate another session filename. A later call is a new attempt at the selected path. There is no crash-durability or cross-process ordering guarantee, public session reset, disposal, strict-mode selector or selected-path inspection API. Intended records are not redacted; choose explicit destinations and filesystem access/retention controls for your deployment.
Explicit File Output
FileDestination.cs selects its full
pathname once at construction using the framework's FileInfo semantics. Relative paths use
that moment's Environment.CurrentDirectory; later directory changes do not redirect the instance.
If the file is deleted, a later permitted call can recreate it at that same path. Missing parent
directories are prepared at construction, not repaired on every output attempt. This fixes a
pathname, not a persistent physical-file identity or filesystem sandbox.
Required arguments are validated before deletion or directory creation. An undefined encoder
throws ArgumentOutOfRangeException naming encoder before those effects. Ordinary construction,
preparation and reset failures outside the documented argument mappings propagate as their original
framework exceptions. Their diagnostic contents are not promised sanitized or path-free; construction
produces neither a console echo nor a Logger.DispatchFailed notification.
After construction, encoding/open/write/flush/close failures through supplied public direct
entrypoints or Logger delivery are LogFailureStage.Output failures. A direct call safely reports
its one-recipient failure and throws LogDispatchException. Logger attempts independent eligible
recipients before safe reporting and the mandatory throw; reporter failures cannot suppress or
replace that result. The sink emits no second report. Validly rejected entries never reach rendering
or file output, but rejection does not undo earlier constructor preparation or explicit reset.
Physical writes are synchronous and serialized within one destination instance; each attempt releases its acquired file handle before completion. Rendering can still run concurrently. There is no cross-instance/process coordination, promised concurrent-call order, retry, replay, relocation, global flush or crash-safe/exactly-once/durability guarantee. A failure may follow partial effects; a later logging call is a new attempt at the same path, not a replay of the failed entry.
Record Layout
The supplied text bases render the captured UTC event time in invariant round-trip O format
(including +00:00), followed by the full severity's general spelling padded left to 12 characters.
The message is massaged once, then quoted and escaped. For Logger.Debug("Hello World!") without
scopes or entry annotations, the shape is below. The timestamp placeholder is not literal output
or a recorded execution:
<UTC event time> :: DebugOnly: "Hello World!" | entryLabels=null | scopes=[]
GenericTextBasedDestination<T> adds the literal prefix " | metadata=" (excluding the quotes)
immediately after the message token, before entryLabels, even for null/default metadata.
Ordinary text has no metadata field.
There is no configurable grammar or automatic discovery of arbitrary structured objects.
| Component | Representation |
|---|---|
Absent text / empty text / literal null text |
null / "" / "null"; non-null values are always quoted. |
| Entry or scope annotation | null when absent; [] when present but empty; otherwise ordered quoted label identifiers, including duplicates. |
| Scopes | [{labels=attachment,properties=[(key,value),...]},...], outermost first, including empty/unlabeled frames. |
| Properties | Ordered pairs, not a dictionary: duplicate keys, null/empty/whitespace keys and original value slots remain separate. Keys are string tokens; values use FormatValue. |
Arrays and pairs use commas without added spaces or trailing commas. Entry labels are separate
from scope labels. Text preserves label occurrences rather than exporting the deduplicated
EffectiveLabels set; frame positions in scopes are not the label-only ScopeIndex values.
Every content token is escaped once after formatting, including message and exception detail, metadata, scope keys/values, label identifiers, unsupported markers and explicit formatter output:
| Input | Emitted text |
|---|---|
| Backslash / double quote | \\ / \" |
| CR / LF / TAB | \r / \n / \t |
Other Char.IsControl units and U+2028/U+2029 |
\uXXXX, with four uppercase hexadecimal digits. |
| Other UTF-16 units | Preserved without normalization or truncation. |
An actual newline becomes \n; an existing backslash followed by n becomes \\n.
Delimiter-looking text stays inside its quoted token. This is reversible text escaping, not
redaction, confidentiality, lossless object serialization or proof of downstream encoding fidelity.
Each text base builds the whole record before one PrintLogEntry call. That string is non-null,
single-line and has no terminator; the sink owns termination. Console retains its WriteLine
handoff. FileDestination appends one Environment.NewLine suffix using the selected encoding,
as described above. Automatic output uses the same suffix with UTF-8; its separate lifecycle and
initial-only recovery rules are described under Automatic File Output.
Scalars And Explicit Formatting
The default LoggingDestinationCore.FormatValue(object value) supports only these values:
| Value | Unescaped scalar text |
|---|---|
| Null, string, char, Boolean | Null result, original string/character, or True/False. |
| SByte/Byte, Int16/UInt16, Int32/UInt32, Int64/UInt64, IntPtr/UIntPtr | Invariant D; pointer-sized integers render their numeric value, without dereferencing. |
| Single/Double; Decimal | Invariant R; invariant G, respectively. Floating special values remain supported. |
| Guid; DateTime/DateTimeOffset; TimeSpan | Invariant D; O; c, respectively. Payload times retain their kind/offset; only the event time is forced to UTC. |
| Enum | General G names/representable flag names, otherwise invariant underlying decimal; alias choice follows the BCL. |
| Anything else | [no formatter: TypeName], using runtime Type.Name, not a full name or object string. |
Nullable boxing follows the underlying value, or null when empty. Runtime-specific BCL floating
spellings are not promised byte-identical across target frameworks. Dictionaries, enumerables and
annotation-shaped metadata remain values, not automatically traversed structures or label sources.
Default rendering calls no arbitrary getters, object ToString, IFormattable, equality, hashing
or nested enumeration. It does not deep-clone values.
Override FormatValue on your text destination to opt into application-owned inspection. Return
unescaped text, delegate unhandled values to base.FormatValue(value), or return null for a
null text token. The renderer escapes every result as data; returning null is not a failure.
Successful text rendering calls the hook once per metadata/property-value occurrence after
eligibility. Duplicate slots are separate calls; call order across values is unspecified, and
results are not cached across recipients. Keys, labels and message/exception text bypass this hook.
Overrides may run concurrently and own their inspection, effects and retained objects.
The rules are implemented by the ordinary text base, typed text base and formatting hook, and specified in TextRenderingTests.cs.
Earlier Text Layout
The old local-time, unquoted output looked like this; it is retained only as a migration reference, not current output:
3/15/2019 11:09:33 PM :: DebugOnly: Hello World!
The existing example program constructs nested exceptions. This historical illustrative error excerpt shows their messages in the earlier multiline layout. Current text keeps the exception detail inside one escaped message token at every valid mask; events retain unescaped massaged text. A constructed-but-unthrown exception does not acquire a stack trace merely because its message mentions one:
3/15/2019 11:25:41 PM :: ErrorOnly: Another generic message about an error occuring. (friendly message to show a UI maybe?)
This exception has an inner exception. (likely details to hide from a UI)
Inner Exception Message:
This is a specific Exception Message and will contain a stack trace.
Implemented M3/M4-A And Remaining Boundaries
Native scopes, ordered origins/full properties, effective-label filtering, atomic registration
settings replacement, optional contextual receivers and guarded supplied destinations are implemented.
M4-A adds call-shared UTC time, invariant scalar/explicit value formatting, ordinary and exact-T
text bases, and quoted single-line rendering of the message and captured native context.
They extend the existing severity validation, explicit-route isolation, borrowed-recipient lifetime
and independent-attempt reporting rules. This source status is not full-v4 or release certification;
the permanent regression, compiled-example and parent final acceptance gates remain separate.
M4-B1 now implements append-by-default explicit files, construction-only reset, fixed selected paths
and physical record encoding/termination. M4-B2 now integrates the shared automatic session,
primary configuration, typed metadata retention, initial-only recovery, fixed-path reuse and
remembered initialization failure. Its final documentation-compilation and independent code/security
gates remain separate; this is not a claim that the whole B2 acceptance target is complete.
The inbound and outbound Microsoft bridge directions are implemented in current source and
documented above; neither is part of this native M3/M4 slice. Explicit membership safety is not a
guarantee of all concurrency safety. The native enum itself does not define Microsoft severity or
None conversion; that mapping belongs to the bridge. The implemented failure behavior above is
not delivery of every policy in
docs/requirements.md. Requirements readiness is not delivery.
A false policy result is an ordinary mismatch, not an output failure or instruction to activate fallback. True means only membership permission, not successful delivery, correct classification, or authorization of a recipient. The library does not automatically classify or redact payloads. You own label mapping, sanitization, recipient access/authentication, storage, retention, and audit obligations. Readable identifiers/configuration and consumer sequence exceptions can contain sensitive information; do not treat them as safe to expose just because the predicate returned.
See the scoped security review, threat model, and data classification. Their scope is not a confidentiality, compliance, sandboxing, whole-library security, or publication guarantee. Any advisory-scan results in that review are dated evidence, not license, bundled-component, SDK/runtime, or release clearance.
Breaking Migration From Earlier Logger APIs
Recompile consumers, custom destinations, and code that compares or persists enum values. Enum constants can be embedded in compiled callers; replacing a library binary does not translate their old numeric meanings. This is unreleased major-version work, not a patch-safe drop-in update.
- Remove calls to ordinary, typed, and metadata-extension
Security, plusSecurity/SecurityOnlyconfiguration names. Choose the appropriate remaining severity for each call. There is no automatic security-event/concern replacement. Explicit application labels and policies are independent of severity, not an automatic translation of the removed Security level. - Recalculate saved integer/numeric-string masks from the intended new bits: 1 is Critical, 2 is ErrorOnly, 4 is WarningOnly, 8 is InformationOnly, 16 is DebugOnly, and 32 is TraceOnly. Do not reuse old numeric configuration without reviewing its meaning. Recheck enum-name configuration too: inclusive Error accepts Error/Critical; Debug no longer means all severities. Select Trace for all six.
- Compare emitted Error entries to
ErrorOnly, not the inclusiveErrormask. For selection, require all requested bits; preserve composite masks rather than reducing them to one severity. - Supply the formerly optional required extension arguments: messages for Debug/Info/Warn and an exception for Error. All three helper families now reject required nulls before dispatch, even if the route rejects everything. Critical requires exception and context; Error's context and Warn's exception remain optional. Empty/whitespace messages and null/default metadata remain valid.
- Correct malformed mask strings instead of relying on the former Information fallback. Zero is valid only as a destination mask; direct/raw zero is an error. Supplied direct destinations now reject ineligible messages before formatting/callback/output, so a direct call no longer bypasses selection.
- Deduplicate setup by object reference per route: a repeated add now throws
ArgumentExceptionwithParamNamenewDest, rather than adding another delivery. Retain the exact reference for removal; an equal but distinct object no longer removes it. Do not treat removal/clear as a drain or immediate revocation: already captured calls may still use that borrowed recipient. - Rebuild subclasses and move public
Logoverrides to the matching protectedLogCoresignature shown above. The old virtual/abstract slot is gone: this is a binary as well as source break. Do not hideLogto bypass guards. Existing callers keep the public method defaults, and independent old-interface implementations need not adopt the optional context interface. - Update report readers for
LabelCheck, empty recipient lists on core-only failure, and core-inclusive totals. Notifications do not all imply an exception; severity/output failures do. Event consumers may readContexton delivery but must allow null on manually constructed args. - Migrate text parsers from local culture-dependent, unquoted multiline output to the fixed UTC
Oprefix and quoted token grammar above. Parse boundaries before decoding escapes once; do not split blindly on delimiters that can occur inside quoted content. Preserve null versus empty/literal-null tokens, repeated labels/keys and full scope frames. Exception stacks now appear escaped within the message token, not as additional physical lines. - Keep
MassageLogStatementunframed and unescaped if you need the supplied text contract: text bases frame its result, while events retain it unescaped. UseFormatValuefor explicit metadata/property rendering andPrintLogEntryfor the completed unterminated record. Review existing subclasses for a coincidentally namedFormatValuemember; replacingLogCorecan replace the supplied rendering behavior. These hooks do not certify custom output code. - Do not reinterpret event
Timestampas UTC. ReadContext.EventTimestampUtcon delivery; a public direct reuse samples anew without altering the retained context. Update text readers independently from raw/event consumers, whose original fields and local timestamp remain. - Recompile callers to obtain
FileDestination's new omittedresetFile: falsedefault on all three existing overloads. Previously compiled callers may still pass embeddedtrueuntil rebuilt; replacing the library alone does not change those arguments. Explicittruestill deletes the selected existing file during construction. No new reset method or factory is added. - Update file readers for one suffix terminator per appended record and no newly added BOM; existing bytes and unterminated prefixes are not repaired. Reject undefined encodings during setup, and handle ordinary constructor errors locally without expecting console echo or safe dispatch diagnostics. Guarded output failures still report safely and must throw. These are unreleased v4 behavioral changes, not a patch-safe update.
- Review no-setup file assumptions: automatic output now uses the host base or a pre-initialization override, initial-only secondary recovery and one shared UTF-8 file with Trace coverage and typed metadata. It no longer forwards typed fallback to ordinary recipients. Clearing registrations cannot reset the selected path or remembered initial failure.
Architecture And Design Decisions
| Choice | Trade-off |
|---|---|
| Static entry point with configurable destinations | Central setup and short calls, but process-wide state and current registration limitations. |
| Typed metadata separate from message text | Your destination can inspect application data; Logger does not supply a database schema or automatically persist that object. |
| Sealed, application-defined label instead of a closed taxonomy | No registry dependency and no invalid default value-type instance; consumers must agree on exact identities. |
| Immutable copied policy membership | Later caller edits cannot change configuration; changing policy means constructing another policy. |
| Standalone predicate plus native enforcement | Membership remains independently usable; Logger and supplied guards enforce whole-entry selection using the captured union. |
| Immutable membership, original nested objects | Stable scope/settings structure without arbitrary deep cloning, classification or sanitization; consumers own nested-object safety and retention. |
| Conventional non-transferable scope handles | Normal await/child inheritance and local cleanup without a creator-ID/fork protocol or universal misuse detector. |
| Nonvirtual entrypoints and protected output hooks | Selection precedes supplied output even on direct calls, at the cost of a major subclass override migration. |
| Closed scalar formatting plus explicit overrides | Predictable invariant text without arbitrary object inspection; your formatter owns any additional reads and effects. |
| Shared UTC and quoted native records | One call-time fact and preserved content boundaries, at the cost of a breaking text-parser migration; physical storage remains a separate responsibility. |
The accepted direction is recorded in docs/decision-log.md. M4-A implements native rendering/framing and M4-B1 implements the explicit-file sink behavior above; M4-B2 integrates the automatic session. Both M5 Microsoft bridge directions are present in current source. This does not claim the published package, M6, or remaining package/release qualification.
Building And Testing Locally
Use Windows with a .NET 10 SDK and .NET Framework 4.8 available for the Framework test leg. Run from the repository root. Build Logger.sln first; it includes the library, tests, and example. The build restores dependencies if needed. Stop if it fails before testing.
dotnet build .\Logger.sln -c Debug
The test project uses
xunit.v3.mtp-off 4.0.1 through VSTest (xunit.runner.visualstudio 4.0.0 and
Microsoft.NET.Test.Sdk 18.10.1); both Microsoft Testing Platform runner switches are disabled.
Tests use Shouldly 4.3.0. The three remaining legacy boolean assertions in
DestinationManagementTests now use Shouldly, and the unused FluentAssertions 5.10.3
reference has been removed. Assertion expressions, expected values, all four test identities
and product operations are unchanged. Moq 4.20.72 supports destination mocks, and
coverlet.collector 6.0.4 supplies coverage.
Use this focused selection, sequentially on both targets, with coverage:
$filter = @(
'FullyQualifiedName~ProphetsWay.Logger.Tests.SensitivityLabelTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationLabelPolicyTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.BasicTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.GenericBasicTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.AdvancedTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.GenericAdvancedTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.LoggerTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.GenericLoggerTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.MetadataLoggerTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.ILoggingDestinationTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.LogAnnotationsTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.EventDestinationTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationRegistrationSettingsTests.'
'FullyQualifiedName~ProphetsWay.Logger.Tests.TextRenderingTests.'
) -join '|'
dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj -c Debug -f net48 --no-build --no-restore --filter $filter --collect "XPlat Code Coverage"
dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj -c Debug -f net10.0 --no-build --no-restore --filter $filter --collect "XPlat Code Coverage"
This selection includes native scope/context/settings, guarded-destination and text-rendering specifications, not just the earlier severity and standalone-policy tests. Its discovered count may change as regressions are added. Every C# example above requires independent compile-only checking against both library assets; do not execute the programs as part of that check. This README update does not claim that check, the parent final gate, or release approval passed.
Historical VS Code validation tasks are archived unchanged in
historical-tasks.pre-test-rename.json, not
loaded as active tasks. The current .vscode/tasks.json provides
Logger build current solution, Logger safe tests net48 and Logger safe tests net10.0.
Build first, then run the two test tasks sequentially. They add the four bridge classes
(LogBridgeRepresentationTests, MicrosoftLoggerProviderTests,
MicrosoftLoggerFactoryExtensionsTests, MicrosoftLoggerDestinationTests) to the 14-class
selection above, use the plural project/filter names and write generated TRX/coverage outputs
under TestResults/developer/<target>, not historical run destinations. No task runs
automatically. The archive preserves old commands and evidence references as history,
not instructions to reactivate them.
The following figures are historical selections, not totals for the current source or rendering checks.
The recorded M2-B Windows check on 2026-09-18 EDT passed 320/320 cases on each of
net48 and net10.0, with zero failures/skips: 20 new registration cases plus the
original 300 preserved cases per target. Library and example builds also passed; the
example was not executed. This is focused explicit-registration evidence, not full-suite or
full-v4 certification, fallback/file qualification, independent review approval, or release clearance.
The earlier native Windows check on 2026-09-17 EDT passed 300 cases per target, with zero failures/skips and unchanged same-target case identities. The recorded coverage exercises all seven changed implementation files plus label/policy code; the net48 test copy matches the built netstandard2.0 library, and net10.0 matches its dedicated library. FileDestination, ConsoleDestination and ConsoleWrapper have zero covered lines in this selection. See the portable native assessment. This is a focused result, not the full suite, file/console execution, package-consumer qualification, or Mac/Linux validation.
The earlier label-policy check on the same date recorded 110 cases per target: 67 policy cases plus 43 preserved cases. Its different selection included ConsoleDestinationTests; the historical account is retained separately, not presented as the native check above.
Do not substitute an unfiltered dotnet test as the default developer check.
FileDestinationTests.cs now uses isolated synthetic
files, but its path/failure checks temporarily change process state; run that class in a separate
reviewed test host, not in the default selection above.
The four existing cases in
DestinationManagmentTests.cs now use
DestinationManagementFixture.cs
to exercise real public add/remove/clear/absent-remove operations against fresh loaded Logger state.
Automatic output after removal or clearing is confined to owned synthetic paths, not a real
application's directories. Following independent readiness review, Windows execution on 2026-10-24 passed
all four cases on each of net48 and net10.0, with zero failures or skips, in separate fresh
VSTest hosts against the exact readiness-reviewed inputs. Final evidence and code/docs review
remain separate gates; this is not an unfiltered run, same-host full-suite proof, full M6,
non-Windows verification or release approval. Counts from earlier selections are historical,
not a fixed total for the evolving test tree.
For this isolated class on Windows, use the D021
parent c:/temp/logger tests/. The delivered LOGGER-CI-FIX-R1/R2 fixture repair safely prepares
missing ordinary-directory ancestry, preserves the existing parent and entries, and rejects
symlinks/reparse points and non-directories. On POSIX, the fixture uses the canonical OS temporary
directory. On 2026-10-26, Windows Release validation passed the solution build and
863/863 tests on each of net48 and net10.0, with zero failures or skips, using the CI
filter Requires!=LocalDb. Native Linux/macOS hosted reruns remain required.
Use fresh uniquely owned children containing synthetic data. Clean only verified owned children
after users and handles finish; never delete the parent, change pre-existing files or follow
links/junctions outside the owned tree. Location permission is not permission to run old
unisolated tests.
After a build of the reviewed candidate, run each command separately and sequentially from the
repository root, without other test runs or concurrent builds. Each invocation starts a separate
VSTest host and selects only DestinationManagementTests; do not merge it into the default
18-class selection or combine it with file/process-state classes:
dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj --configuration Debug --framework net48 --no-build --no-restore --filter "FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationManagementTests." --logger trx --results-directory .\TestResults\developer\destination-management\net48
dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj --configuration Debug --framework net10.0 --no-build --no-restore --filter "FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationManagementTests." --logger trx --results-directory .\TestResults\developer\destination-management\net10.0
The equivalent optional manual tasks are Logger isolated destination management tests net48
and Logger isolated destination management tests net10.0. They neither build nor start other
tasks, and write generated TRXs to the target-specific directories above. The three existing
build/safe-test tasks and their filters remain unchanged; none runs automatically.
The example program constructs a relative file destination too: build it, do not run it by default. The existing pipeline is not evidence that this exact focused selection ran in CI.
Contributing
Keep changes focused and add xUnit/Shouldly coverage for new behavior. Preserve the intentional
utility namespace and consult AGENTS.md before changing public contracts or build files.
Use synthetic data; file fixtures must not alter pre-existing files. The current test project,
assembly and namespace use ProphetsWay.Logger.Tests; the library remains ProphetsWay.Logger
with its intentional ProphetsWay.Utilities namespace. D025 authorizes this test-only rename,
not unrelated contract, dependency or version changes.
Versioning And Authors
We use SemVer for versioning. For the versions available, see the tags on this repository. The owner controls version changes; this README does not authorize a bump or a release.
- G. Gordon Nasseri - Initial work - ProphetManX
See also the list of contributors who participated in this project.
Changelog
See CHANGELOG.md for unreleased changes and the existing release history.
License
This project is licensed under the MIT License - see the LICENSE file for details.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
-
net10.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 4.0.0 | 117 | 10/31/2026 |
| 4.0.0-527.Beta | 50 | 10/30/2026 |
| 4.0.0-527.Alpha | 53 | 10/30/2026 |
| 3.0.1-420.Beta | 291 | 5/13/2022 |
| 3.0.1-420.Alpha | 260 | 5/13/2022 |
| 3.0.1-418.Alpha | 277 | 5/13/2022 |
| 3.0.1-352.Beta | 269 | 4/27/2022 |
| 3.0.1-352.Alpha | 257 | 4/27/2022 |
| 3.0.0 | 694 | 1/26/2021 |
| 3.0.0-248.Beta | 332 | 1/26/2021 |
| 3.0.0-248.Alpha | 326 | 1/26/2021 |
| 2.2.0-238.Alpha | 346 | 1/26/2021 |
| 2.1.0 | 731 | 6/3/2020 |
| 2.1.0-182.Beta | 423 | 6/3/2020 |
| 2.1.0-182.Alpha | 413 | 6/3/2020 |
| 2.0.0 | 972 | 4/20/2019 |
| 2.0.0-105.Alpha | 473 | 4/21/2019 |
# Unreleased
## Hosted test-harness portability (native POSIX verification pending)
Owner-approved LOGGER-CI-FIX-R1/R2 implements safe preparation of missing Windows fixture-parent
ancestry, architecture-correct Darwin inode64 bindings, fresh POSIX directory enumeration and
platform-native inert mock paths. Reserved product-created entries must be observed explicitly
at quiescent boundaries; reset must verify selected-file absence before retiring only that old
identity, without lazy adoption or weakened no-follow checks. Windows Release validation on
2026-10-26 passed the solution build and 863/863 tests on each of `net48` and `net10.0`,
with zero failures or skips, using the CI filter `Requires!=LocalDb`.
Initial hosted Windows, Linux and macOS attempts failed, with leading defects in fixture setup,
native ABI/enumeration, ownership identity capture and Windows-only mock inputs; no shipped
Logger bug is established. No passing native Linux/macOS verification is recorded; hosted
reruns remain required, and Windows success or ABI declaration proxies cannot certify them.
This test-harness repair changes no public API, library asset, version or Logger runtime behavior.
## Assertion migration
The three remaining legacy boolean assertions in `DestinationManagementTests` now use
Shouldly instead of FluentAssertions, and the unused FluentAssertions 5.10.3 test-project
reference has been removed. Assertion expressions, expected values, all four test identities
and product operations are unchanged. This completes the assertion/dependency migration
only; it does not claim full M6, release qualification or non-Windows verification.
## Test tooling naming
The owner-approved test project name is now `ProphetsWay.Logger.Tests`, including its
directory, project file and test namespaces. Solution references and current developer
guidance follow the plural name. This mechanical rename preserves test bodies, assertions,
dependencies, target frameworks and the project GUID; the test assembly is not shipped.
Logger runtime behavior, public library namespaces, package identity and version are unchanged.
Historical evidence retains its original identities; fresh validation is required for the rename.
## Destination management test isolation
The four existing `DestinationManagementTests` cases now exercise real public destination
management through fresh loaded Logger state with owned synthetic automatic-file output beneath
the D021 parent `c:/temp/logger tests/`. Method identities and existing assertions are preserved;
Logger runtime behavior, public API, dependencies and version are unchanged. Separate fresh Windows
VSTest hosts passed 4/4 cases on each of `net48` and `net10.0`, with zero failures or skips,
against the readiness-reviewed inputs on 2026-10-24. Final evidence and code/docs review remain
separate gates; this is not same-host full-suite, unfiltered, full M6, non-Windows or release proof.
README guidance and two optional manual class-only tasks keep this execution separate from the
unchanged default 18-class filters. The three existing tasks and historical task archive remain
unchanged. These documentation changes do not requalify the updated package README or package.
## Packaging and debugging metadata
The Logger package project now declares its GitHub project URL and `logging;logger;diagnostics`
tags, uses the standard `git` repository type, and opts into XML documentation, repository metadata,
embedded untracked sources, portable symbol generation, and `.snupkg` symbol packaging. CI-only
`ContinuousIntegrationBuild` is enabled when `TF_BUILD` is `True`, so deterministic CI build metadata
is separated from local builds. These are additive packaging and debuggability improvements; they do
not add runtime API or decide the overall v4 compatibility and versioning question.
The XML documentation setting currently surfaces 58 `CS1591` compiler occurrences, which remain
unresolved. The project metadata has been updated, but package contents, evaluated local-versus-CI
properties, remote Source Link/debugger retrieval, and binary reproducibility are not claimed here.
## Logging abstractions dependency
The Logger library now directly references `Microsoft.Extensions.Logging.Abstractions` `10.0.12`. Consumers should account for the corresponding transitive restore closure, including `Microsoft.Extensions.DependencyInjection.Abstractions` and the supporting `System.*` packages selected for the target framework. This entry records dependency adoption only; it does not claim that the current build, tests, or package qualification have completed.
## Inbound Microsoft logging bridge
Current unreleased source adds `MicrosoftLoggerFactoryExtensions.AddProphetsWay(ILoggerFactory,
IMicrosoftLogLabelMapper = null)`. An explicit call creates one `MicrosoftLoggerProvider`, registers
that provider with the supplied factory, and returns the same provider. Its provider-created loggers
retain their supplied categories and share the provider's lifetime and scope source. Inbound dispatch
uses the exact `LogBridgeEntry` route while retaining concrete `LogBridgeEntry<TState>` payloads.
Callers may explicitly supply an `IMicrosoftLogLabelMapper`; the mapper and factory are borrowed.
The host must arrange provider cleanup by explicitly disposing the returned provider or ensuring
the factory/provider's normal lifetime handling retires it; provider disposal is idempotent. The
provider begins with its own logical-flow scope source; a caller-supplied external scope source and
its scope handles remain borrowed and are cleaned up by their opener. The provider does not dispose
the factory, mapper, supplied scope source, or native destinations.
This describes current source, not the published package or release qualification. The outbound
Logger-to-Microsoft destinations are described separately below; enabling this inbound provider does
not register them. This entry does not claim M5/M6 completion.
## Outbound Microsoft logging destinations
Current unreleased source adds two opt-in outbound destinations: `MicrosoftLoggerDestination` for
ordinary native entries and `GenericMicrosoftLoggerDestination<T>` for an exact declared-`T` route.
Each accepts either a borrowed `ILoggerFactory` (with an optional category fallback) or a borrowed
fixed `ILogger`. Register them explicitly with `Logger.AddDestination(destination)` or
`Logger.AddDestination<T>(destination)`; outbound registration does not install the inbound provider.
Native severity and label selection happen before Microsoft callbacks. The adapter maps one lowest
set native severity bit to one Microsoft level, retains the original mask and available entry state,
exception, event/category, structured properties, and separate native-context/external-scope facts.
The transport keeps entry, native contexts and external scopes in distinct ordered groups; scope
replay preserves individual frames and cleans returned handles in reverse order. The factory's
category fallback applies only when the source category is null; a fixed logger retains its category.
`IsEnabled == false` is normal rejection. The destination does not classify or sanitize consumer data.
Registration does not transfer ownership: clearing or removing a destination does not dispose its
factory or fixed logger. Output and cleanup failures follow Logger's safe reporting and propagation
contract. This describes current unreleased source only, not the published package, package/consumer
qualification, M6 completion, release readiness, or non-Windows verification.
## Controlled Microsoft bridge returns
- Fixed unchanged controlled outbound calls fanned out through multiple `AddProphetsWay`
providers to preserve original entry labels and visited-route suppression on matching receipts.
- Fixed controlled-return registration selection, intrinsic/custom severity checks and native
handoff to use the retained full native severity mask rather than the projected Microsoft level.
## Support and tooling
The library target set is now `netstandard2.0;net10.0`. This removes dedicated assets for the
older .NET Framework, .NET Standard 1.x, .NET Core, .NET 5 and .NET 6 targets, including the former
`net48` library asset. Consumers that can use the `netstandard2.0` asset remain supported; consumers
that require one of the removed assets must move to a compatible `netstandard2.0` consumer or to
`net10.0`. This target change is breaking and requires a major-version decision before publication.
The test project now exercises `net48` and `net10.0` with the refreshed xUnit v3 tooling. This changes
the verification matrix, not the Logger runtime behavior.
## Native severity and destination validation
The native Logger severity model now has six exact bits: `Critical = 1`, `ErrorOnly = 2`,
`WarningOnly = 4`, `InformationOnly = 8`, `DebugOnly = 16`, and `TraceOnly = 32`. Inclusive
destination masks are `Error = 3`, `Warning = 7`, `Information = 15`, `Debug = 31`, and
`Trace = 63`; a destination accepts a composite message only when it contains every requested bit.
The three public `Security` helper forms have been removed. The Logger's internal `Log` helpers remain
private, while `Log` on destination interfaces remains public for direct destination calls. There is
no compatibility replacement for the removed `Security` names, so callers must select the new severity
helper that matches their intent.
The ordinary, metadata-typed, and metadata extension helper families now expose the six severity
operations with exact-bit delivery and explicit argument requirements: `Trace`, `Debug`, `Info`, and
`Warn` require a message; `Error` requires an exception and permits a missing message; `Critical`
requires both. Existing callers should update removed helpers and any calls that relied on omitted
arguments or on the former cumulative severity values.
Destination masks supplied as enum values, integers, or recognized case-sensitive strings are now
validated strictly. Values from 0 through 63 are representable, including unnamed combinations such
as `9`; zero is a valid active reject-all destination mask. The new validation rejects invalid, negative,
unsupported, malformed, or null inputs with argument errors; it does not imply that all such invalid
forms previously shared one `Information` fallback. Destination eligibility continues to require every
requested message bit, while the new raw and direct destination guards require a nonzero mask from 1
through 63 and validate before callbacks or output. Valid calls preserve the original composite mask,
message, metadata, and exception. Exception details are included for valid warnings and composites as
well as errors, including when the raw message is null; no synthetic message or exception is fabricated.
This is breaking for consumers that compile against the removed `Security` members or depend on the
old enum numbers, permissive helper arguments, or inputs now rejected by strict validation. The current
tree is unreleased v4-direction source; this entry describes the native severity change, not full v4
integration or the output-failure policy. The outbound Microsoft bridge is recorded in its separate
current-source entry below. Native text framing is covered by the M4-A entry; remaining qualification
work is not claimed here.
## Sensitivity labels
A new immutable `SensitivityLabel` reference type is available in `ProphetsWay.Utilities`. Create one
with an application-defined identifier, for example:
```csharp
var label = new SensitivityLabel("internal");
```
Labels retain their exact non-null identifier, compare by ordinal value, and provide a matching hash
code. Identifiers must contain 1 through 256 UTF-16 code units and must not contain whitespace or
control characters. Invalid input is rejected without copying the supplied identifier into argument
diagnostics.
## Pure destination-label policy
The new `LabelFilterMode` enum (`NoFilter`, `Exclude`, and `AllowOnly`) and `DestinationLabelPolicy`
class provide immutable, defensive-copying membership evaluation. `Exclude` rejects any intersecting
label; `AllowOnly` requires nonempty effective membership wholly contained in the configured labels;
`NoFilter` permits valid effective input. Duplicate identities and ordering do not affect the result,
and null labels or undeclared modes are rejected with argument errors.
This remains a standalone predicate API for callers that want to evaluate a policy directly; it does
not render or redact content, select fallback destinations, or provide confidentiality or security
guarantees. M3 also uses the immutable policy as an additional whole-entry gate through
`DestinationRegistrationSettings` and the destination's intrinsic `LabelPolicy`: both configured
and intrinsic restrictions must permit the complete effective label union before payload delivery.
A label denial is a deliberate non-failure and does not select fallback; enabled membership still
suppresses fallback on that route.
The pure destination-label policy now protects its configured membership readback from ordinary collection-interface mutation attempts, including the synchronization-root path that previously exposed its owned backing list on the modern runtime. Constructed policies retain the same deduplicated, ordinal membership, and `Mode`, `Allows`, and the public API remain unchanged; consumers do not need to change their calls.
## Explicit destination registration
The existing ordinary and metadata-typed registration methods now maintain separate, exact routes. A
typed registration is selected by its declared `T`, not by runtime metadata assignability, and a
destination-contract type does not alias the ordinary route. The same compatible destination reference
may be registered on distinct routes, but adding that same reference twice to one route now throws
`ArgumentException` with `ParamName` `newDest`. Removal is reference-only, so an equal but distinct
destination remains registered, survivor order is preserved, and remove/clear affect only their selected
route. These are breaking behavior changes for callers that relied on duplicate registration, equality-
based removal, or ordinary/typed route sharing; no method signature or public type was added, and callers
should register each intended route explicitly and retain the reference they intend to remove.
Registration and dispatch now publish complete ordered membership captures before user eligibility or
callbacks run. Mutations from those callbacks affect later captures, recursive dispatch captures again,
and an older capture may still invoke a removed or cleared destination after the mutation returns.
Registration does not invoke recipients, and remove/clear never dispose borrowed destinations; hosts
must quiesce producers and await synchronous calls before disposing them. This corrects the prior live-
enumeration and ownership hazards without promising a drain, immediate revocation, or automatic fallback.
## Log annotation occurrences
The new `LogAnnotations` value captures an explicit `IEnumerable<SensitivityLabel>` through its
constructor and exposes the successful capture through the read-only `LabelOccurrences` property.
The constructor copies the supplied occurrences in order, preserves duplicates, accepts an empty
sequence, and rejects null input or null elements. A failed or unsupported sequence capture does not
publish a usable partial value; callers remain responsible for providing a finite, stable sequence.
The returned collection is read-only. `BeginScope` can attach one to a native scope and
`LogAnnotated` can attach one to an entry; dispatch captures the enclosing scopes and entry
annotation together before recipient callbacks, while the policy predicate still uses deduplicated
ordinal membership rather than occurrence order. An annotation remains data, not authorization,
classification, formatting, redaction, or a security guarantee.
## Configured dispatch failure reporting
Configured ordinary and declared-typed routes now capture the complete route, settings, scopes and
effective labels before attempting each enabled, independently eligible recipient. Registration
severity, destination severity and both applicable label policies must permit the entry; a contextual
recipient receives one contextual handoff and a legacy recipient receives one raw handoff. A deliberate
Boolean label denial withholds the entry from that recipient without recording a failure; a
`LabelCheck` exception is recorded and returns through the safe report boundary. Neither kind of label
outcome stops later captured recipients, while an eligibility or output callback failure also does not
stop later captured recipients.
After applicable attempts, the call attempts bounded notification through `Logger.DispatchFailed` when
subscribers are present and same-thread recursive reporting is not already suppressed, along with the
ordinary stderr summary, then throws `LogDispatchException` for mandatory eligibility/output failures.
A capture or check-only failure therefore permits the whole call to return safely only when no mandatory
eligibility/output failure also occurred, so mixed outcomes remain represented by `LogDispatchException`.
The report exposes a correlation ID, encounter-ordered failure descriptors with each recipient's
one-based captured position and `LabelCheck`, `Eligibility` or `Output` stage, an overflow count when
more failures occurred than the retained descriptor limit, and a separate `CoreCaptureFailureCount`
for a shared capture failure. Subscriber failures are contained, and the safe exception/report boundary
does not retain or expose the original callback causes.
Consumers that previously handled only the first raw recipient exception should instead catch
`LogDispatchException` and inspect its `Report`, and may subscribe to `Logger.DispatchFailed` when they
need the bounded notification. This contract applies to configured routes; unconfigured fallback
behavior remains separately qualified, and it does not claim automatic fallback, retries, rollback,
or full exception-graph sanitization.
The configured-route failure behavior corrects the prior single-failure propagation boundary. This
entry records that configured-route slice, not the full v4 integration or automatic Trace/file behavior.
Native text framing is recorded in the M4-A entry below; file lifecycle/termination and broader
qualification are separate. Current outbound source behavior is described in the M5 entry above.
## Native scopes and contextual destinations
The Logger now captures native scopes and entry annotations into an immutable `LogContext`. Use
`BeginScope` for ordered scope properties and labels, and `LogAnnotated` for entry labels; captured
scope and label membership is complete at capture time, while nested property values remain the
caller-owned objects. Scope handles are flow-local and conventional: dispose them in order, and do
not treat a retained `LogContext` as authorization to bypass current destination checks.
Destination registration now has immutable per-registration `Enabled`, severity-mask, and label-policy
settings. `SetDestinationSettings` publishes a complete replacement atomically, so a callback sees
either the old settings or the new settings rather than a partially updated combination. The ordinary
and exact-declared-metadata-type routes remain separate. Existing independent destination interfaces
remain valid; contextual interfaces are optional extensions for destinations that need the captured
context.
Supplied destinations and base classes now expose guarded direct `Log` calls and optional
`LogWithContext` calls. Custom destinations deriving from `BaseLoggingDestination` or
`BaseLoggingDestination<T>` must move their implementation to the protected `LogCore` override;
the public logging entrypoints are guarded and are no longer the subclass override point. This is a
source and binary compatibility break for custom destinations that overrode the former public logging
member. Built-in event destinations expose the selected context through their event arguments, while
event delivery preserves the original payload, metadata, exception and existing event semantics. Native
text rendering and framing are covered by the separate M4-A entry below.
Failure results now distinguish a failed native capture from a destination `LabelCheck`, `Eligibility`,
or `Output` failure. Shared capture and label-check failures report safely and return without handing
the incomplete or rejected entry to that recipient; eligibility and output failures remain mandatory
`LogDispatchException` results after independent attempts. `CoreCaptureFailureCount` records the core
capture count without inventing a recipient failure, and failure-report membership no longer exposes a
writable `SyncRoot` alias through collection interfaces. Consumers reading `LogDispatchException.Report`
can therefore distinguish these safe result paths without receiving callback causes or payload data.
This M3 work is unreleased and does not by itself claim publication or release readiness. The custom
destination override change has major-version implications; the new scope, annotation, contextual
delivery, settings, and failure-report members are additive individually, but they do not make that
overall compatibility decision a minor or patch change. The accepted local validation is green on the
focused `net48` and `net10.0` matrix, with the library/example builds and compile-only README checks
also passing; it is not unfiltered real-file fixture certification. The permanent report-membership
regression and parent final gate are complete within that accepted local boundary; they are not pending release work. M4-A native text rendering and framing is now implemented as a separate unreleased slice. M4-B, the outbound Microsoft bridge, file lifecycle/termination and broader release qualification were separate from this M3 scope; later Unreleased entries describe subsequent work.
## Native text rendering and framing
Native ordinary and exact-declared-metadata text destinations now render one complete, unterminated
single-line record from the call's captured `LogContext.EventTimestampUtc`. The prefix uses invariant
UTC `O` formatting and the existing full severity spelling; entry labels and every captured native scope
frame follow in their original order, including empty frames, duplicate labels, repeated or null keys,
and null values. Message, exception, metadata, label, key, and formatted property-value content is
escaped as data, so null, empty, whitespace, literal `null`, and embedded line boundaries remain
distinct without being silently discarded. Raw/event transport and the existing local event timestamp
semantics are unchanged.
This changes the default text layout and is a breaking output-contract change for consumers that parse,
snapshot, or otherwise depend on the former local-time prefix and message-only text. Update those parsers
and fixtures to the structured record layout; custom text destinations still implement `PrintLogEntry`,
but must treat its input as the new complete record rather than reconstructing the old layout. The new
`LogContext.EventTimestampUtc`, protected `FormatValue(object value)` hook, and
`GenericTextBasedDestination<T>` are additive individually. The default formatter supports the documented
scalar set with invariant formats, returns `[no formatter: TypeName]` for unsupported values, and emits
null as a null token; an override may extend scalar formatting, but a thrown formatter, massage, render,
or print operation remains an output failure. Consumers overriding `FormatValue` should return unescaped
text and leave framing/escaping to the destination.
This M4-A slice does not claim automatic Trace/file behavior, physical file termination or lifecycle,
either Microsoft bridge direction, fallback completion, or publication/release qualification. Current
inbound and outbound Microsoft source behavior is described in separate entries above; neither was
part of this native text-framing slice. This is an unreleased v4-direction slice; no version number is
changed here.
## Explicit file destinations
`FileDestination` now defaults all three constructor overloads to `resetFile: false`, so constructing a
destination no longer deletes an existing selected file unless deletion is explicitly requested with
`resetFile: true`. This is a breaking v4-direction behavior change for source callers that omitted the
argument: recompile them with the desired value. Previously compiled callers retain the default value
embedded in their call site until rebuilt, and callers that already pass `true` retain eager deletion.
The destination captures the selected `fileName` path at construction and writes back to that same path,
creating a missing file there on permitted output. Each write appends the rendered record followed by one
`Environment.NewLine`, using the selected one of the five declared encodings (`ASCII`, `BigEndianUnicode`,
`Unicode`, `UTF8`, or `UTF32`). It does not add a BOM, repair an unterminated existing prefix, inspect or
transcode existing bytes, or relocate output. Undefined encoding values now fail with
`ArgumentOutOfRangeException` for `encoder` before deletion or directory creation. Invalid `fileName`
values identify `fileName`; ordinary framework filesystem and access diagnostics remain the originating
exceptions rather than being replaced by a console echo.
This remains an explicit-file implementation only. It does not claim automatic fallback, recovery, retry,
replay, relocation, shared-session behavior, or publication/release qualification. The default change and
the established file-output contract have major-version implications; the version file remains unchanged.
## Automatic file destinations
Automatic file output is now enabled as the implicit final `Trace` recipient for an ordinary route and
for each exact declared-metadata-type route when that route has no enabled compatible explicit
registration. An enabled explicit destination that rejects or fails still suppresses that route's
automatic output; automatic output does not rescue it, and a label denial remains a deliberate
non-failure. Ordinary and typed automatic routes share one session and one selected pathname, while
remaining distinct for rendering and metadata retention. The typed route preserves its declared
metadata, including `null` or `default(T)`.
The default primary directory is the consuming host's `AppContext.BaseDirectory`. Before the first
automatic attempt, applications may select a different primary directory:
```csharp
Logger.ConfigureAutomaticFileHostDirectory(directory);
```
The path is normalized when configured and must be supplied before automatic establishment starts;
configuration performs no directory or permission probe and cannot reset failure state or move an
existing file. If the captured primary location is unavailable during initial establishment, the
session tries one application-associated directory under
`Environment.SpecialFolder.LocalApplicationData`. It selects one UTF-8 file named with the UTC
allocation timestamp and a GUID token, creates missing directories and avoids an existing-name
collision. The selected pathname is retained for the session, and later records append one
`Environment.NewLine` after the complete native rendered record.
Initial inability to establish either location is remembered: the automatic attempt returns a
mandatory output failure on that call and later calls do not keep probing or silently switch
locations. After a pathname is selected, a later open, write, flush or disposal failure also remains
an output failure; the record is not replayed, relocated or retried. Consumers should handle the
existing `LogDispatchException` failure contract and should configure the primary directory before
the first log call when the host's base directory is not an appropriate output location. This is
additive API surface within the unreleased v4-direction change, whose automatic output, fallback
suppression and failure semantics are breaking behavior decisions; the version file remains `3.0.1`.
## Bridge carrier representation
The Logger now exposes the assembly-created `LogBridgeEntry`, `LogBridgeEntry<TState>`, and
`LogBridgeScope` carrier types. They preserve original typed or opaque state, declared state type,
producer delegate, exception, cached text, ordered structured property and scope frames, annotations,
and native source-origin context; their constructors remain assembly-only, and captured membership is
read-only without deep-freezing nested caller-owned values. As recorded with the carrier-only source
on 2026-10-03, that change did not add inbound or outbound adapters, activation, routing, loop guards,
or lifecycle behavior. Later M5 entries above describe the subsequent inbound and outbound source behavior.
## Microsoft log label mapper contract
The v4-direction contract now includes the public `IMicrosoftLogLabelMapper` interface for explicit
mapping of external Microsoft logging input to optional `LogAnnotations`. Implementations may map each
entry through `MapEntry<TState>` and each captured external scope frame through `MapScope`; the
callbacks receive the completed original facts and may return no attachment or a present annotation.
At the time this mapper contract was recorded on 2026-10-03, it was contract surface only and did not
include a provider implementation, callback invocation, routing, activation, or lifecycle behavior.
Current inbound callback use and outbound behavior are described in separate entries above; outbound
is not part of this mapper contract, and no release qualification is claimed here.