Add automated upgrade assistant for appsettings.json migrations

[Copilot]

Major version upgrades require configuration changes (new mandatory fields, restructured sections). Users currently must manually apply migrations from MIGRATION.md, which is error-prone.

Implementation

Migration Tool (tools/LinkDotNet.Blog.UpgradeAssistant)

• CLI with --path, --dry-run, --backup-dir options
• Detects current version via new ConfigVersion field in appsettings.json
• Chains migrations sequentially (8.0→9.0→11.0→12.0)
• Creates timestamped backups before modifications
• ANSI-colored output for warnings/errors

Migration Framework

• IMigration interface for version transitions
• Three migrations implemented:
  • 8.0→9.0: Restructures KofiToken/GithubSponsorName/PatreonName into SupportMe section, adds ShowSimilarPosts
  • 9.0→11.0: Adds UseMultiAuthorMode
  • 11.0→12.0: Adds ShowBuildInformation
• MigrationManager orchestrates sequential application

Documentation

• docs/Migrations/UpgradeAssistant.md: User guide
• MIGRATION.md: Updated with tool reference
• Tool README with examples

Tests

• 17 unit tests covering all migrations and manager
• Validates transformations, idempotency, error handling

Usage

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

# Migrate all appsettings*.json in current directory
dotnet run --project tools/LinkDotNet.Blog.UpgradeAssistant

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

Example Transform

Before (v8.0):

{
  "KofiToken": "abc123",
  "GithubSponsorName": "user"
}

After (v12.0):

{
  "ConfigVersion": "12.0",
  "SupportMe": {
    "KofiToken": "abc123",
    "GithubSponsorName": "user",
    "ShowUnderBlogPost": true,
    "ShowUnderIntroduction": false,
    "ShowInFooter": false,
    "ShowSupportMePage": false,
    "SupportMePageDescription": ""
  },
  "ShowSimilarPosts": false,
  "UseMultiAuthorMode": false,
  "ShowBuildInformation": true
}

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• http://crl3.digicert.com:443/DigiCertCSRSA4096RootG5.crl
  • Triggering command: /usr/bin/dotnet dotnet restore (http block)
• http://crl3.digicert.com:443/NETFoundationProjectsCodeSigningCA2.crl
  • Triggering command: /usr/bin/dotnet dotnet restore (http block)
• http://crl3.digicert.com:443/sha2-assured-cs-g1.crl
  • Triggering command: /usr/bin/dotnet dotnet restore (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

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.