Repository navigation
[API Proposal]: WASM DotnetHostBuilder assembly loading progress callback #93941
Description
Background and motivation
The WASM runtime can take a while to load for certain kinds of apps. To provide a better experience for the user using the application, it can be useful to show a loading indicator.
ASP.NET Core Blazor did this (at least it did in .NET 7 when I was last investigating this, although looks like it may not be the case now), but it had to manually instantiate the web assembly module in order to achieve this.
Currently, there is no public API available on the DotnetHostBuilder type that enables this scenario. The public, documented approach would require manually looking up the blazor.boot.json file, and then calling createDotnetRuntime using that configuration. However, for less advanced scenarios, it would be useful to have this functionality available on the host builder.
This is already possible by using the internal withModuleConfig API, and passing in a value to the onDownloadResourceProgress callback, however this method is internal and not exposed in the typescript type files for the DotnetHostBuilder, making for a bad IDE experience. This method is mentioned in one of the advanced samples here, which is how I discovered it in the first place.
API Proposal
interface DotnetHostBuilder {
//exact naming TDB
//parameters currently match those provided to the `onDownloadResourceProgress` callback available when calling `createDotnetRuntime`
withDownloadResourceProgress(callback: (resourcesLoaded: number, totalResources: number) => void): DotnetHostBuilder;
}Currently, using onDownloadResourceProgress, the total parameter does not actually reflect the total number of resources that the runtime needs to load - I suggest that for this user-friendly API we provide that information rather than making the user calculate this number themselves directly from the blazor.boot.json file.
API Usage
const runtime = await dotnet
.withDownloadResourceProgress(updateProgress)
//...other configuration
.create();
function updateProgress(loaded: number, total: number) {
//do something with the information
}Alternative Designs
- Expose
withModuleConfigpublicly
This is a much more advanced API, allowing access to lower-level emscripten and more control over how the WASM module is instantiated. - Alternative names
withDownloadResourceProgressCallbackwithDownloadProgresswithInitializationProgress- etc.
Risks
Low - the API already exists, this would just be exposing it for use in a more user friendly manner.
Activity
maraf commentedon Oct 25, 2023
Thank you for the proposal. It is reasonable to expose the callback with public API.
I have fixed the propsal API typescript definition so the parameter is a callback.
maraf commentedon Oct 25, 2023
cc @pavelsavara
JakeYallop commentedon Oct 25, 2023
I'd be happy to contribute a PR if it would be accepted, unless this need to go through API review first?
maraf commentedon Oct 25, 2023
PR is welcome! Actually, we don't need API review for JavaScript changes
JakeYallop commentedon Oct 25, 2023
I'm thinking it would be much simpler if we had the same behaviour for this method vs the onDownloadResourceProgress callback specified in
withModuleConfig.The proposal above suggests making
totalResourcesactually be the total number of resources that need to be loaded during initialization, however at the moment, it seems these 2 values representresourcesLoaded- the number of completed requests for loading resourcestotalResources- the number of started requests for loading resourcesruntime/src/mono/wasm/runtime/loader/assets.ts
Lines 598 to 612 in 9ad24ae
What do we want to do here? Using the
withModuleConfigcallback, its not a big deal to ask the user to compute the number of resources that need to be loaded, as its an advanced API, however, with this new API - I'm not sure that same assumption holds. The developer using this API shouldn't need to know what the blazor.boot.json looks like, which would be the only way to compute this number. Additionally, the only way to actually get the config before loading the runtime so that this total value can be computed would mean callingwithModuleConfiganyway - which defeats whole point of the proposal.We have a few options:
onDownloadResourceProgressandwithDownloadResourceProgress, and maketotalResourcesreturn the total number of resources the runtime needs to load whilst its initialising. This would be a low-impact breaking change.withModuleConfigsetting.maraf commentedon Oct 26, 2023
Sorry, I missed the part about total number. We should definitely have just one callback, so
withDownloadResourceProgressshould reuseonDownloadResourceProgress. Current behavior can be considered as a bug / not ideal. IIRC it's not straightforward to get total number of resources to download, because not everything from the boot config will be downloaded (pdbs are used only in debug mode, only one icu is downloaded, memory snapshot skip dlls, etc).We're ok accepting a PR with just the new API and opening an issue for better "total resources" computation
JakeYallop commentedon Oct 26, 2023
Ah - I did wonder about the reasoning behind it - makes a bit more sense now. Will leave the existing behaviour as is.
JakeYallop commentedon Dec 13, 2024
I won't be working on this any time soon, but I don't think "needs author action" is the right label either - should this just be marked as "help wanted"?