ASP.NET Core Blazor 啟動

發行項
04/10/2024

注意

這不是這篇文章的最新版本。如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前版本，請參閱本文的 .NET 8 版本。

本文說明 Blazor 應用程式啟動設定。

如需用於伺服器端開發的 ASP.NET Core 應用程式組態的一般指引，請參閱 ASP.NET Core 中的組態。

啟動程序與設定

Blazor 啟動程序透過 Blazor 指令碼 (blazor.*.js) 自動化且非同步，其中的 * 預留位置為：

web 用於 Blazor Web 應用程式
server 用於 Blazor Server 應用程式
webassembly 用於 Blazor WebAssembly 應用程式

Blazor 啟動程序透過 Blazor 指令碼 (blazor.*.js) 自動化且非同步，其中的 * 預留位置為：

server 用於 Blazor Server 應用程式
webassembly 用於 Blazor 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 初始設定式，請將 JS 模組新增至名為 {NAME}.lib.module.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 執行階段啟動之後呼叫。

注意

舊版 JS 初始設定式 (beforeStart、afterStarted) 預設不會在 Blazor Web 應用程式中叫用。您可以讓舊版初始設定式透過 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 Interop 呼叫並註冊自訂元素，藉此用來初始化程式庫。 Blazor 執行個體會以引數的形式 (blazor) 傳遞至 afterStarted。

其他 .NET WebAssembly 執行階段回呼：

onRuntimeConfigLoaded(config)：下載開機設定時呼叫。允許應用程式在執行階段啟動之前修改參數 (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.lib.module.js，其組件名稱為 BlazorSample。將檔案放在應用程式的 wwwroot 資料夾中。
如果 JS 初始設定式是從 RCL 取用，請使用格式 {LIBRARY NAME/PACKAGE ID}.lib.module.js，其中 {LIBRARY NAME/PACKAGE ID} 預留位置是專案的程式庫名稱或套件識別碼。例如，將 RCL 的檔案命名為 RazorClassLibrary1.lib.module.js，其封裝識別碼為 RazorClassLibrary1。將檔案放在程式庫的 wwwroot 資料夾中。

針對 Blazor Web 應用程式：

下列範例示範 JS 初始設定式，這些初始設定式會在 Blazor Web 應用程式啟動之前和之後載入自訂指令碼，方法是將這些指令碼新增至 beforeWebStart 和 afterWebStarted 中的 <head>：

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 啟動之前載入。其不保證指令碼中等候的 Promise 會在 Blazor 啟動之前完成其執行。

針對 Blazor Server、Blazor WebAssembly 和 Blazor Hybrid 應用程式：

下列範例示範 JS 初始設定式，這些初始設定式會在 Blazor 啟動之前和之後載入自訂指令碼，方法是將這些指令碼新增至 beforeStart 和 afterStarted 中的 <head>：

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 啟動之前載入。其不保證指令碼中等候的 Promise 會在 Blazor 啟動之前完成其執行。

注意

MVC 和 Razor Pages 應用程式不會自動載入 JS 初始設定式。不過，開發人員程式碼可以包含指令碼來擷取應用程式的資訊清單，並觸發 JS 初始設定式的載入。

如需 JS 初始設定式的範例，請參閱下列資源：

具有靜態伺服器端轉譯 (靜態 SSR) 的 ASP.NET Core Blazor JavaScript
在 JavaScript 應用程式和 SPA 架構中使用 Razor 元件 (quoteContainer2 範例)
ASP.NET Core Blazor 事件處理 (自訂剪貼簿貼上事件範例)
允許為 ASP.NET Core Blazor Web 應用程式中的 TOTP 驗證器應用程式產生 QR 代碼
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 Interop 初始化，請使用 then 鏈結至手動 Blazor 應用程式啟動所產生的 Promise：

<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 的下列檔案是從位於 https://cdn.example.com/blazorwebassembly/{VERSION}/ 的 CDN 提供：

dotnet.*.js
dotnet.wasm
時區資料

{TARGET FRAMEWORK} 預留位置是目標 Framework Moniker (例如，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 WebAssembly 應用程式中使用的載入進度指示器不存在於從 Blazor Web 應用程式專案範本建立的應用程式中。通常互動式 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 執行階段

在進階程式設計案例中，會使用具有 dotnet 執行階段主機建立器的 configureRuntime 函式來設定 .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>

注意

.NET 執行階段執行個體可以使用 Blazor WebAssembly 執行階段 API (Blazor.runtime) 進行存取。例如，您可以使用 Blazor.runtime.runtimeBuildInfo.buildConfiguration 取得應用程式的組建設定。

如需 .NET WebAssembly 執行階段設定的詳細資訊，請參閱 dotnet/runtime GitHub 存放庫中的執行階段的 TypeScript 定義檔案 (dotnet.d.ts)。

注意

本節適用於 Blazor Web Apps。

若要停用增強的導覽和表單處理，請針對 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`