Compatibility issues with ABP Bundle version 10

Wed, 21 Jan 2026 00:00:00 +0800

Blazor WebAssembly + ABP 10.0.2 + .NET 10 Preview Release Compatibility Issues Record

Conclusion: Currently, using .NET 10 + ABP 10.0.2 to publish Blazor WASM will encounter framework-level issues such as script loading and Service Worker caching. In the short term, it is more recommended to use the stable version of .NET 8 + ABP 8, or adopt a small number of manual script references as a temporary solution in the current project.

1. Phenomenon: Normal in Development Mode, White Screen in Published Mode

Development mode (dotnet run / IDE startup):
- Blazor WebAssembly can be loaded normally.
- Login, OIDC, and ABP components all work normally.
Published mode (started from bin/Release/net10.0/publish after dotnet publish):
- The page HTML can return 200.
- Most of the static resources (global.css, global.js, dotnet.js, etc.) can return 200.
- But the front end does not render content in the end, and an exception appears in the console.

Typical error logs:

404 appears multiple times in the backend log:
- _framework/WHS.Blazor.Client.jqrq8onpr6.wasm 404.
- service-worker-assets.js 404.
Front-end console error:
- Could not find 'AuthenticationService.init' ('AuthenticationService' was undefined).
- Occurs in the callEntryPoint stage of blazor.web.js.

2. Old Resource Caching Issue Caused by Service Worker

Blazor PWA will by default:

Load service-worker-assets.js through service-worker.published.js.
Cache resources such as blazor.boot.json, wasm, dll, css, js according to assetsManifest.

The problem encountered with the combination of .NET 10 + ABP 10.0.2 is:

After the first release, Service Worker will cache an old blazor.boot.json and wasm hash.
When the code is modified and published again, even if the new wasm file is already on the server:
- The browser still preferentially takes the old version of blazor.boot.json from the SW cache.
- As a result, the front end will request a non-existent _framework/WHS.Blazor.Client.<old>.wasm, and the server returns 404.

Temporary solution:

In App.razor, make a special judgment for localhost and unregister all registered Service Workers at startup:

const isLocalhost = location.hostname === 'localhost' || location.hostname === '127.0.0.1';
if ('serviceWorker' in navigator && isLocalhost) {
    window.addEventListener('load', async () => {
        const registrations = await navigator.serviceWorker.getRegistrations();
        for (const registration of registrations) {
            await registration.unregister();
        }
    });
}

For the production environment (non-localhost), service-worker.published.js is still registered according to normal logic, retaining PWA capabilities.

3. ABP Core JS Not Injected Correctly

ABP Blazor relies on a set of core JS files, such as:

_content/Microsoft.AspNetCore.Components.WebAssembly.Authentication/AuthenticationService.js
_content/Volo.Abp.AspNetCore.Components.Web/libs/abp/js/abp.js
_content/Volo.Abp.AspNetCore.Components.Web/libs/abp/js/lang-utils.js
_content/Volo.Abp.AspNetCore.Components.Web/libs/abp/js/authentication-state-listener.js

According to ABP’s design, these scripts are usually:

AbpBundlingOptions + BlazorWebAssemblyStandardBundles.Scripts.Global;
 + app.MapAbpStaticAssets();

Automatically injected into the page.

In the new “Razor Components + Interactive WebAssembly” mode of .NET 10 + ABP 10.0.2 + Blazor, it is actually observed that:

In the published mode, when blazor.web.js starts, the above scripts may not have been loaded yet.
Result: The AuthenticationService or abp object is undefined, triggering an error that AuthenticationService.init cannot be found.

Temporary solution: Manually hardcode core script references and place them before blazor.web.js:

<body class="abp-application-layout">

    <!-- .NET 10 + ABP 10.0.2 compatibility fix: core JS is loaded synchronously in advance -->
    <script src="_content/Microsoft.AspNetCore.Components.WebAssembly.Authentication/AuthenticationService.js"></script>
    <script src="_content/Volo.Abp.AspNetCore.Components.Web/libs/abp/js/abp.js"></script>
    <script src="_content/Volo.Abp.AspNetCore.Components.Web/libs/abp/js/lang-utils.js"></script>
    <script src="_content/Volo.Abp.AspNetCore.Components.Web/libs/abp/js/authentication-state-listener.js"></script>
    <script src="_framework/blazor.web.js"></script>

    <!-- The following are the application container and ABP automatically injected global.js, etc. -->
</body>

This ensures that:

When blazor.web.js calls the .NET entry point, the relevant JS APIs are already available in window.

4. Why Manually Referencing Scripts is a “Temporary Solution”

Advantages:

Can quickly bypass the automatic Bundling/injection problem of the current version and make the application available in the published mode.
It is easier to troubleshoot and control the script loading order.

Disadvantages:

Lose the benefits of automatic merging, compression, and version hashing brought by the ABP Bundling system.
After ABP or .NET is upgraded, if the script path or file name changes, you need to manually maintain these <script>.
May be duplicated with the content injected by  (be careful not to load the same script twice).

Therefore, it is recommended to explicitly mark it as “compatibility fix / TODO” in the code, and it can be cleaned up after the framework is fixed:

<!--
.NET 10 + ABP 10.0.2 published mode compatibility fix:
Manually hardcode the core JS files to ensure synchronous loading before blazor.web.js starts.
ABP's automatic script injection may fail in the published mode (timing / path problem).
TODO: After ABP or .NET is fixed, remove the manual reference and restore the use of ABP automatic injection.
-->

5. Summary