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.Upgrade there is no "Check for updates" entry in the admin UI, no /health endpoint, 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

<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)

/health is mounted by the extension itself — you never map it yourself. Keep the host's app.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 reports WebSocket 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, replace app.UseEasyAdminBlazor<App>(); in Program.cs with the options overload:

app.UseEasyAdminBlazor<App>(options =>
{
    options.DisableWebSocketCompression = true;
});

The alternative is to strip the browser's Sec-WebSocket-Extensions request 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"
}

HealthCheckUrl must be reachable from the server itself and must use the same port the app listens on. To let customers upgrade from the published site, set Source to Url and put the release index in ReleaseIndexUrl (https://your-release-host/releases/index.json); HTTPS is required, add "AllowInsecureHttp": true for plain HTTP on an internal network. RestartMode also accepts Systemd (the updater stops and starts a systemd service) and External (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

  1. Install ARR: IIS Manager → server node → Application Request Routing Cache → Server Proxy Settings → check Enable proxy;
  2. Create the site: IIS Manager → Sites → Add Website, point the physical path to an empty directory (the web.config goes there) and pick No Managed Code as the application pool;
  3. Add web.config: put the file below in the site root (change 5099 to 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;
  • maxAllowedContentLength is 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.

  1. Publish: dotnet publish -c Release -o publish on your machine, then copy the whole publish/ folder to /www/wwwroot/your-app;
  2. 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 to your-app.dll and the port BT Panel assigns (e.g. 5018);
  3. Check the port: the site starts with --urls http://localhost:5018, so HealthCheckUrl in appsettings.json uses the same port http://127.0.0.1:5018;
  4. Configure: use the Linux appsettings.json from section 2 (RestartMode: "Direct", port 5018);
  5. Upgrade: copy the new updates/v1.1.0/ folder and updates/index.json to <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