ASP.NET Core Blazor 基本概念

2025-04-30

注意

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

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。如需目前的版本，請參閱本文的 .NET 9 版本。

重要

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

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

「基礎知識」文章會提供基礎概念的指引。某些概念會連線到對元件的基本瞭解Razor，本文下一節會進一步說明這些概念，並詳述於 Components 文章中。

靜態和互動式轉譯概念

Razor 元件會 以靜態方式 呈現或 以互動方式 呈現。

靜態或 靜態渲染 是伺服器端的情境，表示元件會被渲染，但沒有能力讓使用者與 .NET/C# 程式代碼互動。 JavaScript 和 HTML DOM 事件不受影響，但用戶端上的任何使用者事件都無法使用在伺服器上執行的 .NET 進行處理。

互動/互動或 互動式轉譯 表示元件能夠透過 C# 程式代碼處理 .NET 事件和系結。 .NET 事件和繫結由 ASP.NET Core 執行階段在伺服器上處理，或由基於 WebAssembly 的 Blazor 執行階段在客戶端瀏覽器中處理。

重要

使用 Blazor Web App時，大部分 Blazor 的檔範例元件 都需要 互動功能才能運作，並示範文章所涵蓋的概念。當您在 Blazor Web App中測試文章所提供的範例元件時，請確定應用程式採用全域互動功能，或元件採用互動式渲染模式。此主題的詳細資訊是由<元件>一節中的 ASP.NET Core 轉譯模式所提供，稍後會出現在檔集中。

如需這些概念以及如何控制靜態和互動式轉譯的詳細資訊，請參閱Blazor檔中的一文。

用戶端和伺服器轉譯概念

Blazor整份文件中，用戶系統上發生的活動表示發生在用戶端或用戶端。據說在伺服器上發生的活動發生在 伺服器 或 伺服器端。

渲染一詞表示產生瀏覽器所顯示的 HTML 標記。

用戶端轉譯（CSR） 表示最終 HTML 標記是由用戶端上的 .NET WebAssembly 運行時間所產生。應用程式的用戶端產生的 UI 並不會有任何 HTML 由伺服器傳送到客戶端進行此類型的渲染。假設使用者會與頁面互動。沒有靜態客戶端轉譯之類的概念。 CSR 被認為是互動的，所以業界或文件裡不會用「互動式用戶端渲染」或「互動式 CSR」。
伺服器端轉譯（SSR） 表示最終的 HTML 標記是由伺服器上的 ASP.NET Core 執行時間所產生。 HTML 會透過網路傳送至用戶端，供用戶端的瀏覽器顯示。用戶端不會為應用程式伺服器產生的 UI 建立任何 HTML 以進行此類型的轉譯。 SSR 可屬於兩種類型：
- 靜態 SSR：伺服器會產生靜態 HTML，不會提供使用者互動或維護 Razor 元件狀態。
- 互動式 SSR： Blazor 事件允許使用者互動和 Razor 元件狀態由 Blazor 架構維護。
預先呈現 是伺服器上初始轉譯頁面內容的程式，而不需要啟用轉譯控件的事件處理程式。伺服器會盡快輸出頁面的 HTML UI，以回應初始要求，如此可改善應用程式對使用者的回應速度。預先呈現也可以藉由轉譯搜尋引擎用來計算頁面排名的初始 HTTP 回應內容，來改善搜尋引擎優化（SEO ）。在伺服器或用戶端上，一律會先進行預先轉譯，再進行最終轉譯。

Razor 元件

應用程式是以元件為基礎構建，通常簡稱為元件。「元件」是 UI 的元素，例如頁面、對話方塊或資料輸入表單。元件是 .NET 元件內建的 .NET C# 類別。

Razor 指的是元件通常以 Razor 標記頁面的形式撰寫，用於用戶端使用者介面的邏輯和組合。 Razor 是結合了 HTML 標記與 C# 程式碼的語法，專為開發人員的生產力而設計。 Razor 檔案會使用 .razor 副檔名。

雖然某些 Blazor 開發人員和線上資源使用「Blazor 元件」一詞，但本文不會這麼做，而是會普遍使用「Razor 元件」或「元件」。

Blazor 文件採用數個慣例來顯示和討論元件：

一般而言，範例會遵循 ASP.NET Core/C# 編碼慣例和工程指導方針。如需詳細資訊，請參閱下列資源：
- ASP.NET Core 架構工程指導方針（dotnet/aspnetcore GitHub 存放庫）
- C# 編碼慣例（C# 指南）
專案程式碼、檔案路徑和名稱、專案範本名稱和其他特製化詞彙都是美式英文，而且通常會以代碼保護。
元件通常會以其 C# 類別名稱 (Pascal 命名法) 加上「元件」一字來指稱。例如，典型的檔案上傳元件稱為「FileUpload 元件」。
元件的 C# 類別名稱通常與其檔案名稱相同。
路由式元件通常會將其相對 URL 設定為元件的類別名稱，使用 kebab-case 格式。例如，FileUpload 元件包含路由設定，可在相對 URL /file-upload 連線到轉譯的元件。在 Blazor 路由和導航中涵蓋了路由和導航。
使用多個版本的元件時，元件會循序編號。例如，FileUpload3 元件在 /file-upload-3 被到達。
元件定義 (Razor) 頂端的會按下列順序放置：.razor file、@page (.NET 8 或更新版本)、@rendermode 陳述式、按字母順序排列的其他指示詞。
雖然 private 成員並不必需使用，但在文章範例和範例應用程式中仍會使用存取修飾詞。例如，會陳述 private 以將名為 maxAllowedFiles 的欄位宣告為 private int maxAllowedFiles = 3;。
元件參數的值可以以 Razor 保留 @ 符號開頭，但不是必須的。常值 (例如布林值)、關鍵字 (例如 this)，以及作為元件參數值的 null 前面不會加上 @，但這也只是文件慣例。在您的程式碼中，如果您願意，可以在文字字面值前加上 @。
C# 類別會使用 this 關鍵詞，並避免在建構函式中使用底線（_）作為欄位的前綴，這與 ASP.NET Core 框架的工程指導方針不同。
在使用主要建構函式（C# 12 或更新版本的範例中，主要建構函式參數通常由類別成員直接使用。在文章範例中，程式代碼行會分割以減少水平捲動。這些段落分隔不會影響執行，但在貼到您的專案時可以選擇刪除。

ASP.NET Core Razor的Razor區段中提供了關於元件語法的其他資訊。

下面會舉例說明計數器元件以及從 Blazor 專案範本建立的應用程式部分內容。如需詳細的元件說明，請參閱文件稍後的「元件」文章。下列範例會先示範「基本概念」文章中所見的元件概念，再到達文件稍後的「元件」文章。

Counter.razor：

此元件會假設互動式轉譯模式繼承自父元件，或全域套用至應用程式。

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

此元件會假設互動式轉譯模式繼承自父元件，或全域套用至應用程式。

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

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

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

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

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

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

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

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

上述 Counter 元件：

會在第一行使用 @page 指示詞設定其路由。
會設定其網頁標題和頁面標題。
使用 @currentCount 呈現目前的計數。 currentCount 是 @code 區塊的 C# 程式碼所定義的整數變數。
會顯示可觸發 IncrementCount 方法的按鈕，該按鈕也可在 @code 區塊中找到，並且會增加 currentCount 變數的值。

渲染模式

基礎節點中的文章會參考轉譯模式的概念。此主題詳述於Blazor節點中的ASP.NET Core呈現模式的文章，該文章位於基本概念節點的文章之後。

對於此文章節點中關於轉譯模式概念的早期參考，目前只須留意下列內容：

中的每個元件 Blazor Web App 都會採用 轉譯模式 來判斷其使用的裝載模型、轉譯的位置，以及它是否以靜態方式在伺服器上呈現、針對伺服器上的使用者互動性轉譯，或針對用戶端上的使用者互動性轉譯（通常是在伺服器上預先呈現）。

Blazor Server 和 Blazor WebAssembly 在 .NET 8 之前的 ASP.NET Core 發行版應用程式仍過於著重於 裝載模型 概念，而非轉譯模式。從概念層面來看，轉譯模式適用於 .NET 8 或更新版本中的 Blazor Web App。

以下表格顯示可用於在Razor中渲染Blazor Web App元件的渲染模式。在元件實例或元件定義上使用 @rendermode 指示詞時，渲染模式會套用至該元件。此外也可設定整個應用程式的轉譯模式。

名稱	描述	渲染位置	互動式
靜態伺服器	靜態伺服器端轉譯 (SSR)	伺服器	不
互動式伺服器	使用 Blazor Server 的互動式伺服器端轉譯 (互動式 SSR)	伺服器	是的
互動式 WebAssembly	使用 Blazor WebAssembly 的用戶端轉譯 (CSR)†	客戶	是的
互動式汽車	最初使用 Blazor Server 進行互動式 SSR，然後在下載 Blazor 套件後的後續造訪中使用 CSR。	伺服器，然後用戶端	是的

† 用戶端轉譯 (CSR) 會假設為互動式。在產業界或文件中不使用「互動式用戶端渲染」和「Blazor CSR」。

有關轉譯模式的上述資訊就是您必須知道才能瞭解 基本概念 節點文章的所有資訊。如果您是Blazor的新手並且按照Blazor目錄逐篇閱讀文章，您可以延遲獲取有關轉譯模式的深入資訊，直到到達 [Blazor] 節點中的 ASP.NET Core 轉譯模式一文為止。

文件物件模型 (DOM)

檔物件模型的參考會使用縮寫 DOM。

如需詳細資訊，請參閱以下資源：

適用於 Blazor WebAssembly 應用程式的 .NET API 子集

目前並未選列瀏覽器上支援用於 Blazor WebAssembly 的特定 .NET API。不過，您可以手動搜尋批注的 [UnsupportedOSPlatform("browser")].NET API 清單，以探索 WebAssembly 中不支援的 .NET API。

注意

.NET 參考來源的文件連結通常會載入存放庫的預設分支，這代表著針對下一版 .NET 的開發進度。若要選取特定發行版本的標籤，請使用「切換分支或標籤」下拉式清單。如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼的版本標記（dotnet/AspNetCore.Docs #26205）。

如需詳細資訊，請參閱以下資源：

範例應用程式

文件範例應用程式可供檢查和下載：

Blazor 範例 GitHub 存放庫（dotnet/blazor-samples）

先選取與您使用的 .NET 版本相符的版本資料夾，以找出範例應用程式。

存放庫中的範例應用程式：

Blazor Web App
Blazor WebAssembly
Blazor Web App 電影教學課程範例（建置 Blazor 電影資料庫應用程式（概觀））
Blazor Web App 搭配 SignalR （使用 ASP.NET Core SignalR 搭配 Blazor）
有兩個項目和一個應用程式，可用來透過 ASP.NET Core 應用程式呼叫 Web（伺服器）API（呼叫 Web API）
Blazor Web App搭配 OIDC（使用 OpenID Connect (OIDC) 保護 ASP.NET Core Blazor Web App）
使用 Entra Blazor Web App （Blazor Web App保護 ASP.NET 核心）
Blazor WebAssembly 作用域啟用的日誌（ASP.NET Core Blazor 日誌）
Blazor WebAssembly 搭配 ASP.NET Core Identity （使用 ASP.NET Core Blazor WebAssembly 保護 ASP.NET Core Identity）
.NET MAUI Blazor Hybrid應用程式具有 Blazor Web App 和由 Razor 類別庫（RCL）提供的共享UI （使用 .NET MAUI 建置 Blazor HybridBlazor Web App 應用程式）
其他範例（請參閱 GitHub 存放庫自述檔範例）

存放庫中的範例應用程式：

Blazor Web App
Blazor WebAssembly
Blazor Web App 電影教學課程範例（建置 Blazor 電影資料庫應用程式（概觀））
Blazor Web App 搭配 SignalR （使用 ASP.NET Core SignalR 搭配 Blazor）
有兩個項目和一個應用程式，可用來透過 ASP.NET Core 應用程式呼叫 Web（伺服器）API（呼叫 Web API）
Blazor Web App搭配 OIDC（BFF 和非 BFF 模式）（使用 OpenID Connect 保護 ASP.NET Core Blazor Web App（OIDC）
Blazor WebAssembly 作用域啟用的日誌（ASP.NET Core Blazor 日誌）
Blazor WebAssembly 搭配 ASP.NET Core Identity （使用 ASP.NET Core Blazor WebAssembly 保護 ASP.NET Core Identity）
.NET MAUI Blazor Hybrid應用程式具有 Blazor Web App 和由 Razor 類別庫（RCL）提供的共享UI （使用 .NET MAUI 建置 Blazor HybridBlazor Web App 應用程式）
其他範例（請參閱 GitHub 存放庫自述檔範例）

範例存放庫包含兩種類型的範例：

程式碼片段範例應用程式會提供出現在文章中的程式碼範例。這些應用程式會編譯，但不一定可執行應用程式。這些應用程式僅適用於取得出現在文章中的範例程式碼。
Blazor 文章隨附的範例應用程式會針對下列案例來進行編譯並執行：
- Blazor Server 和 Blazor WebAssembly 與 SignalR
- Blazor WebAssembly 启用範圍記錄

如需詳細資訊，存放庫中的範例清單和下載指示，請參閱 gitHub 存放庫自述檔範例。

ASP.NET Core 存放庫的基本測試應用程式也是各種 Blazor 案例的一組實用範例:

ASP.NET Core 參考來源中的BasicTestApp（dotnet/aspnetcore）

注意

位元組倍數

.NET 位元組大小會根據 1024 的乘冪使用非十進位位元組倍數的計量前置詞。

名稱 (縮寫)	大小	範例
Kbbyte （KB）	1,024 個位元組	1 KB = 1,024 個位元組
MB 位元組	1,024² 個字節	1 MB = 1,048,576 個位元組
千兆位元組（GB）	1,024³ 個字節	1 GB = 1,073,741,824 個位元組

支援要求

只有文件相關問題會適用於 dotnet/AspNetCore.Docs 存放庫。 針對產品支援，請勿開啟文件問題。 透過下列一或多個支援通道尋求協助：

如需架構或產品意見反應中的潛在錯誤，請針對 dotnet/aspnetcore 問題 ASP.NET 核心產品單元提出問題。 Bug 報告通常需要下列 項目：

清楚說明問題：開啟問題時，請遵循產品單位所提供的 GitHub 問題範本中的指示。
最小重現專案：將專案放在 GitHub 上，讓產品單位工程師下載並執行。將專案交叉鏈接至問題的起始評論。

如對 Blazor 文章有潛在問題，請開立一個文件問題。若要開啟文件問題，請使用文章底部的 [開啟文件問題 意見反應] 連結。為您的問題新增的中繼資料提供追蹤資料，並自動通知文章的作者。如果在開啟文件問題之前，產品單元已討論過該主題，請將工程問題的交叉連結放在文件問題的開放式留言中。

如需提供關於 Visual Studio 的問題或意見反應，請在 Visual Studio 中使用回報問題或建議功能選項，以開啟 Visual Studio 的內部問題追蹤。如需詳細資訊，請參閱 Visual Studio意見反應。

如有 Visual Studio Code 問題，請在社群支援論壇上尋求支援。如需 Bug 報告和產品意見反應，請在 GitHub 存放庫上microsoft/vscode提出問題。

GitHub 中的文件問題會自動在專案（ GitHub 存放庫）中標示為需分類。請稍候一會以取得回應，特別是遇到週末和假日時。如果是工作日，文件作者通常會在 24 小時內回應。

社群連結至 Blazor 資源

如需連結至社群所維護的資源集合 Blazor ，請造訪 Awesome Blazor。

注意

Microsoft並不擁有、維護或支援 Awesome Blazor，並且那裡描述和連結的大部分社群產品和服務也是如此。

共用方式為