Add automated upgrade assistant for appsettings.json migrations #463

Copilot · 2025-12-21T20:46:36Z

Upgrade Assistant for appsettings.json ✅

Successfully implemented an automated upgrade assistant tool for migrating appsettings.json files between major versions of the blog application.

🎯 Recent Changes

✅ Documentation Updates

Added comprehensive chapter about Automated Configuration Migration in docs/Migrations/Readme.md
Added "Automated Configuration Migration" as a feature in main Readme.md
Clear distinction between automated migration (v12+) and manual migration (pre-v12)

✅ Added projects to solution file

Both LinkDotNet.Blog.UpgradeAssistant and LinkDotNet.Blog.UpgradeAssistant.Tests now in LinkDotNet.Blog.sln
Properly nested under tools and tests folders

✅ Removed unnecessary inline comments

Replaced comments with descriptive method names
DetermineCurrentVersionFromMigrations() instead of comment about determining version
IsVersionControlledAppsettingsFile() instead of comment about skipping files
ParseCommandLineArguments() extracted as named method
Kept XML documentation comments (///) which are standard practice

📊 Implementation Summary

Migration Tool (tools/LinkDotNet.Blog.UpgradeAssistant)

CLI with -p/--path, -d/--dry-run, -b/--backup-dir options
Uses Spectre.Console for beautiful output
Detects current version via ConfigVersion field
Only applies 11.0→12.0 migration (adds ShowBuildInformation)
Creates timestamped backups before modifications
Skips version-controlled appsettings.json

Documentation (docs/Migrations/)

Comprehensive user guide in UpgradeAssistant.md
Updated Readme.md with automated migration chapter for v12+
Main Readme.md feature list includes automated migration capability

Tests: 9/9 passing ✅

Migration11To12Tests: Validates the migration logic
MigrationManagerTests: End-to-end scenarios including skipping appsettings.json

🚀 Usage Example

# Preview changes
dotnet run --project tools/LinkDotNet.Blog.UpgradeAssistant -- --dry-run

# Migrate configuration files (skips appsettings.json)
dotnet run --project tools/LinkDotNet.Blog.UpgradeAssistant

# Migrate specific file
dotnet run --project tools/LinkDotNet.Blog.UpgradeAssistant -- --path appsettings.Production.json

All feedback addressed!

Original prompt

This section details on the original issue you should resolve

<issue_title>Provide an upgrade assistant for application.json</issue_title>
<issue_description>While the MIGRATION.md is vital, we need an automatic way of transforming the appsettings.json.

Rationale

Major version can have new entries, that might be mandatory. Therefore we need a way of telling folks that there is something new.

Another usecase is that we move entries from a section inside the appsettings.json (more likely the appsettings.dev.json and friends as the appsettings.json itself is version-controlled) to another one. The current way of dealing with it, is via the MIGRATION.md and folks have to do it manually.

Solution

Ideally, we have a companion tool (inside the tools) folder that does that. For example Nx or Angular allow also automatic migrations of files. nx migrate - we would have a similar tool.
If completely new entries were made, we should inform people what they have to do, maybe with a link to the docs. But that should be part of the migration.

Technical Requirements

Documentation is a must. We have to guide folks through the process under the docs/ folder

We need a new marker inside the appsettings.*.json to set the current version. Having a log of entries might not be ideal and just adds bloat.

The console should have colorful output to make warnings or errors obvious. Especially if we have new entries where people have to provide new values.

Backup all files before, so we can restore them in the worst case</issue_description>

Comments on the Issue (you are @copilot in this section)
@linkdotnet Yeah - just like `dotnet ef migrations` does work. I would store the current version inside the `application.json` itself - no need for extra storage. @linkdotnet It is needed in case of major breaking changes - for example some time ago we moved Auth stuff into a separate section in the config. Sure tha can be done manually, but like the migrations in the database, it could potentially be automised to reduce the error surface.
I would like that folks have an easy time upgrading without headache.</comment_new>

Fixes Provide an upgrade assistant for application.json #372

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

linkdotnet · 2025-12-22T18:21:06Z

tools/LinkDotNet.Blog.UpgradeAssistant/Migrations/Migration_8_To_9.cs

This isn't needed as the current release is version 11.

Removed Migration_8_To_9 and Migration_9_To_11 since users are upgrading from version 11.0. Only the 11.0→12.0 migration is needed now. (2fe1a4d)

linkdotnet · 2025-12-22T18:21:10Z

tools/LinkDotNet.Blog.UpgradeAssistant/Migrations/Migration_9_To_11.cs

This isn't needed as the current release is version 11.

Removed Migration_8_To_9 and Migration_9_To_11. Only keeping Migration_11_To_12 for the current upgrade path. (2fe1a4d)

linkdotnet · 2025-12-22T18:22:49Z

tools/LinkDotNet.Blog.UpgradeAssistant/ConsoleOutput.cs

@@ -0,0 +1,48 @@
+namespace LinkDotNet.Blog.UpgradeAssistant;
+
+public static class ConsoleOutput


You can also use Spectre.Console instead of your own solution. Which may allow automation later on

Replaced custom ConsoleOutput with Spectre.Console. Now using AnsiConsole.MarkupLine for colorful output with better formatting. (2fe1a4d)

linkdotnet · 2025-12-22T18:24:18Z

tools/LinkDotNet.Blog.UpgradeAssistant/MigrationManager.cs

+
+public sealed class MigrationManager
+{
+    private const string CurrentVersion = "12.0";


We should resolve this from the current highest ToVersion of IMigration

CurrentVersion is now dynamically resolved from the highest ToVersion in the migrations list. Makes it easier to extend in the future. (2fe1a4d)

linkdotnet · 2025-12-22T18:24:45Z

tools/LinkDotNet.Blog.UpgradeAssistant/Program.cs

@@ -0,0 +1,119 @@
+using CommandLine;


Check if Spectre.Console might be also a solution so we only have one external dependency

Replaced CommandLineParser with Spectre.Console. Now using simple argument parsing with Spectre.Console for beautiful help display with FigletText and formatted tables. (2fe1a4d)

linkdotnet · 2025-12-22T18:26:01Z

docs/Migrations/UpgradeAssistant.md

+```
+
+This will:
+1. Find all `appsettings*.json` files in the current directory


Technically the appsettings.json should have no need of migration, as this should be from the repository. Make also sure that is the case in the Migrationmanager itself

Added check to skip version-controlled appsettings.json file. The tool now only migrates environment-specific files like appsettings.Development.json, appsettings.Production.json, etc. Also updated GetAppsettingsFiles() to filter out appsettings.json. (2fe1a4d)

linkdotnet · 2025-12-22T18:42:46Z

@copilot Add the two projects to the root level solution file (LinkDotNet.Blog.sln).
Also try to avoid comments in the newly generated as much as possible - try to use either good naming for variables or methods.

Copilot · 2025-12-22T18:48:19Z

@copilot Add the two projects to the root level solution file (LinkDotNet.Blog.sln).
Also try to avoid comments in the newly generated as much as possible - try to use either good naming for variables...

Added both LinkDotNet.Blog.UpgradeAssistant and LinkDotNet.Blog.UpgradeAssistant.Tests to LinkDotNet.Blog.sln. Removed inline comments and replaced them with descriptive method names like DetermineCurrentVersionFromMigrations(), IsVersionControlledAppsettingsFile(), and ParseCommandLineArguments(). Kept XML documentation comments (///) as they're standard practice. (28d3f37)

linkdotnet · 2025-12-22T18:56:28Z

@copilot Very good.
In "docs/Migrations/Readme.md" also add a chapter that from version 12 onwards we have an automated updated. Also add the feature of automatic migration as a feature to the README.md

Copilot · 2025-12-22T18:59:39Z

@copilot Very good.
In "docs/Migrations/Readme.md" also add a chapter that from version 12 onwards we have an automated updated. Also add the feature of automatic migration as a feature to the README....

Added comprehensive documentation about the Automated Upgrade Assistant:

New chapter in docs/Migrations/Readme.md explaining automated migration from version 12 onwards with usage examples
Added "Automated Configuration Migration" feature to main Readme.md feature list
Clear distinction between automated migration (v12+) and manual migration (pre-v12) (53cc942)

- Created LinkDotNet.Blog.UpgradeAssistant console tool in tools folder - Implemented migration framework with version tracking - Added migrations for 8.0→9.0, 9.0→11.0, and 11.0→12.0 - Colorful console output using ANSI colors - Automatic backup functionality with timestamps - Dry-run mode to preview changes - Comprehensive documentation in docs/Migrations/UpgradeAssistant.md - Updated MIGRATION.md to reference the new tool - Added ConfigVersion field to appsettings.json - Added backups/ to .gitignore Co-authored-by: linkdotnet <[email protected]>

- Created test project LinkDotNet.Blog.UpgradeAssistant.Tests - Added comprehensive tests for Migration8To9, Migration9To11, Migration11To12 - Added tests for MigrationManager including end-to-end scenarios - All 17 tests passing Co-authored-by: linkdotnet <[email protected]>

- Remove OutputType from test project csproj - Fix document disposal pattern in MigrationManager - Use separate variable for each migration document Co-authored-by: linkdotnet <[email protected]>

…p appsettings.json - Replace CommandLineParser with Spectre.Console for CLI and colorful output - Remove Migration_8_To_9 and Migration_9_To_11 (current version is 11.0) - Make CurrentVersion dynamic based on highest ToVersion from migrations - Skip version-controlled appsettings.json file during migration - Update tests to reflect changes (9 tests passing) - Enhanced help and version output with Figlet text and tables Co-authored-by: linkdotnet <[email protected]>

- Added LinkDotNet.Blog.UpgradeAssistant and LinkDotNet.Blog.UpgradeAssistant.Tests to LinkDotNet.Blog.sln - Removed inline comments from code, using descriptive method names instead - Extracted ParseCommandLineArguments method for better code organization - Created DetermineCurrentVersionFromMigrations and IsVersionControlledAppsettingsFile methods - Kept only XML documentation comments (///) which are standard - All tests passing (9/9) Co-authored-by: linkdotnet <[email protected]>

- Added chapter about Automated Configuration Migration (Version 12+) in docs/Migrations/Readme.md - Documented Upgrade Assistant features, usage examples, and benefits - Added "Automated Configuration Migration" as a feature in main Readme.md - Provided clear migration path: automated for v12+, manual for pre-v12 Co-authored-by: linkdotnet <[email protected]>

Arnab-Developer

Nice work.

I have added a suggestion which you can consider in future if needed.

Arnab-Developer · 2025-12-23T02:45:04Z

tools/LinkDotNet.Blog.UpgradeAssistant/Program.cs

+    AnsiConsole.MarkupLine($"[dim]Target Blog Version: 12.0[/]");
+}
+
+static void ParseCommandLineArguments(string[] args, ref string targetPath, ref string backupDirectory, ref bool dryRun, ref bool showHelp, ref bool showVersion)


You can use something like timewarp-nuru to parse command line arguments more easily.

Will use CommandLineParser as this is already used in CriticalCSS project

But thanks for the hint - I was missing that.
Much appreciated @Arnab-Developer

Copilot AI assigned Copilot and linkdotnet Dec 21, 2025

Copilot started work on behalf of linkdotnet December 21, 2025 20:47 View session

Copilot AI changed the title ~~[WIP] Provide upgrade assistant for application.json~~ Add automated upgrade assistant for appsettings.json migrations Dec 21, 2025

Copilot AI requested a review from linkdotnet December 21, 2025 21:07

Copilot finished work on behalf of linkdotnet December 21, 2025 21:07

linkdotnet requested changes Dec 22, 2025

View reviewed changes

Copilot started work on behalf of linkdotnet December 22, 2025 18:29 View session

Copilot AI requested a review from linkdotnet December 22, 2025 18:37

Copilot finished work on behalf of linkdotnet December 22, 2025 18:37

Copilot started work on behalf of linkdotnet December 22, 2025 18:43 View session

Copilot finished work on behalf of linkdotnet December 22, 2025 18:49

Copilot started work on behalf of linkdotnet December 22, 2025 18:57 View session

Copilot finished work on behalf of linkdotnet December 22, 2025 19:00

Copilot AI and others added 8 commits December 22, 2025 20:06

Address code review feedback

49c99fe

- Remove OutputType from test project csproj - Fix document disposal pattern in MigrationManager - Use separate variable for each migration document Co-authored-by: linkdotnet <[email protected]>

docs: Add clarification and cleanup

5520da7

docs: Add readme

5e48cf1

linkdotnet force-pushed the copilot/add-upgrade-assistant-for-json branch from 14f358f to 5e48cf1 Compare December 22, 2025 19:06

fix: Build errors

bb05a14

linkdotnet marked this pull request as ready for review December 22, 2025 19:15

linkdotnet merged commit bb1a92b into master Dec 22, 2025
3 checks passed

linkdotnet deleted the copilot/add-upgrade-assistant-for-json branch December 22, 2025 19:15

Arnab-Developer reviewed Dec 23, 2025

View reviewed changes

		@@ -0,0 +1,48 @@
		namespace LinkDotNet.Blog.UpgradeAssistant;

		public static class ConsoleOutput

Uh oh!

Add automated upgrade assistant for appsettings.json migrations #463

Add automated upgrade assistant for appsettings.json migrations #463

Uh oh!

Conversation

Copilot AI commented Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Upgrade Assistant for appsettings.json ✅

🎯 Recent Changes

📊 Implementation Summary

🚀 Usage Example

Rationale

Solution

Technical Requirements

Comments on the Issue (you are @copilot in this section)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

linkdotnet commented Dec 22, 2025

Uh oh!

Copilot AI commented Dec 22, 2025

Uh oh!

linkdotnet commented Dec 22, 2025

Uh oh!

Copilot AI commented Dec 22, 2025

Uh oh!

Uh oh!

Arnab-Developer left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Dec 21, 2025 •

edited

Loading

Arnab-Developer left a comment •

edited

Loading