Upgrade Guide
Upgrading 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
- Clean the
binandobjdirectories (stale build artifacts can interfere) - Rebuild:
dotnet build - Start on a development environment with
UseAutoSyncStructure(true)and confirm new tables/columns are synced - Check the changelog for breaking changes (renamed settings, API changes, changed defaults)
- Walk through the key features: login, user/role/menu, operation logs, file upload, code generator
- 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
- v2.3.2 login ticket upgrade: tickets move to v2, so legacy v1 tickets are treated as signed-out and every user must log in once after upgrading (AesKey now also derives the Data Protection application name)
- v2.3.2 multi-tenant host whitelist: when multi-tenant is enabled, configure
Security:AllowedHosts(admin domains); leaving it empty keeps the previous unrestricted behaviour - v2.3.2 operation log gains two columns:
SysOperationLogaddsEntityType,EntityKeyand theidx_operationlog_entityindex (used by the change-history view). WithUseAutoSyncStructure(true)they are created automatically; when auto-sync is disabled in production, run the equivalentALTER TABLE ... ADD COLUMN ...andCREATE INDEX ...manually - v2.6.0 the controlled download of private files has been removed (breaking change): the
/api/files/{id}endpoint and theFileService.OpenPrivateFileAsyncmethod are gone; files are served from their static URL. If your own code references any of these members, switch toSysFile.AccessUrl(the access address on the file record). None of the framework's built-in extension packages reference them -- every one of them has been checked. TheSysFile.IsPublicfield stays on the entity but no longer takes part in any decision -- it is kept so that the schema of existing databases stays as it is and upgrading projects need no database change - v2.6.0 approval record gains one column:
SysApprovalRecordaddsTotalLevels(INT NULL, the level count of the flow at submit time). A running bill is governed by that value, so changing the flow configuration afterwards (adding or removing a level) no longer changes the number of nodes of a bill that is already in flight -- such bills no longer stay stuck in "under approval". The framework runsCodeFirst.SyncStructure<SysApprovalRecord>()on startup and adds the column automatically; when auto-sync is disabled in production, runALTER TABLE sys_approval_record ADD COLUMN TotalLevels INT NULL;manually. Legacy rows have a null value and fall back to "snapshot level count, then flow configuration", which behaves exactly as before the upgrade - v2.6.0 image pixel limit: a new
FileSettings:MaxImagePixelssetting (default 40 million pixels, roughly a 160MB decode buffer) blocks crafted images that are tiny on disk but eat gigabytes once decoded. The trade-off is that camera originals above 48 million pixels are rejected; raise the value when needed (set it to0to disable the limit) - v2.6.0 large column flag properties: if you use the "large column flag" (
Is{Column}/{Column}Length), the flag property must carry[Column(IsIgnore = true)]-- otherwise it is treated as a real column and written to the database, overwriting a real column of the same name. Check the flag properties you added earlier for this attribute - Template behind the core package:
EasyAdminBlazor.TemplatesandEasyAdminBlazormay 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