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 withModuleConfig publicly
  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
  • withDownloadResourceProgressCallback
  • withDownloadProgress
  • withInitializationProgress
  • etc.

Risks

Low - the API already exists, this would just be exposing it for use in a more user friendly manner.