| | | 1 | | using Microsoft.Extensions.Configuration; |
| | | 2 | | using Microsoft.Extensions.Logging; |
| | | 3 | | |
| | | 4 | | namespace NexusLabs.Needlr.Hosting; |
| | | 5 | | |
| | | 6 | | /// <summary> |
| | | 7 | | /// Contextual data passed to the <see cref="NeedlrBootstrapper.RunAsync"/> callback. |
| | | 8 | | /// Provides access to a bootstrap logger and a bootstrap <see cref="IConfiguration"/> |
| | | 9 | | /// that are available before the DI container is built. |
| | | 10 | | /// </summary> |
| | | 11 | | /// <remarks> |
| | | 12 | | /// <para> |
| | | 13 | | /// Everything on this context is <strong>bootstrap-phase only</strong>. These resources |
| | | 14 | | /// exist solely to bridge the gap until the DI container is built. Once Syringe (or any |
| | | 15 | | /// host builder) creates the real <see cref="IConfiguration"/> and logging pipeline, |
| | | 16 | | /// the bootstrap versions are disposed and should no longer be referenced. |
| | | 17 | | /// </para> |
| | | 18 | | /// <para> |
| | | 19 | | /// In particular, <see cref="BootstrapConfiguration"/> is <strong>not</strong> the same |
| | | 20 | | /// <see cref="IConfiguration"/> that the application's DI container will provide. |
| | | 21 | | /// They are independent instances that may read different sources, have different |
| | | 22 | | /// precedence rules, or contain different values. Do not cache or leak the bootstrap |
| | | 23 | | /// configuration beyond the callback. |
| | | 24 | | /// </para> |
| | | 25 | | /// </remarks> |
| | | 26 | | /// <example> |
| | | 27 | | /// <code> |
| | | 28 | | /// await new NeedlrBootstrapper() |
| | | 29 | | /// .ConfigureBootstrapConfiguration(builder => builder |
| | | 30 | | /// .AddJsonFile("appsettings.json", optional: true) |
| | | 31 | | /// .AddEnvironmentVariables()) |
| | | 32 | | /// .RunAsync(async (ctx, ct) => |
| | | 33 | | /// { |
| | | 34 | | /// var logPath = ctx.BootstrapConfiguration["Logging:Path"] |
| | | 35 | | /// ?? "logs/bootstrap.log"; |
| | | 36 | | /// ctx.Logger.LogInformation("Bootstrap log path: {Path}", logPath); |
| | | 37 | | /// |
| | | 38 | | /// // Build the real app — Syringe creates its own IConfiguration independently. |
| | | 39 | | /// var host = new Syringe() |
| | | 40 | | /// .UsingSourceGen() |
| | | 41 | | /// .ForHost() |
| | | 42 | | /// .UsingOptions(() => CreateHostOptions.Default.UsingLogger(ctx.Logger)) |
| | | 43 | | /// .BuildHost(); |
| | | 44 | | /// await host.RunAsync(ct); |
| | | 45 | | /// }); |
| | | 46 | | /// </code> |
| | | 47 | | /// </example> |
| | | 48 | | public sealed record NeedlrBootstrapContext |
| | | 49 | | { |
| | | 50 | | /// <summary> |
| | | 51 | | /// Gets the bootstrap logger, available before the DI container is configured. |
| | | 52 | | /// </summary> |
| | | 53 | | /// <remarks> |
| | | 54 | | /// This logger is for bootstrap-phase diagnostics only. Once the DI container is built, |
| | | 55 | | /// the application's own <c>ILogger<T></c> pipeline takes over. |
| | | 56 | | /// </remarks> |
| | 31 | 57 | | public required ILogger Logger { get; init; } |
| | | 58 | | |
| | | 59 | | /// <summary> |
| | | 60 | | /// Gets a minimal <see cref="IConfiguration"/> built during the bootstrap phase, |
| | | 61 | | /// before the DI container exists. |
| | | 62 | | /// </summary> |
| | | 63 | | /// <remarks> |
| | | 64 | | /// <para> |
| | | 65 | | /// This configuration is for <strong>bootstrap-phase use only</strong>. It is |
| | | 66 | | /// <strong>not</strong> the same <see cref="IConfiguration"/> that will be available |
| | | 67 | | /// after the DI container is built. Syringe (and the .NET Generic Host / WebApplication |
| | | 68 | | /// builder) builds its own <see cref="IConfiguration"/> independently. The two may read |
| | | 69 | | /// the same files but are separate instances with no shared state. |
| | | 70 | | /// </para> |
| | | 71 | | /// <para> |
| | | 72 | | /// By default the bootstrap configuration is <strong>empty</strong>. Use |
| | | 73 | | /// <see cref="NeedlrBootstrapperExtensions.ConfigureBootstrapConfiguration"/> to add |
| | | 74 | | /// configuration sources (JSON files, environment variables, in-memory collections, etc.) |
| | | 75 | | /// that are needed during the bootstrap phase. |
| | | 76 | | /// </para> |
| | | 77 | | /// </remarks> |
| | 36 | 78 | | public required IConfiguration BootstrapConfiguration { get; init; } |
| | | 79 | | } |