Table of Contents

🧭 Upgrade OpenSettings v1.2 ➡ v2.0

⚠️ This page outlines the steps required to upgrade from version 1.2.* to 2.0.* of OpenSettings. Contains Breaking change v2 switches primary keys to GUID and restructures several tables. You must recreate the database on v2.

Why this is breaking

  • v1 used INT IDENTITY keys; v2 uses GUID keys.
  • Database server cannot flip IDENTITY to GUID via a simple ALTER.
  • To keep v2 clean and reliable, we require a fresh schema.

📦 Affected Packages

Ensure you update the following NuGet packages:

  • OpenSettings → 2.0.*
  • OpenSettings.AspNetCore → 2.0.*
  • OpenSettings.AspNetCore.Spa → 2.0.*

You can update via CLI:

dotnet add package OpenSettings --version 2.0.*
dotnet add package OpenSettings.AspNetCore --version 2.0.*
dotnet add package OpenSettings.AspNetCore.Spa --version 2.0.*

Need to keep data? (Manual Export/Import)

There is no supported automatic in-place migration from v1.2 to v2. If you must keep data:

  1. Export what you need from v1.2.
  2. Delete the Data folder in your project and generate fresh initial migrations.
  3. Update your connection string with a new database name.
  4. Run the application and schema will be created automatically.

🎢 Generate Migration

If your application acts as a provider and persists data using the included OpenSettingsDbContext, you'll need to apply a database migration

Run the following command from your executable project directory:

dotnet ef migrations add OpenSettingsDbMigration_v2_0 -c OpenSettingsDbContext -o Data/Migrations/OpenSettings/OpenSettingsDb

✅ Verify: After executing the command, you should see:

  • ..._OpenSettingsDbMigration_v2.0.cs
  • ..._OpenSettingsDbMigration_v2.0.Designer.cs

Inside:

Data/Migrations/OpenSettings/OpenSettingsDb/
Important

For EF tools setup and guidance, refer to our Migration Guide.

🛠 Troubleshooting

If you run into any errors during the upgrade process, please check out the Troubleshooting page for common issues and solutions.

✨ OpenSettings makes settings management simple and efficient! 🚀

Edit this page