JsonMigrations 3.0.0

JsonMigrations

A .NET library for incrementally migrating JSON files (such as appsettings.json) without needing to overwrite them entirely. This is useful when JSON files contain installation-specific values that cannot be known in advance.

Migrations are plain C# classes that run in a defined order. After each run the library records which migration was last applied, so only newer migrations execute on subsequent runs.

Getting Started

Installation

Install via NuGet:

dotnet add package JsonMigrations

Requirements: .NET 6.0 or later

Quick Example

using System.Text.Encodings.Web;
using System.Text.Json;
using JsonMigrations;
using JsonMigrations.Enums;

// 1. Configure options (optional — defaults shown below)
var options = new JsonMigratorOptions()
{
    InvalidJsonAction = InvalidJsonAction.Throw,
    FileNotExistAction = FileAction.Throw,
    MigrationFaultAction = MigrationAction.Throw,
    JsonSerializerOptions = new JsonSerializerOptions()
    {
        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
        WriteIndented = true,
    }
};
JsonMigrator.SetOptions(options);

// 2. Register migrations by assembly or namespace
JsonMigrator.AddJsonMigrations(typeof(MyFirstMigration).Assembly);
// or: JsonMigrator.AddJsonMigrations(typeof(MyFirstMigration).Namespace!);

// 3. Run migrations on one or more files
JsonMigrator.Migrate("AppsettingsProgram", "appsettings.json", "appsettings.development.json");

A complete working example is available in the Example project.

Writing Migrations

Create a class that implements IJsonMigration:

using System.Text.Json;
using System.Text.Json.Nodes;
using JsonMigrations.Interfaces;

public class MyFirstMigration : IJsonMigration
{
    public int Order => 0;
    public string MigrationKey => "AppsettingsProgram";

    public void Up(JsonObject jsonObject, JsonSerializerOptions options)
    {
        jsonObject.TryAdd("ConnectionString", "Server=localhost;Database=mydb");
    }
}

After running, a "Migration" property is written to each JSON file with the class name of the last applied migration. On subsequent runs, only migrations with a higher Order are executed.

Configuration

JsonMigratorOptions

Enum Values

MigrationAction — behaviour on migration failure: | Value | Description | |---|---| | Ignore | Skips the failed migration and continues with the next one. | | Throw | Throws the exception. | | Restore | Restores the JSON file to its state before the migration run started. |

InvalidJsonAction — behaviour on invalid JSON: | Value | Description | |---|---| | None | Skips the file. | | Throw | Throws an InvalidJsonException. |

FileAction — behaviour when a file does not exist: | Value | Description | |---|---| | None | Skips the file. | | Create | Creates the file with an empty JSON object ({}). | | Throw | Throws an exception. |

API Reference

// Configure options (call before Migrate)
JsonMigrator.SetOptions(JsonMigratorOptions options);

// Register migrations from one or more assemblies
JsonMigrator.AddJsonMigrations(params Assembly[] assemblies);

// Register migrations from one or more namespaces
JsonMigrator.AddJsonMigrations(params string[] namespaces);

// Run pending migrations for a key against one or more files
JsonMigrator.Migrate(string migrationKey, params string[] filePaths);

Contributing

See CONTRIBUTING.md for guidelines on how to contribute, including commit conventions and build instructions.

License

See LICENSE.txt for details.