Application Online Upgrade · User Guide
The admin footer shows App v1.0.0 · Check for updates. An administrator clicks Check for updates → Upgrade now; the system stops the service, backs up, replaces the files, starts it again and runs a health check. A failed step is rolled back, and users do not have to log in again.
Upgrade packages are per-version deltas: 1.0 → 1.1 → 1.2 are applied one by one, so a client that lags several versions still upgrades automatically (no manual version skipping).
During the upgrade:
- Clicking "Upgrade now" shows a full-screen overlay with the fixed title "Upgrading the application, please wait..." (stage texts such as "stopping the application" are no longer shown).
- Once the health check reports the target version, the page shows "Upgrade completed. Current version: x.y.z" and reloads itself after a 3-second countdown. Other administrators' pages reload the same way, and users do not have to log in again.
- The confirmation dialog shows the current number of online users (their pages are interrupted briefly).
- If a step fails, only that step is rolled back and the previous version is started again.
The upgrade lives in the extension: without
EasyAdminBlazor.Upgradethere is no "Check for updates" entry in the admin UI, no/healthendpoint, and no upgrade package is produced on publish. Existing projects behave exactly as before.
Localization: the footer, the update dialog, the upgrade overlay and the completed/rolled-back notices follow the current language; the extension ships Chinese and English (
Locales/zh.json,en.json).
1. Install the extension
Option A: NuGet (recommended)
<ItemGroup>
<PackageReference Include="EasyAdminBlazor.Upgrade" Version="2.4.0" />
</ItemGroup>
One line is enough: the extension, the upgrade engine and the publish hook all live in the package — no Import to write and no project to add to the solution.
Option B: source reference (when you work against the framework repository)
<ItemGroup>
<ProjectReference Include="..\..\yyq\EasyAdminBlazor\Extensions\EasyAdminBlazor.Upgrade\EasyAdminBlazor.Upgrade.Extension.csproj" />
</ItemGroup>
<!-- put this before </Project> -->
<Import Project="..\..\yyq\EasyAdminBlazor\Extensions\EasyAdminBlazor.Upgrade\build\EasyAdminBlazor.Upgrade.targets" />
A source reference also needs the three projects below added to the solution, otherwise Visual Studio reports "project information not found" (command-line dotnet build/publish restores them automatically):
Extensions/EasyAdminBlazor.Upgrade/EasyAdminBlazor.Upgrade.Extension.csproj extension
Extensions/EasyAdminBlazor.Upgrade/Engine/EasyAdminBlazor.Upgrade.csproj engine
Extensions/EasyAdminBlazor.Upgrade/Updater/EasyAdminBlazor.Updater.csproj updater + packager
Both options behave the same: publishing puts the updater into updater\ and a Release build produces the upgrade package.
2. Enable the upgrade
Program.cs:
var builder = WebApplication.CreateBuilder(args);
// required for the Windows service hosting model; not needed for console / BT Panel
builder.Host.UseWindowsService();
builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions
{
// …keep your existing settings…
})
// …your existing extension chain…
.AddEasyAdminBlazorUpgrade(); // enables the upgrade feature (footer entry + /health)
/healthis mounted by the extension itself — you never map it yourself. Keep the host'sapp.UseEasyAdminBlazor<App>();(it maps the notification SignalR hub and adds the framework and extension assemblies to the Razor component routes).
The Windows service (behind an IIS reverse proxy) must also turn off Blazor's WebSocket compression:
Since .NET 10, Interactive Server components enable WebSocket compression (
permessage-deflate) by default, and the IIS ARR reverse proxy does not handle compressed frames correctly — the handshake succeeds but the connection is dropped immediately, the browser reportsWebSocket closed with status code 1006, and the admin page keeps spinning or stays blank. That also breaks the upgrade overlay, the countdown and the auto reload, because they all rely on that long-lived connection. When you deploy as a Windows service behind IIS, replaceapp.UseEasyAdminBlazor<App>();inProgram.cswith the options overload:app.UseEasyAdminBlazor<App>(options => { options.DisableWebSocketCompression = true; });The alternative is to strip the browser's
Sec-WebSocket-Extensionsrequest header at the IIS side (add<set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" />to the rewrite rule and allow that variable in the URL Rewrite "Allowed server variables" list) — but that is a site-wide setting that affects every other app on the site, so prefer the code switch above. Console / BT Panel self-hosting does not go through IIS ARR and needs no such configuration.
appsettings.json:
Windows service:
"Urls": "http://0.0.0.0:5099",
"Upgrade": {
"Enabled": true,
"Source": "Local",
"ReleasesPath": "updates",
"RestartMode": "WindowsService",
"ServiceName": "your-service-name",
"HealthCheckUrl": "http://127.0.0.1:5099"
}
Linux (BT Panel):
"Urls": "http://127.0.0.1:5018",
"Upgrade": {
"Enabled": true,
"Source": "Local",
"ReleasesPath": "updates",
"RestartMode": "Direct",
"HealthCheckUrl": "http://127.0.0.1:5018"
}
HealthCheckUrlmust be reachable from the server itself and must use the same port the app listens on. To let customers upgrade from the published site, setSourcetoUrland put the release index inReleaseIndexUrl(https://your-release-host/releases/index.json); HTTPS is required, add"AllowInsecureHttp": truefor plain HTTP on an internal network.RestartModealso acceptsSystemd(the updater stops and starts a systemd service) andExternal(the stop/start is left to an external process manager).
3. Produce the package
Only one place holds the version: <Version> in the host csproj.
dotnet publish -c Release -o publish
Publishing from Visual Studio (Release configuration) works as well. After the publish:
publish\
├── application files / wwwroot / updater\ ← updater\ is generated, do not delete it
└── updates\
├── index.json
├── v1.0.0\ update.zip + release.json + files.json ← the previous version (baseline)
└── v1.1.0\ update.zip + release.json + files.json ← this increment (~1–2 MB)
Publish repeatedly into the same output directory — that is what keeps the previous baseline around and makes the package an incremental one. For release notes, put a release-notes.txt in the project root, one note per line (# starts a comment).
4. Windows deployment (IIS reverse proxy + Kestrel service)
Environment: install the .NET 10 Runtime (plus the ASP.NET Core Hosting Bundle when IIS support is needed) and copy the contents of publish/ into the application directory (e.g. D:\app\EasyAdminBlazor).
Why is online upgrade only available as a "Windows service" on Windows?
An online upgrade needs an external process that stops the app, replaces the files and starts it again. With IIS in-process hosting the app runs inside
w3wp.exe(the application pool): recycling or stopping the pool also kills the child processes it started (the updater), and the updater is not allowed to stop and restart the whole pool; on top of that one pool may host several sites, so the stop/start granularity does not line up. The framework therefore disables the upgrade entry when it detects in-process IIS hosting (no "Check for updates" in the footer, no/health).So on Windows the app has to run as an independent process: register it as a Windows service (Kestrel listens on a local port, see below) and let IIS act as a reverse proxy only; that is what lets the updater run
sc stop/start <service>and bring the app back. Console hosting (RestartMode: Direct) technically works too, but is not suitable for production (nobody watches the window once it is closed).
1. Register the app as a Windows service
Elevated command prompt:
# the built-in sc
sc.exe create EasyAdminBlazor binPath= "D:\app\EasyAdminBlazor\your-app.exe" start= auto
sc.exe start EasyAdminBlazor
# or NSSM
nssm install EasyAdminBlazor "D:\app\EasyAdminBlazor\your-app.exe"
nssm set EasyAdminBlazor AppDirectory "D:\app\EasyAdminBlazor"
nssm set EasyAdminBlazor Start SERVICE_AUTO_START
nssm start EasyAdminBlazor
Verify: http://127.0.0.1:5099/health should return
{
"status": "Healthy",
"applicationVersion": "1.0.0",
"frameworkVersion": "2.4.0"
}
The updater runs sc stop <service> → waits for the process to exit → backs up → replaces the files → sc start <service> → checks the version on /health. The service account has to be allowed to control the service (the LocalSystem default of sc create is enough; a restricted account needs the "start/stop this service" permission, and the application directory has to be writable).
2. IIS reverse proxy configuration
- Install ARR: IIS Manager → server node → Application Request Routing Cache → Server Proxy Settings → check Enable proxy;
- Create the site: IIS Manager → Sites → Add Website, point the physical path to an empty directory (the
web.configgoes there) and pick No Managed Code as the application pool; - Add web.config: put the file below in the site root (change
5099to the port your app actually listens on):
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="ReverseProxyToKestrel" stopProcessing="true">
<match url="(.*)" />
<action type="Rewrite" url="http://127.0.0.1:5099/{R:1}" />
</rule>
</rules>
</rewrite>
<proxy preserveHostHeader="true" />
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="104857600" />
</requestFiltering>
</security>
</system.webServer>
<system.web>
<httpRuntime maxRequestLength="102400" executionTimeout="600" />
</system.web>
</configuration>
Notes:
preserveHostHeader="true"keeps the original Host header, otherwise Blazor derives wrong URLs;maxAllowedContentLengthis raised to 100 MB to cover file uploads;- the application pool must run in No Managed Code mode, because the app is self-hosted by Kestrel.
3. Turn off Blazor's WebSocket compression (required for the Windows service model)
Since .NET 10, Interactive Server components enable WebSocket compression (permessage-deflate) by default, and the IIS ARR reverse proxy cannot handle compressed frames: the handshake returns 101 but the connection is dropped right afterwards (the browser reports WebSocket closed with status code 1006), so the admin page keeps spinning or stays blank — the online upgrade overlay, the countdown and the auto reload all depend on that connection and break with it.
Change the host's Program.cs to:
app.UseEasyAdminBlazor<App>(options =>
{
options.DisableWebSocketCompression = true;
});
Restart the service and reopen the admin page to confirm that the 1006 error is gone.
4. Application pool identity permissions
The IIS application pool runs as ApplicationPoolIdentity and has to reach the port Kestrel listens on (127.0.0.1:5099). Because it is a loopback address, no extra configuration is normally needed. If the site returns 502, check whether IIS can reach that port:
curl http://127.0.0.1:5099/health
If this command works on the server, the IIS reverse proxy is fine.
5. Linux BT Panel deployment (verified working, no service registration)
Do not register a systemd service and do not use the BT Panel "process guard" — publish with the built-in .NET site feature of BT Panel, the updater stops and starts the process itself.
- Publish:
dotnet publish -c Release -o publishon your machine, then copy the wholepublish/folder to/www/wwwroot/your-app; - Create the site: BT Panel → Websites → Add Website → pick .NET project / .NET website, set the project directory to
/www/wwwroot/your-app, the start file toyour-app.dlland the port BT Panel assigns (e.g. 5018); - Check the port: the site starts with
--urls http://localhost:5018, soHealthCheckUrlinappsettings.jsonuses the same porthttp://127.0.0.1:5018; - Configure: use the Linux
appsettings.jsonfrom section 2 (RestartMode: "Direct", port 5018); - Upgrade: copy the new
updates/v1.1.0/folder andupdates/index.jsonto<app>/updates/, then click "Check for updates → Upgrade now" in the admin UI.
Permissions: the application directory has to be writable (the upgrade writes .upgrade/ and the program files); www is a reasonable owner.
6. Deploying a new version to the server
The server needs no redeployment of the program — copy one directory over:
server <app>/updates/ ← put the new version folder here (e.g. v1.1.0/)
Then log in to the admin UI → "Check for updates" → "Upgrade now" and wait for the page to reload. The service stops for a few seconds, the page reconnects on its own and nobody has to log in again.
First deployment on a new server: copy the whole publish/ folder (it already contains the updates/v1.0.0/ baseline); from then on copy only the increment folder for each version (the baseline is optional if you do not want to keep it).
7. Troubleshooting
| Symptom | What to do |
|---|---|
| No "Check for updates" in the footer | in-process IIS hosting (by design), Upgrade:Enabled is not true, or the account is not an administrator |
| "Already up to date" | the new version folder is not in the server's updates\, or the host <Version> was not bumped |
| "Upgrade chain is broken" | an intermediate version package is missing — copy it as well |
Clicked upgrade but nothing happens and upgrade.log is empty |
updater/ was not deployed as a whole (updater and engine must be the same version); check the app log for the [升级] 后台启动升级程序:… line |
| A 502 appears for a few seconds | expected: the app is restarting; the overlay and the countdown take care of it |
The admin page keeps spinning / is blank and the browser console reports WebSocket closed with status code 1006 |
IIS ARR is not compatible with Blazor's WebSocket compression (permessage-deflate); add app.UseEasyAdminBlazor<App>(options => { options.DisableWebSocketCompression = true; }); as described in section 2 or section 4 (or strip the Sec-WebSocket-Extensions request header at the IIS side) |
| Everyone has to log in again | do not change AesKey / CookieName, and keep DataProtectionKeyPath on the same directory (the upgrade protects .aspnet/DataProtection-Keys and the configured key directory by default, so this normally does not happen) |
| Upgrade failed | it has been rolled back automatically; send .upgrade/upgrade.log and upgrade-status.json |