ASP.NET Core Blazor Startup

Configure a manual start in the wwwroot/index.html file (Blazor WebAssembly) or Pages/_Host.cshtml file (Blazor Server):

  • Add an autostart="false" attribute and value to the <script> tag for the Blazor script.
  • Place a script that calls Blazor.start after the Blazor <script> tag and inside the closing </body> tag.

Initialize Blazor when the document is ready

The following example starts Blazor when the document is ready:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function() {
        Blazor.start();
      });
    </script>
</body>

The {webassembly|server} placeholder in the preceding markup is either webassembly for a Blazor WebAssembly app (blazor.webassembly.js) or server for a Blazor Server app (blazor.server.js).

Chain to the Promise that results from a manual start

To perform additional tasks, such as JS interop initialization, use then to chain to the Promise that results from a manual Blazor app start:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        ...
      });
    </script>
</body>

The {webassembly|server} placeholder in the preceding markup is either webassembly for a Blazor WebAssembly app (blazor.webassembly.js) or server for a Blazor Server app (blazor.server.js).

Load boot resources

This section only applies to Blazor WebAssembly apps.

When a Blazor WebAssembly app loads in the browser, the app downloads boot resources from the server:

  • JavaScript code to bootstrap the app
  • .NET runtime and assemblies
  • Locale specific data

Customize how these boot resources are loaded using the loadBootResource API. The loadBootResource function overrides the built-in boot resource loading mechanism. Use loadBootResource for the following scenarios:

  • Load static resources, such as timezone data or dotnet.wasm, from a CDN.
  • Load compressed assemblies using an HTTP request and decompress them on the client for hosts that don't support fetching compressed contents from the server.
  • Alias resources to a different name by redirecting each fetch request to a new name.

Note

External sources must return the required Cross-Origin Resource Sharing (CORS) headers for browsers to allow cross-origin resource loading. CDNs usually provide the required headers by default.

loadBootResource parameters appear in the following table.

Parameter Description
type The type of the resource. Permissable types include: assembly, pdb, dotnetjs, dotnetwasm, and timezonedata. You only need to specify types for custom behaviors. Types not specified to loadBootResource are loaded by the framework per their default loading behaviors.
name The name of the resource.
defaultUri The relative or absolute URI of the resource.
integrity The integrity string representing the expected content in the response.

The loadBootResource function can return a URI string to override the loading process. In the following example, the following files from bin/Release/net5.0/wwwroot/_framework are served from a CDN at https://cdn.example.com/blazorwebassembly/5.0.0/:

  • dotnet.*.js
  • dotnet.wasm
  • Timezone data

Inside the closing </body> tag of wwwroot/index.html:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
      switch (type) {
        case 'dotnetjs':
        case 'dotnetwasm':
        case 'timezonedata':
          return `https://cdn.example.com/blazorwebassembly/5.0.0/${name}`;
      }
    }
  });
</script>

To customize more than just the URLs for boot resources, the loadBootResource function can call fetch directly and return the result. The following example adds a custom HTTP header to the outbound requests. To retain the default integrity checking behavior, pass through the integrity parameter.

Inside the closing </body> tag of wwwroot/index.html:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      return fetch(defaultUri, { 
        cache: 'no-cache',
        integrity: integrity,
        headers: { 'Custom-Header': 'Custom Value' }
      });
    }
  });
</script>

The loadBootResource function can also return:

Additional resources