Put an ILogger seam over the Serilog pipeline

Framework code reaches logging through Serilog's static Log, which pins the
project to one logger implementation and leaks Serilog types outward. Introduce
Microsoft.Extensions.Logging.ILogger as the abstraction in front of it, keeping
Serilog as the provider and the pipeline itself untouched.

AddFalloutLogging registers the abstraction over the pipeline and nothing else,
so any container can call it any number of times. Configuring the pipeline stays
separate because Logging.Configure is not idempotent: it reassigns Serilog's
Log.Logger on every call, and with no build it installs a pipeline with no file
sinks, no host sink and no filter, wiping out whatever a previous caller had set
up. BuildManager.Execute runs Configure explicitly, just before it builds the
provider.

The registration deliberately avoids services.AddLogging, which would install
MEL's own filter pipeline with an Information default -- a second level authority
that would drop trace and debug records before Serilog saw them, displacing
Logging.LevelSwitch.

ILogger<T> and ILogger are transient, not singleton. Logger<T> binds its inner
logger in its constructor, so a singleton would pin every consumer to whichever
pipeline was current at the first resolution -- the same failure Logging.Logger
stays uncached to avoid. ILoggerFactory stays a singleton because it is left
unbound and pins nothing. Transient does not rescue a component that holds a
logger across a pipeline swap, so that remaining constraint is documented at the
registration and on CreateSerilogLoggerFactory.

BuildManager.Execute now owns a per-run composition root and feeds the resolved
factory to a static facade on Logging, so the ~85 Log.* call sites and the static
build engine are unchanged. The provider is declared outside the try so it
survives into Finish(), but built inside it so a configuration failure still
returns the same exit code as before.

The seam is internal: it is framework foundation, not public surface yet. Nothing
in the public API changes and no output changes.

docs/dependencies.md gains rows for Serilog.Extensions.Logging,
Microsoft.Extensions.Logging.Abstractions and
Microsoft.Extensions.DependencyInjection. The DI row notes that Fallout.Build is
consumer-facing, so every consumer now pulls the container transitively.

First of the additive PRs in #428.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

Directory.Packages.props

@@ -16,11 +16,13 @@
     <PackageVersion Include="JetBrains.Annotations" Version="2026.2.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyModel" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
     <PackageVersion Include="Nerdbank.GitVersioning" Version="3.7.115" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <PackageVersion Include="NuGet.Packaging" Version="6.14.3" />
     <PackageVersion Include="Octokit" Version="14.0.0" />
     <PackageVersion Include="Serilog" Version="4.3.0" />
+    <PackageVersion Include="Serilog.Extensions.Logging" Version="10.0.0" />
     <PackageVersion Include="Serilog.Formatting.Compact" Version="3.0.0" />
     <PackageVersion Include="Serilog.Formatting.Compact.Reader" Version="4.0.0" />
     <PackageVersion Include="Serilog.Sinks.Console" Version="6.1.1" />

docs/dependencies.md

@@ -15,6 +15,7 @@ Central package versions are pinned in `Directory.Packages.props`; this page lin
 | `Microsoft.Build` (+ `.Framework`, `.Tasks.Core`, `.Utilities.Core`) | MSBuild engine — read/evaluate `.csproj`/`.props` files | `Fallout.ProjectModel`, `Fallout.MSBuildTasks` |
 | `Microsoft.Build.Locator` | Locate an installed MSBuild at runtime | `Fallout.ProjectModel` |
 | `Microsoft.CodeAnalysis.*` (CSharp, Workspaces, MSBuild, Analyzers) | Roslyn — C# parsing/compilation/analysis | `Fallout.SourceGenerators`, `Fallout.Cli` (Cake rewriter) |
+| `Microsoft.Extensions.DependencyInjection` | DI container for the per-run composition root that wires the logging seam ([#428](https://github.com/Fallout-build/Fallout/issues/428)) | `Fallout.Build`. Note the footprint: `Fallout.Build` is consumer-facing, so every consumer now pulls the container transitively. Deliberate, not accidental. It currently serves one internal composition root, and the plugin foundation ([milestone #6](https://github.com/Fallout-build/Fallout/milestone/6)) is what will use it more widely. |
 | `Microsoft.Extensions.DependencyModel` | Parse `.deps.json` runtime metadata | `Fallout.Build` |
 | `Microsoft.SourceLink.GitHub` | Source-link symbols into published nupkgs so debuggers can step into Fallout | All packable libs |
 | `Nerdbank.GitVersioning` | Build-time semver derived from git history | All packable libs |
@@ -27,6 +28,8 @@ Central package versions are pinned in `Directory.Packages.props`; this page lin
 |---|---|
 | `Serilog` + `Sinks.Console` + `Sinks.File` | The logging framework. All `Log.Information/Warning/Error` calls route through this. |
 | `Serilog.Formatting.Compact` (+ `.Reader`) | Structured JSON log format for machine-readable logs |
+| `Serilog.Extensions.Logging` | Serilog provider for `Microsoft.Extensions.Logging`. Backs the `ILogger` seam in `Fallout.Build`, so framework code logs against the abstraction while Serilog stays the provider. |
+| `Microsoft.Extensions.Logging.Abstractions` | The `ILogger` / `ILoggerFactory` abstraction itself. Abstractions only, no implementation and no filter pipeline. |
 
 ## Azure
 

src/Fallout.Build/Execution/BuildManager.cs

@@ -6,7 +6,9 @@
 using Fallout.Common.Tooling;
 using Fallout.Common.Utilities;
 using Fallout.Common.Utilities.Collections;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyModel;
+using Microsoft.Extensions.Logging;
 using Serilog;
 
 #pragma warning disable CA2255
@@ -44,9 +46,20 @@ public static int Execute<T>(Expression<Func<T, Target>>[] defaultTargetExpressi
         using var context = BuildContext.Activate();
         var build = new T();
 
+        // The composition root for the run. Declared out here so it survives into `finally` —
+        // Finish() still writes the outcome summary — but built inside the `try`, so a failure while
+        // configuring logging is reported the same way it was before there was a container.
+        ServiceProvider services = null;
+        IDisposable loggerFactoryScope = null;
+
         try
         {
+            // Configure installs the pipeline; AddFalloutLogging only registers the abstraction over
+            // it. Order matters here rather than inside the registration: a logger binds the ambient
+            // pipeline when it is created, so the pipeline has to exist before anything resolves one.
             Logging.Configure(build);
+            services = new ServiceCollection().AddFalloutLogging().BuildServiceProvider();
+            loggerFactoryScope = Logging.UseLoggerFactory(services.GetRequiredService<ILoggerFactory>());
 
             build.ExecutableTargets = ExecutableTargetFactory.CreateAll(build, defaultTargetExpressions);
             build.ExecuteExtension<IOnBuildCreated>(x => x.OnBuildCreated(build.ExecutableTargets));
@@ -91,6 +104,8 @@ public static int Execute<T>(Expression<Func<T, Target>>[] defaultTargetExpressi
         {
             Finish();
             Log.CloseAndFlush();
+            loggerFactoryScope?.Dispose();
+            services?.Dispose();
             // Per-run teardown (handler unsubscription + state reset) is owned by the BuildContext,
             // run when `context` is disposed at method exit.
         }

src/Fallout.Build/Fallout.Build.csproj

@@ -18,7 +18,10 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
     <PackageReference Include="Microsoft.Extensions.DependencyModel" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
+    <PackageReference Include="Serilog.Extensions.Logging" />
     <PackageReference Include="Serilog.Formatting.Compact" />
     <PackageReference Include="Serilog.Formatting.Compact.Reader" />
     <PackageReference Include="Serilog.Sinks.Console" />

src/Fallout.Build/Logging.DependencyInjection.cs

@@ -0,0 +1,62 @@
+using System;
+using System.Linq;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Logging;
+
+namespace Fallout.Common.Execution;
+
+/// <summary>
+/// Composition root for the logging seam. Serilog stays the provider. This only puts
+/// <see cref="ILogger"/> in front of it, so framework code can stop referencing Serilog directly.
+/// </summary>
+/// <remarks>
+/// Internal on purpose: the abstraction is the framework's own foundation, not public surface yet.
+/// The root <c>AssemblyInfo.cs</c> grants <c>InternalsVisibleTo</c> to <c>Fallout.Cli</c> and the
+/// spec assemblies, which is everything that needs to wire a container today.
+/// </remarks>
+internal static class LoggingServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers the <see cref="ILogger"/> abstraction over the Serilog pipeline.
+    /// </summary>
+    /// <remarks>
+    /// Registration only. This method never touches the pipeline, so any container can call it, any
+    /// number of times. Installing the pipeline is <see cref="Logging.Configure"/>, which the caller
+    /// runs explicitly just before it builds the provider.
+    ///
+    /// The two are kept apart because <see cref="Logging.Configure"/> is not idempotent. It
+    /// reassigns Serilog's <c>Log.Logger</c> on every call. Called with no build, it installs a
+    /// pipeline with no file sinks, no host sink and no filter. A second container calling this
+    /// method would then wipe out the pipeline the first one had set up.
+    ///
+    /// Deliberately not <c>services.AddLogging(...)</c>. That installs Microsoft.Extensions.Logging's
+    /// own filter pipeline, whose default minimum is
+    /// <see cref="Microsoft.Extensions.Logging.LogLevel.Information"/> — qualified because the
+    /// unqualified name binds to Fallout's own <see cref="LogLevel"/> from the enclosing namespace.
+    /// It would be a second authority on levels, dropping trace and debug records before Serilog
+    /// ever saw them.
+    /// Registering the Serilog factory directly leaves <see cref="Logging.LevelSwitch"/> as the only
+    /// thing that decides what gets logged.
+    /// </remarks>
+    public static IServiceCollection AddFalloutLogging(this IServiceCollection services)
+    {
+        // Safe as a singleton because the factory is left unbound: it reads the ambient pipeline
+        // every time it creates a logger. See Logging.CreateSerilogLoggerFactory.
+        services.TryAddSingleton(_ => Logging.CreateSerilogLoggerFactory());
+
+        // Transient, not singleton. Logger<T> resolves its inner logger in its constructor, and the
+        // non-generic lambda would run once per container. As singletons, both would pin every
+        // consumer to whichever pipeline was current at the first resolution. Log.Logger does not
+        // stay put during a run: Configure installs it late, and Host.WriteErrorsAndWarnings swaps
+        // it again to render the end-of-build summary.
+        //
+        // Transient means each resolution binds to the pipeline that is current right now. It does
+        // not rescue a component that resolves a logger once and holds it across a swap. Any
+        // component that outlives a swap must read Logging.Logger at the point of writing instead.
+        services.TryAddTransient(typeof(ILogger<>), typeof(Logger<>));
+        services.TryAddTransient(sp => sp.GetRequiredService<ILoggerFactory>().CreateLogger(Logging.DefaultCategoryName));
+
+        return services;
+    }
+}

src/Fallout.Build/Logging.cs

@@ -10,15 +10,27 @@
 using Serilog;
 using Serilog.Core;
 using Serilog.Events;
+using Serilog.Extensions.Logging;
 using Serilog.Formatting.Compact;
 using Serilog.Sinks.SystemConsole.Themes;
 
+// Both Serilog and Microsoft.Extensions.Logging declare an ILogger. This file is the seam between
+// them, so the unqualified name is bound to the abstraction the framework codes against; Serilog's
+// own pipeline is reached through the static Log class below.
+using ILogger = Microsoft.Extensions.Logging.ILogger;
+using ILoggerFactory = Microsoft.Extensions.Logging.ILoggerFactory;
+
 namespace Fallout.Common.Execution;
 
 public static class Logging
 {
     public static readonly LoggingLevelSwitch LevelSwitch = new();
 
+    /// <summary>Category for framework log records written without a category of their own.</summary>
+    internal const string DefaultCategoryName = "Fallout";
+
+    private static ILoggerFactory loggerFactory;
+
     internal static bool SupportsAnsiOutput =>
         Environment.GetEnvironmentVariable("TERM") is { } term && term.StartsWithOrdinalIgnoreCase("xterm");
 
@@ -40,6 +52,61 @@ public static LogLevel Level
         set => LevelSwitch.MinimumLevel = value.ToLogEventLevel();
     }
 
+    /// <summary>
+    /// Logger factory for the current build run, backed by the Serilog pipeline that
+    /// <see cref="Configure"/> installs. <c>BuildManager</c> feeds this from its composition root
+    /// (see <c>AddFalloutLogging</c>). Outside a run there is no container — the CLI commands call
+    /// <see cref="Configure"/> directly — so this falls back to a factory over the ambient Serilog
+    /// pipeline, and the seam is usable either way.
+    /// </summary>
+    internal static ILoggerFactory Factory => loggerFactory ??= CreateSerilogLoggerFactory();
+
+    /// <summary>
+    /// Logger for framework code that has no category of its own. Deliberately not cached — each
+    /// access creates a logger against the pipeline that is current right now, which is what keeps
+    /// the façade correct across the reassignments described on
+    /// <see cref="CreateSerilogLoggerFactory"/>.
+    /// </summary>
+    internal static ILogger Logger => Factory.CreateLogger(DefaultCategoryName);
+
+    /// <summary>
+    /// Points <see cref="Factory"/> at <paramref name="factory"/> until the returned bracket is
+    /// disposed. Ownership stays with the caller: disposing the bracket restores the previous
+    /// factory, it does not dispose <paramref name="factory"/>.
+    /// </summary>
+    internal static IDisposable UseLoggerFactory(ILoggerFactory factory)
+    {
+        return DelegateDisposable.SetAndRestore(() => loggerFactory, factory.NotNull());
+    }
+
+    /// <summary>
+    /// Bridges <see cref="ILogger"/> onto Serilog.
+    /// </summary>
+    /// <remarks>
+    /// Passing no logger leaves the factory itself unbound, so each logger it hands out reads the
+    /// ambient <see cref="Log.Logger"/> as it is created. That matters because the pipeline is not
+    /// stable for the lifetime of the process: <see cref="Configure"/> installs it late and
+    /// replaces it on re-entry, and <c>Host.WriteErrorsAndWarnings</c> swaps it again to render the
+    /// end-of-build summary. Pinning a logger into the factory would strand every consumer on
+    /// whichever pipeline happened to exist first.
+    ///
+    /// Binding still happens per logger rather than per write, because the category name is
+    /// attached as Serilog's <c>SourceContext</c> at construction. Three consequences the callers
+    /// depend on. <see cref="Configure"/> runs before the container is built, so a resolved logger
+    /// can never bind a pipeline that is already gone. The container registrations for
+    /// <c>ILogger&lt;T&gt;</c> and <see cref="ILogger"/> are transient, so each
+    /// resolution binds the pipeline that is current right now. And <see cref="Logger"/> is not
+    /// cached, for the same reason. A component that resolves a logger once and holds it across a
+    /// reassignment still writes into the old pipeline, so anything living that long must read
+    /// <see cref="Logger"/> at the point of writing.
+    ///
+    /// Serilog owns the pipeline's lifetime (<c>Log.CloseAndFlush</c>), hence <c>dispose: false</c>.
+    /// </remarks>
+    internal static ILoggerFactory CreateSerilogLoggerFactory()
+    {
+        return new SerilogLoggerFactory(logger: null, dispose: false);
+    }
+
     public static void Configure(IFalloutBuild build = null)
     {
         if (build != null)