ASP.NET Core Blazor 启动

项目
03/02/2024

注意

此版本不是本文的最新版本。对于当前版本，请参阅此文的 .NET 8 版本。

重要

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本，请参阅此文的 .NET 8 版本。

本文介绍 Blazor 应用启动配置。

有关用于服务器端开发的 ASP.NET Core 应用配置的一般指南，请参阅 ASP.NET Core 中的配置。

启动过程和配置

Blazor 启动过程可以通过 Blazor 脚本 (blazor.*.js) 自动异步完成，其中 * 占位符为：

适用于 Blazor Web 应用的 web
适用于 Blazor Server 应用的 server
适用于 Blazor WebAssembly 应用的 webassembly

Blazor 启动过程可以通过 Blazor 脚本 (blazor.*.js) 自动异步完成，其中 * 占位符为：

适用于 Blazor Server 应用的 server
适用于 Blazor WebAssembly 应用的 webassembly

有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

手动启动 Blazor 的步骤：

Blazor Web 应用：

将 autostart="false" 属性和值添加到 Blazor<script> 标记中。
将调用 Blazor.start() 的脚本放置在 Blazor<script> 标记之后并放在结束的 </body> 标记内。
将静态服务器端呈现（静态 SSR）选项置于 ssr 属性中。
将服务器端 Blazor-SignalR 线路选项置于 circuit 属性中。
将客户端 WebAssembly 选项置于 webAssembly 属性中。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ssr: {
      ...
    },
    circuit: {
      ...
    },
    webAssembly: {
      ...
    }
  });
  ...
</script>

独立 Blazor WebAssembly 和 Blazor Server：

将 autostart="false" 属性和值添加到 Blazor<script> 标记中。
将调用 Blazor.start() 的脚本放置在 Blazor<script> 标记之后并放在结束的 </body> 标记内。
可以在 Blazor.start() 参数中提供其他选项。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ...
  });
  ...
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

JavaScript 初始值设定项

JavaScript (JS) 初始值设定项在 Blazor 应用加载之前和之后执行逻辑。 JS 初始值设定项在以下场景中很有用：

自定义 Blazor 应用的加载方式。
在 Blazor 启动之前初始化库。
配置 Blazor 设置。

JS 初始值设定项是在生成过程中检测到的，并自动进行导入。使用 JS 初始值设定项通常无需在使用 Razor 类库 (RCL) 时从应用中手动触发脚本函数。

若要定义 JS 初始值设定项，请向项目添加名为 {NAME}.lib.module.js 的 JS 模块，其中 {NAME} 占位符是程序集名称、库名称或包标识符。将文件放在项目的 Web 根目录中，通常为 wwwroot 文件夹。

对于 Blazor Web 应用：

beforeWebStart(options)：在 Blazor Web 应用启动之前调用。例如，beforeWebStart 用于自定义加载过程、日志记录级别和其他选项。接收 Blazor Web 选项 (options)。
afterWebStarted(blazor)：在所有 beforeWebStart 承诺解决后调用。例如，afterWebStarted 可用于注册 Blazor 事件侦听器和自定义事件类型。 Blazor 实例作为参数 (blazor) 传递给 afterWebStarted。
beforeServerStart(options, extensions)：在启动第一个服务器运行时之前调用。接收 SignalR 路线启动选项 (options) 以及在发布期间添加的任何扩展 (extensions)。
afterServerStarted(blazor)：在启动第一个交互式服务器运行时之后调用。
beforeWebAssemblyStart(options, extensions)：在启动交互式 WebAssembly 运行时之前调用。接收 Blazor 选项 (options) 以及在发布期间添加的任何扩展 (extensions)。例如，选项可以指定使用自定义启动资源加载程序。
afterWebAssemblyStarted(blazor)：在启动交互式 WebAssembly 运行时之后调用。

注意

在 Blazor Web 应用中，默认情况下不会调用旧的 JS 初始值设定项（beforeStart、afterStarted）。可使用 enableClassicInitializers 选项启用旧版初始值设定项来运行。但是，旧版初始值设定项执行是不可预测的。

<script>
  Blazor.start({ enableClassicInitializers: true });
</script>

对于 Blazor Server、Blazor WebAssembly 和 Blazor Hybrid 应用：

beforeStart(options, extensions)：在 Blazor 启动之前调用。例如，beforeStart 用于自定义加载过程、日志记录级别以及其他特定于托管模型的选项。
- 客户端 beforeStart 接收 Blazor 选项 (options) 以及在发布期间添加的任何扩展 (extensions)。例如，选项可以指定使用自定义启动资源加载程序。
- 服务器端 beforeStart 接收 SignalR 线路启动选项 (options)。
- 在 BlazorWebView 中，不会传递任何选项。
afterStarted(blazor)：在 Blazor 准备好从 JS 接收调用后调用。例如，afterStarted 用于通过进行 JS 互操作调用并注册自定义元素来初始化库。 Blazor 实例作为参数 (blazor) 传递给 afterStarted。

其他 .NET WebAssembly 运行时回调：

onRuntimeConfigLoaded(config)：在下载启动配置时调用。允许应用在运行时启动前（参数是来自 dotnet.d.ts 的 MonoConfig）修改参数（配置）：

export function onRuntimeConfigLoaded(config) {
  // Sample: Enable startup diagnostic logging when the URL contains 
  // parameter debug=1
  const params = new URLSearchParams(location.search);
  if (params.get("debug") == "1") {
    config.diagnosticTracing = true;
  }
}

onRuntimeReady({ getAssemblyExports, getConfig })：在 .NET WebAssembly 运行时启动后调用（参数是来自 dotnet.d.ts 的 RuntimeAPI）：

export function onRuntimeReady({ getAssemblyExports, getConfig }) {
  // Sample: After the runtime starts, but before Main method is called, 
  // call [JSExport]ed method.
  const config = getConfig();
  const exports = await getAssemblyExports(config.mainAssemblyName);
  exports.Sample.Greet();
}

这两个回调都可以返回一个 Promise，并会在启动继续之前等待该承诺。

对于文件名：

如果 JS 初始值设定项用作项目中的静态资产，请使用格式 {ASSEMBLY NAME}.lib.module.js，其中 {ASSEMBLY NAME} 占位符是应用的程序集名称。例如，对于程序集名称为 BlazorSample 的项目，将文件命名为 BlazorSample.lib.module.js。将文件放在应用的 wwwroot 文件夹中。
如果 JS 初始值设定项是从 RCL 使用的，请使用格式 {LIBRARY NAME/PACKAGE ID}.lib.module.js，其中 {LIBRARY NAME/PACKAGE ID} 占位符是项目的库名称或包标识符。例如，对于包标识符为 RazorClassLibrary1 的 RCL，将文件命名为 RazorClassLibrary1.lib.module.js。将文件放在库的 wwwroot 文件夹中。

对于 Blazor Web 应用：

下面的示例展示了 JS 初始值设定项，它们通过将脚本追加到 beforeWebStart 和 afterWebStarted 中的 <head>，在 Blazor Web 应用启动之前和之后加载自定义脚本：

export function beforeWebStart() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterWebStarted() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

前面的 beforeWebStart 示例仅保证自定义脚本在 Blazor 启动之前加载。它不保证脚本中等待的承诺在 Blazor 启动之前完成执行。

对于 Blazor Server、Blazor WebAssembly 和 Blazor Hybrid 应用：

下面的示例展示了通过将脚本追加到 beforeStart 和 afterStarted 中的 <head>，在 Blazor 启动之前和之后加载自定义脚本的 JS 初始值设定项：

export function beforeStart(options, extensions) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterStarted(blazor) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

前面的 beforeStart 示例仅保证自定义脚本在 Blazor 启动之前加载。它不保证脚本中等待的承诺在 Blazor 启动之前完成执行。

注意

MVC 和 Razor Pages 应用不会自动加载 JS 初始值设定项。但是，开发人员代码可以包含一个脚本，用于提取应用的清单并触发 JS 初始值设定项的加载。

有关 JS 初始化表达式的示例，请参阅以下资源：

使用静态服务器端呈现（静态 SSR）的 ASP.NET Core Blazor JavaScript
在 JavaScript 应用和 SPA 框架中使用 Razor 组件（quoteContainer2 示例）
ASP.NET Core Blazor 事件处理（自定义剪贴板粘贴事件示例）
为 ASP.NET Core 中的 TOTP 验证器应用启用 QR 码生成Blazor Web 应用
ASP.NET Core GitHub 存储库中的基本测试应用 (BasicTestApp.lib.module.js)

在 JavaScript 应用和 SPA 框架中使用 Razor 组件（quoteContainer2 示例）
ASP.NET Core Blazor 事件处理（自定义剪贴板粘贴事件示例）
ASP.NET Core 托管的 Blazor WebAssembly 应用的部署布局
ASP.NET Core GitHub 存储库中的基本测试应用 (BasicTestApp.lib.module.js)

注意

指向 .NET 参考源的文档链接通常会加载存储库的默认分支，该分支表示针对下一个 .NET 版本的当前开发。若要为特定版本选择标记，请使用“切换分支或标记”下拉列表。有关详细信息，请参阅如何选择 ASP.NET Core 源代码的版本标记 (dotnet/AspNetCore.Docs #26205)。

确保按特定顺序加载库

按照应加载的顺序将自定义脚本追加到 beforeStart 和 afterStarted 中的 <head>。

以下示例在 script2.js 之前加载 script1.js，在 script4.js 之前加载 script3.js：

export function beforeStart(options, extensions) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script1.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script2.js');
    document.head.appendChild(customScript2);
}

export function afterStarted(blazor) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script3.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script4.js');
    document.head.appendChild(customScript2);
}

导入其他模块

使用 JS 初始值设定项文件中的顶级 import 语句导入其他模块。

additionalModule.js：

export function logMessage() {
  console.log('logMessage is logging');
}

在 JS 初始值设定项文件 (.lib.module.js) 中：

import { logMessage } from "/additionalModule.js";

export function beforeStart(options, extensions) {
  ...

  logMessage();
}

导入映射

ASP.NET Core 和 Blazor 支持导入映射。

文档准备就绪时初始化 Blazor

当文档准备就绪时，以下示例将启动 Blazor：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    Blazor.start();
  });
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

链接到由手动启动生成的 `Promise`

若要执行其他任务（如 JS 互操作初始化），请使用 then 链接到 Promise（由手动 Blazor 应用启动生成）：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start().then(function () {
    ...
  });
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

注意

若要在 Blazor 启动后使库自动执行其他任务，请使用 JavaScript 初始值设定项。使用 JS 初始值设定项不需要库的使用者将 JS 调用链接到 Blazor 的手动启动。

加载客户端启动资源

当应用程序在浏览器中加载时，该应用程序将从服务器下载启动资源：

用于启动应用程序的 JavaScript 代码
.NET 运行时和程序集
区域设置特定的数据

自定义如何使用 loadBootResource API 加载这些启动资源。 loadBootResource 函数会重写内置启动资源加载机制。在以下场景中使用 loadBootResource：

从 CDN 加载静态资源，例如时区数据或 dotnet.wasm。
使用 HTTP 请求加载压缩的程序集，并将其解压缩到不支持从服务器提取压缩内容的主机的客户端上。
将每个 fetch 请求重定向到新名称，从而为资源提供别名。

注意

外部源必须返回浏览器所需的跨源资源共享 (CORS) 标头以允许跨源资源加载。 CDN 通常会默认提供所需的标头。

loadBootResource 参数如下表所示。

参数	描述
`type`	资源类型。允许的类型包括：`assembly`、`pdb`、`dotnetjs`、`dotnetwasm` 和 `timezonedata`。你只需指定自定义行为的类型。框架会根据默认的加载行为加载未指定到 `loadBootResource` 的类型。 `dotnetjs` 启动资源 (`dotnet.*.js`) 必须返回表示默认加载行为的 `null` 或表示 `dotnetjs` 启动资源的源的 URI。
`name`	资源的名称。
`defaultUri`	资源的相对或绝对 URI。
`integrity`	表示响应中的预期内容的完整性字符串。

loadBootResource 函数可以返回 URI 字符串以替代加载进程。在以下示例中，来自 bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework 的以下文件从 CDN 的 https://cdn.example.com/blazorwebassembly/{VERSION}/ 提供：

dotnet.*.js
dotnet.wasm
时区数据

{TARGET FRAMEWORK} 占位符是目标框架名字对象（例如 net7.0）。 {VERSION} 占位符是共享框架版本（例如 7.0.0）。

Blazor Web 应用：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      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/{VERSION}/${name}`;
        }
      }
    }
  });
</script>

独立 Blazor WebAssembly：

<script src="{BLAZOR SCRIPT}" 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/{VERSION}/${name}`;
      }
    }
  });
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

除了为启动资源自定义 URL 外，该 loadBootResource 函数还可以直接调用 fetch 并返回结果。以下示例将一个自定义 HTTP 标头添加到出站请求。若要保持默认的完整性检查行为，请传递 integrity 参数。

Blazor Web 应用：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type == 'dotnetjs') {
          return null;
        } else {
          return fetch(defaultUri, {
            cache: 'no-cache',
            integrity: integrity,
            headers: { 'Custom-Header': 'Custom Value' }
          });
        }
      }
    }
  });
</script>

独立 Blazor WebAssembly：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type == 'dotnetjs') {
        return null;
      } else {
        return fetch(defaultUri, {
          cache: 'no-cache',
          integrity: integrity,
          headers: { 'Custom-Header': 'Custom Value' }
        });
      }
    }
  });
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

当 loadBootResource 函数返回 null 时，Blazor 采用资源的默认加载行为。例如，上述代码为 dotnetjs 启动资源 (dotnet.*.js) 返回 null，因为 dotnetjs 启动资源必须返回表示默认加载行为的 null 或表示 dotnetjs 启动资源的源的 URI。

loadBootResource 函数还可以返回 Response promise。有关示例，请参阅托管和部署 ASP.NET Core Blazor WebAssembly。

有关详细信息，请参阅 ASP.NET Core Blazor WebAssembly .NET 运行时和应用捆绑包缓存。

控制 C# 代码中的标头

使用下列方法控制 C# 代码中启动时的标头。

在以下示例中，通过 CSP 标头将内容安全策略 (CSP) 应用于应用。 {POLICY STRING} 占位符是 CSP 策略字符串。

服务器端和预呈现的客户端方案

使用 ASP.NET Core 中间件来控制标头集合。

在 Program 文件中：

在 Startup.cs 的 Startup.Configure 中：

app.Use(async (context, next) =>
{
    context.Response.Headers.Append("Content-Security-Policy", "{POLICY STRING}");
    await next();
});

前面的示例使用内联中间件，但你也可以创建自定义中间件类，并使用 Program 文件中的扩展方法调用中间件。有关详细信息，请参阅编写自定义 ASP.NET Core 中间件。

无需预呈现的客户端开发

将 StaticFileOptions 传递给 MapFallbackToFile，以指定 OnPrepareResponse 阶段的响应标头。

在服务器端 Program 文件中：

在 Startup.cs 的 Startup.Configure 中：

var staticFileOptions = new StaticFileOptions
{
    OnPrepareResponse = context =>
    {
        context.Context.Response.Headers.Append("Content-Security-Policy", 
            "{POLICY STRING}");
    }
};

...

app.MapFallbackToFile("index.html", staticFileOptions);

有关 CSP 的详细信息，请参阅为 ASP.NET Core Blazor 强制实施内容安全策略。

客户端加载进度指示器

加载进度指示器向用户显示应用的加载进度，指示应用正在正常加载，用户应等待加载完成。

Blazor Web 应用加载进度

从 Blazor Web 应用项目模板创建的应用中没有 Blazor WebAssembly 应用中所用的加载进度指示器。通常，交互式 WebAssembly 组件不需要加载进度指示器，因为 Blazor Web 应用会在服务器上预呈现客户端组件，以缩短初始加载时间。对于混合呈现模式的情况，框架或开发人员代码还必须注意避免以下问题：

在同一呈现页面上显示多个加载指示器。
在加载 WebAssembly 运行时时无意中丢弃了预呈现的内容。

.NET 的将来版本可能提供基于框架的加载进度指示器。同时，可以将自定义加载进度指示器添加到 Blazor Web 应用。

在调用 OperatingSystem.IsBrowser 的 .Client 应用中创建 LoadingProgress 组件：

为 false 时，在下载 Blazor 捆绑包时和在客户端上激活 Blazor 运行时之前，显示加载进度指示器。
为 true 时，呈现请求的组件的内容。

以下演示使用了在从 Blazor WebAssembly 模板创建的应用中发现的加载进度指示器，包括对模板提供的样式的修改。这些样式由 HeadContent 组件加载到应用的 <head> 内容中。有关详细信息，请参阅在 ASP.NET Core Blazor 应用中控制头内容。

LoadingProgress.razor：

@if (!OperatingSystem.IsBrowser())
{
    <HeadContent>
        <style>
            .loading-progress {
                position: relative;
                display: block;
                width: 8rem;
                height: 8rem;
                margin: 20vh auto 1rem auto;
            }

                .loading-progress circle {
                    fill: none;
                    stroke: #e0e0e0;
                    stroke-width: 0.6rem;
                    transform-origin: 50% 50%;
                    transform: rotate(-90deg);
                }

                    .loading-progress circle:last-child {
                        stroke: #1b6ec2;
                        stroke-dasharray: 
                            calc(3.141 * var(--blazor-load-percentage, 0%) * 0.8), 
                            500%;
                        transition: stroke-dasharray 0.05s ease-in-out;
                    }

            .loading-progress-text {
                position: relative;
                text-align: center;
                font-weight: bold;
                top: -90px;
            }

                .loading-progress-text:after {
                    content: var(--blazor-load-percentage-text, "Loading");
                }

            code {
                color: #c02d76;
            }
        </style>
    </HeadContent>
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

在采用交互式 WebAssembly 呈现的组件中，使用 LoadingProgress 组件包装组件的 Razor 标记。下面的示例使用从 Blazor Web 应用项目模板创建的应用的 Counter 组件演示了该方法。

Pages/Counter.razor：

@page "/counter"
@rendermode InteractiveWebAssembly

<PageTitle>Counter</PageTitle>

<LoadingProgress>
    <h1>Counter</h1>

    <p role="status">Current count: @currentCount</p>

    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</LoadingProgress>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Blazor WebAssembly 应用加载进度

项目模板包含可缩放矢量图形 (SVG) 和显示应用加载进度的文本指示器。

进度指示器是使用 Blazor 提供的两个 CSS 自定义属性（变量）通过 HTML 和 CSS 实现的：

--blazor-load-percentage：加载的应用文件的百分比。
--blazor-load-percentage-text：加载的应用文件的百分比，四舍五入为最接近的整数。

使用上述 CSS 变量可以创建与应用样式匹配的自定义进度指示器。

如下示例中：

resourcesLoaded 是应用启动期间加载的资源的瞬时计数。
totalResources 是要加载的资源总数。

const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

默认舍入进度指示器在 wwwroot/index.html 文件中的 HTML 中实现：

<div id="app">
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
</div>

若要查看默认进度指示器的项目模板标记和样式，请参阅 ASP.NET Core 参考源：

注意

以下示例演示了如何实现线性进度指示器，而不是使用默认的舍入进度指示器。

向 wwwroot/css/app.css 添加以下样式：

.linear-progress {
    background: silver;
    width: 50vw;
    margin: 20% auto;
    height: 1rem;
    border-radius: 10rem;
    overflow: hidden;
    position: relative;
}

.linear-progress:after {
    content: '';
    position: absolute;
    inset: 0;
    background: blue;
    scale: var(--blazor-load-percentage, 0%) 100%;
    transform-origin: left top;
    transition: scale ease-out 0.5s;
}

CSS 变量 (var(...)) 用于将 --blazor-load-percentage 的值传递给蓝色伪元素的 scale 属性，该属性指示应用文件的加载进度。当应用加载时，--blazor-load-percentage 会自动更新，这会动态更改进度指示器的可视表示形式。

在 wwwroot/index.html 中，删除 <div id="app">...</div> 中的默认 SVG 舍入指示器，并将其替换为以下标记：

<div class="linear-progress"></div>

配置 .NET WebAssembly 运行时

在高级编程方案中，会将 configureRuntime 函数与 dotnet 运行时主机生成器配合使用来配置 .NET WebAssembly 运行时。例如，dotnet.withEnvironmentVariable 设置一个可执行以下操作的环境变量：

配置 .NET WebAssembly 运行时。
更改 C 库的行为。

configureRuntime 函数还可用于启用与浏览器探查器的集成。

在以下实例，会设置一个环境变量：

{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。
{NAME} 占位符是环境变量的名称。
{VALUE} 占位符是环境变量的值。

Blazor Web 应用：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      configureRuntime: dotnet => {
        dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
      }
    }
  });
</script>

独立 Blazor WebAssembly：

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureRuntime: dotnet => {
      dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
    }
  });
</script>

注意

可使用 Blazor WebAssembly 运行时 API (Blazor.runtime) 访问 .NET 运行时实例。例如，可以使用 Blazor.runtime.runtimeBuildInfo.buildConfiguration 获取应用的生成配置。

有关 .NET WebAssembly 运行时配置的详细信息，请参阅 dotnet/runtime GitHub 存储库中的运行时 TypeScript 定义文件 (dotnet.d.ts)。

注意

本部分适用于 BlazorWeb 应用。

若要禁用增强型导航和表单处理，请将 Blazor.start 的 disableDomPreservation 设置为 true。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    ssr: { disableDomPreservation: true }
  });
</script>

在前面的示例中，{BLAZOR SCRIPT} 占位符是 Blazor 脚本路径和文件名。有关脚本的位置，请参阅 ASP.NET Core Blazor 项目结构。

ASP.NET Core Blazor 启动

启动过程和配置

JavaScript 初始值设定项

确保按特定顺序加载库

导入其他模块

导入映射

文档准备就绪时初始化 Blazor

链接到由手动启动生成的 `Promise`

加载客户端启动资源

控制 C# 代码中的标头

服务器端和预呈现的客户端方案

无需预呈现的客户端开发

客户端加载进度指示器

Blazor Web 应用加载进度

Blazor WebAssembly 应用加载进度

配置 .NET WebAssembly 运行时

禁用增强型导航和表单处理

其他资源

反馈

其他资源

ASP.NET Core Blazor 启动

启动过程和配置

JavaScript 初始值设定项

确保按特定顺序加载库

导入其他模块

导入映射

文档准备就绪时初始化 Blazor

链接到由手动启动生成的 Promise

加载客户端启动资源

控制 C# 代码中的标头

服务器端和预呈现的客户端方案

无需预呈现的客户端开发

客户端加载进度指示器

Blazor Web 应用加载进度

Blazor WebAssembly 应用加载进度

配置 .NET WebAssembly 运行时

禁用增强型导航和表单处理

其他资源

反馈

其他资源

链接到由手动启动生成的 `Promise`