docs: appsettings.json philosophy section#6
Merged
StuartMeeks merged 1 commit intomainfrom May 3, 2026
Merged
Conversation
Adds a "Working with appsettings.json across updates" section to
the README between the user-files section and the configuration
table. Covers:
- The .NET layering recommendation (preserve appsettings.{Env}.json,
let appsettings.json update with each release; IConfiguration
overlays them at runtime — no file-on-disk merge needed).
- Migration tip for consumers whose users currently put connection
strings in the base appsettings.json.
- The onConflict resolver as an escape hatch for consumers who really
do need to merge two JSON files at install time, with caveats:
no diff base means user-modified vs inherited can't be distinguished,
JSON round-trips drop comments, and the package deliberately doesn't
ship a built-in merger.
Docs-only — no version bump, no behaviour change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only. New "Working with
appsettings.jsonacross updates" README section between "Preserving user files across updates" and the configuration table.Covers:
appsettings.{Environment}.json, letappsettings.jsonupdate with each release;IConfigurationoverlays them at runtime so no file-on-disk merge is needed.appsettings.json— one-time move into a layered override file, zero ongoing complexity.onConflictresolver can be used to perform a surgical JSON merge in-place. Acknowledges the caveats: no base version means user-modified vs inherited can't be distinguished, JSON round-trips drop comments, and the package deliberately doesn't ship a built-in merger.No version bump, no code changes, no behaviour change.
Test plan
🤖 Generated with Claude Code