Upgrade Guide

This guide explains how to upgrade an EasyAdminBlazor project to a new version. Read the Changelog first and check for breaking changes.

1. Before Upgrading

  • Back up the database: upgrades may involve schema changes
  • Validate on a test environment: do not upgrade the production database directly
  • Read the changelog to confirm dependency upgrades, security fixes, and configuration changes in this release

2. Upgrade NuGet Packages

Check the currently referenced versions:

dotnet list package

Upgrade the core package and extensions:

# Upgrade the core package to the latest
dotnet add package EasyAdminBlazor

# Upgrade the extensions you use
dotnet add package EasyAdminBlazor.Mail
dotnet add package EasyAdminBlazor.Redis
dotnet add package EasyAdminBlazor.Scheduler
# ...install/upgrade as needed

You can also upgrade from the "Manage NuGet Packages" UI in Visual Studio. It is recommended to keep the core and extension packages at the same version.

3. Update the Template Package

The template package is updated separately; re-running the install command overwrites it with the latest version:

dotnet new install EasyAdminBlazor.Templates

Existing projects are not affected; new projects will use the latest template.

4. Verification After Upgrading

  1. Clean the bin and obj directories (stale build artifacts can interfere)
  2. Rebuild: dotnet build
  3. Start on a development environment with UseAutoSyncStructure(true) and confirm new tables/columns are synced
  4. Check the changelog for breaking changes (renamed settings, API changes, changed defaults)
  5. Walk through the key features: login, user/role/menu, operation logs, file upload, code generator
  6. Deploy to production only after verification (see Deployment)

5. Common Notes

  • Database schema: upgrades may add tables or columns. After development sync passes, sync on production (or follow the deployment guide to disable auto-sync and run manual change scripts)
  • Cache: restart the process after upgrading; if Redis is used, clean stale keys when necessary
  • AesKey / AdminRouteSecret: unless the changelog explicitly requires it, do not change them during upgrade; whether existing sessions are invalidated depends on the changelog
  • Template behind the core package: EasyAdminBlazor.Templates and EasyAdminBlazor may not be in sync; upgrade the core package to the latest after creating a project from the template
  • Multiple instances: roll upgrades instance by instance to avoid a full service interruption