klod68/embedded-resource-configuration

---

name: embedded-resource-configuration description: "Use when building a .NET library distributed via NuGet that needs default configuration values shipped with the assembly, when you want zero-configuration defaults that just work without file deployment, or when consumers need to override library settings via standard appsettings.json patterns. Covers three-tier configuration precedence: embedded JSON defaults compiled into the assembly via EmbeddedResource, consumer appsettings.json overrides, and hardcoded fallback values, plus the EmbeddedConfigLoader and LogicalName conventions. Domain: .NET Library Design, Configuration. Level: Intermediate. Tags: configuration, embedded-resource, nuget, library-defaults, appsettings."

Embedded Resource Configuration

Problem

A .NET class library distributed via NuGet needs default configuration values that:

• Are guaranteed to be available at runtime without file deployment
• Can be overridden by consuming applications
• Don't rely on the consuming app bundling or copying config files

Traditional Content file deployment is fragile — NuGet content files may not copy correctly across TFMs, may collide with consumer files, or may be silently ignored.

Solution: 3-Tier Configuration Precedence

Design a layered configuration system with three tiers (highest to lowest priority):

1. Consumer's appsettings.json — consuming app overrides any value
2. Library's embedded resource defaults — compiled into the assembly via <EmbeddedResource>
3. Hardcoded fallback defaults — last-resort values in code

Why Embedded Resources

• Guaranteed availability: no file paths, no deployment; the config lives inside the DLL
• No consumer friction: works out-of-the-box, no setup required
• Override-friendly: consumers only need to add matching keys to their own appsettings.json

Implementation

1. Create the defaults file

MyLibrary/
├── Settings/
│   └── library-defaults.json    ← human-readable source, embedded at build time

{
  "LibrarySettings": {
    "DefaultLanguage": "en-US",
    "LogFilePath": "MyLibrary-Log.txt",
    "MaxRetryCount": 3,
    "CacheTimeoutMinutes": 30
  }
}

2. Mark as embedded resource in .csproj

<ItemGroup>
  <EmbeddedResource Include="Settings\library-defaults.json">
    <LogicalName>MyLibrary.Settings.library-defaults.json</LogicalName>
  </EmbeddedResource>
</ItemGroup>

Key distinction: Use <EmbeddedResource> (compiled into assembly) — NOT <Content> (deployed alongside). SQL scripts, migration files, and other consumer-deployed assets should remain as <Content>.

Without <LogicalName>: The resource name is auto-generated as {DefaultNamespace}.{FolderPath}.{FileName} with dots replacing path separators. Example: project Acme.DataAccess, file at Settings/defaults.json → Acme.DataAccess.Settings.defaults.json. Use <LogicalName> to make the name explicit and refactor-safe.

3. Loader — separate internal class (SRP)

The loader mechanism is separate from the settings accessor. Each has one reason to change.

internal static class EmbeddedConfigLoader
{
    private const string ResourceName = "MyLibrary.Settings.library-defaults.json";

    internal static IConfiguration Load()
    {
        var builder = new ConfigurationBuilder();

        var stream = typeof(EmbeddedConfigLoader).Assembly
            .GetManifestResourceStream(ResourceName);

        if (stream is not null)
        {
            builder.AddJsonStream(stream);
        }

        return builder.Build();
    }
}

4. Settings accessor — 3-tier fallback

internal static class LibrarySettings
{
    private static readonly IConfiguration _libraryConfig = EmbeddedConfigLoader.Load();

    public static string DefaultLanguage =>
        ConsumerConfigHelper.GetValue("LibrarySettings:DefaultLanguage")      // Tier 1
        ?? _libraryConfig["LibrarySettings:DefaultLanguage"]                   // Tier 2
        ?? "en-US";                                                            // Tier 3

    public static int MaxRetryCount =>
        ConsumerConfigHelper.GetValue<int?>("LibrarySettings:MaxRetryCount")  // Tier 1
        ?? _libraryConfig.GetValue<int?>("LibrarySettings:MaxRetryCount")     // Tier 2
        ?? 3;                                                                  // Tier 3
}

5. Consumer overrides (their appsettings.json)

{
  "LibrarySettings": {
    "DefaultLanguage": "es-ES"
  }
}

The consumer only overrides what they need. Everything else falls through to library defaults.

When to Use

• Distributing a .NET library via NuGet that has configurable behavior
• You want zero-configuration defaults that just work
• Your library must support multiple TFMs without content-file deployment issues
• You want consumers to override settings via standard appsettings.json patterns

When NOT to Use

• Application-level configuration (just use appsettings.json directly)
• Files that consumers must see/edit at deployment (SQL scripts, templates) — use <Content> instead
• Simple constants that never change — just use const or static readonly

Gotchas

1. Stream is read-once: AddJsonStream reads the stream during Build(). Don't try to reuse the stream.
2. Logical name must match: GetManifestResourceStream uses the logical name, not the file path.
3. TFM-specific content files conflict: If your package has any TFM-specific content files (any/net9.0/), the any/any/ fallback is ignored. Keep embedded resources and content files on separate strategies.
4. No hot-reload: Embedded defaults are baked at compile time. That's a feature, not a bug.

Verification

// Confirm the resource is embedded and named correctly
var names = typeof(EmbeddedConfigLoader).Assembly.GetManifestResourceNames();
Debug.Assert(names.Contains("MyLibrary.Settings.library-defaults.json"),
    "Embedded resource not found — check <LogicalName> or auto-naming convention.");

Related Skills

• Gen Options Class (options validated at startup)
• Multi-TFM NuGet Packaging (embedded resources in multi-TFM packages)
• Internal-by-Default Library Design (what to expose in the package)