19 KiB

Raw Blame History

title

author

description

monikerRange

ms.author

ms.custom

ms.date

no-loc

uid

ASP.NET Core Blazor Startup

guardrex

Learn how to configure Blazor startup.

>= aspnetcore-3.1

riande

mvc

11/09/2021

Home

Privacy

Kestrel

appsettings.json

ASP.NET Core Identity

Blazor

Blazor Server

Blazor WebAssembly

Identity

Let's Encrypt

Razor

SignalR

blazor/fundamentals/startup

ASP.NET Core Blazor Startup

::: moniker range=">= aspnetcore-6.0"

Configure a manual start in the wwwroot/index.html file (Blazor WebAssembly) or Pages/_Layout.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.

JavaScript initializers

[!INCLUDE]

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:

null/undefined, which results in the default loading behavior.
A Response promise. For an example, see xref:blazor/host-and-deploy/webassembly#compression.

Additional resources

::: moniker-end

::: moniker range=">= aspnetcore-5.0 < aspnetcore-6.0"

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

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.

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>

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:

null/undefined, which results in the default loading behavior.
A Response promise. For an example, see xref:blazor/host-and-deploy/webassembly#compression.

Additional resources

::: moniker-end

::: moniker range="< aspnetcore-5.0"

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

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.

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/3.1.0/${name}`;
      }
    }
  });
</script>

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:

null/undefined, which results in the default loading behavior.
A Response promise. For an example, see xref:blazor/host-and-deploy/webassembly#compression.

Additional resources

::: moniker-end

19 KiB Raw Blame History

ASP.NET Core Blazor Startup

JavaScript initializers

Initialize Blazor when the document is ready

Chain to the Promise that results from a manual start

Load boot resources

Additional resources

Initialize Blazor when the document is ready

Chain to the Promise that results from a manual start

Load boot resources

Additional resources

Initialize Blazor when the document is ready

Chain to the Promise that results from a manual start

Load boot resources

Additional resources

19 KiB

Raw Blame History

Chain to the `Promise` that results from a manual start

Chain to the `Promise` that results from a manual start

Chain to the `Promise` that results from a manual start