klod68/gen-embedded-config-loader

---

name: gen-embedded-config-loader description: "Use when a .NET library needs to ship sensible default configuration that consumers can override without editing source. Generates a 3-tier config system: embedded JSON defaults, appsettings.json overrides, and environment variable overrides via a static accessor. Also invoke when the user mentions: embedded config, library defaults, appsettings override, embedded resource settings. Domain: Code Generation, Configuration. Level: Intermediate."

Generate an embedded resource configuration loader for the library: ${1:LibraryName}.

Context

• Namespace root: ${2:MyLib}
• Configuration section name: ${3:LibrarySettings}
• Settings (name, type, default, description): ${4:e.g. DefaultLanguage string en-US Language code, CacheTimeoutMinutes int 30 Cache TTL in minutes, EnableRetry bool true Enable transient retry}

---

Required output — generate ALL of the following:

1. Defaults JSON file

${2}/Settings/${1:lower}-defaults.json

{
  "${3}": {
    "Setting1": defaultValue1,
    "Setting2": defaultValue2
  }
}

All defaults from context above. Values must match the property types exactly (strings quoted, numbers unquoted, bools lowercase).

2. .csproj entry

<ItemGroup>
  <EmbeddedResource Include="Settings\${1:lower}-defaults.json">
    <LogicalName>${2}.Settings.${1:lower}-defaults.json</LogicalName>
  </EmbeddedResource>
</ItemGroup>

Resource name convention: {DefaultNamespace}.{FolderPath.WithDots}.{FileName}

3. Settings accessor class

${2}/Settings/${1}Settings.cs

/// <summary>
/// Provides ${1} configuration using 3-tier precedence:
/// consumer appsettings.json → embedded library defaults → hardcoded fallback.
/// </summary>
internal static class ${1}Settings
{
    internal const string EmbeddedResourceName =
        "${2}.Settings.${1:lower}-defaults.json";

    private const string SectionName = "${3}";

    private static readonly IConfiguration _embedded = LoadEmbedded();

    private static IConfiguration LoadEmbedded()
    {
        var stream = typeof(${1}Settings).Assembly
            .GetManifestResourceStream(EmbeddedResourceName);
        var builder = new ConfigurationBuilder();
        if (stream is not null)
            builder.AddJsonStream(stream);
        return builder.Build();
    }

    // One property per setting — 3-tier ?? chain
    // Tier 1: consumer appsettings  Tier 2: embedded JSON  Tier 3: hardcoded
}

For each setting, generate a property:

/// <summary>[Description]. Default: [default].</summary>
/// <remarks>Override: add <c>"${3}:SettingName": value</c> to appsettings.json.</remarks>
public static string SettingName =>
    ConsumerConfig.GetValue<string?>($"{SectionName}:SettingName")  // Tier 1
    ?? _embedded[$"{SectionName}:SettingName"]                       // Tier 2
    ?? "hardcoded-fallback";                                         // Tier 3

For numeric types use int.TryParse(... ?? ...) with the hardcoded fallback as the out parameter default.

4. Consumer configuration reference

Markdown table for documentation:

| Key | Type | Default | Description | |---|---|---|---|

And an example appsettings.json override block.

5. Verification snippet

// Add to a test or startup diagnostic to confirm the resource is embedded:
var names = typeof(${1}Settings).Assembly.GetManifestResourceNames();
Debug.Assert(names.Contains(${1}Settings.EmbeddedResourceName),
    $"Embedded resource '{${1}Settings.EmbeddedResourceName}' not found. " +
    $"Check the <EmbeddedResource> entry and <LogicalName> in the .csproj.");

---

Rules

• Settings class is internal static — consumers never access it directly
• Embedded config is loaded once at class init (static readonly) — never per-call
• A null stream (misconfigured resource) is handled gracefully — no crash
• Consumer Tier 1 has highest priority — library never overrides explicit consumer settings
• Hardcoded fallback matches the JSON default (defense in depth, not a different value)
• No mutable state — all properties are read-only computed values

---

Constraints

• Follow all rules in the workspace root instruction file
• No AddJsonFile with file paths — always GetManifestResourceStream
• No DI dependency — the settings class is static and self-contained
• ConsumerConfig is assumed to be a static accessor wrapping the host's IConfiguration (create a stub if it doesn't exist in this codebase)