ASP.NET Core Blazor 基础知识

项目
11/19/2024

说明

此版本不是本文的最新版本。有关当前版本，请参阅本文的 .NET 9 版本。

警告

此版本的 ASP.NET Core 不再受支持。有关详细信息，请参阅 .NET 和 .NET Core 支持策略。有关当前版本，请参阅本文的 .NET 9 版本。

重要

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

有关当前版本，请参阅本文的 .NET 9 版本。

基础知识文章提供了有关基础 Blazor 概念的指导。其中一些概念与对 Razor 组件的基本了解有关，本文的下一部分将进一步介绍这些概念，并在“组件”文章中进行详细介绍。

静态和交互式呈现概念

Razor 组件是静态呈现的，也可以以交互方式呈现。

静态或静态呈现是一种服务器端方案，这意味着组件在用户和 .NET/C# 代码之间没有交互能力的情况下呈现。 JavaScript 和 HTML DOM 事件不受影响，但是客户端上的任何用户事件都不能使用服务器上运行的 .NET 进行处理。

交互式或交互式呈现意味着组件有能力通过 C# 代码处理 .NET 事件。 .NET 事件在服务器上由 ASP.NET Core 运行时处理，或者在客户端的浏览器中由基于 WebAssembly 的 Blazor 运行时处理。

重要

使用 Blazor Web App 时，大多数 Blazor 文档示例组件需要交互性才能运行并演示文章中涵盖的概念。测试某篇文章提供的示例组件时，请确保应用采用全局交互性或组件采用交互式呈现模式。

有关这些概念以及如何控制静态和交互式呈现的详细信息，请参阅稍后 Blazor 文档中的 ASP.NET Core Blazor 呈现模式文章。

客户端和服务器呈现概念

在整个 Blazor 文档中，发生在用户系统上的活动被称为发生在客户端上或客户端侧。发生在服务器上的活动被称为发生在服务器上或服务器侧。

术语呈现意味着生成浏览器显示的 HTML 标记。

客户端呈现 (CSR) 意味着最终 HTML 标记由客户端上的 .NET WebAssembly 运行时生成。对于这种类型的呈现，应用的客户端生成的 UI 没有 HTML 从服务器发送到客户端。假定用户可与页面交互。没有静态客户端呈现之类的概念。 CSR 假定是交互式的，因此行业或 Blazor 文档中不使用“交互式客户端呈现”和“交互式 CSR”。
服务器侧呈现 (SSR) 意味着最终 HTML 标记由服务器上的 ASP.NET Core 运行时生成。 HTML 通过网络发送到客户端，供客户端的浏览器显示。对于这种类型的呈现，客户端不会为应用的服务器生成的 UI 创建 HTML。 SSR 可以是两种类型：
- 静态 SSR：服务器生成静态 HTML，它不提供用户交互性或维护 Razor 组件状态。
- 交互式 SSR：Blazor 事件允许用户交互，并且 Razor 组件状态由 Blazor 框架维护。
预呈现是最初在服务器上呈现页面内容的过程，而无需为呈现的控件启用事件处理程序。服务器会根据初始请求尽快输出页面的 HTML UI，这会让应用感觉对用户的响应更强。预呈现还可以通过呈现搜索引擎可用来计算网页排名的初始 HTTP 响应的内容，来改进搜索引擎优化 (SEO)。在服务器或客户端上，预呈现始终后跟最终呈现。

Razor 组件

Blazor 应用基于 Razor 组件，通常仅称为组件。组件是 UI 的一个元素，例如页面、对话框或数据输入窗体。组件是内置到 .NET 程序集的 .NET C# 类。

Razor 是指组件通常以 Razor 标记页面的形式编写，用于客户端 UI 逻辑和组合。 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 设置为小写横线格式大小写中组件的类名。例如，FileUpload 组件包含路由配置，以在相对 URL /file-upload 处到达呈现的组件。路由和导航在 ASP.NET Core Blazor 路由和导航中进行了介绍。
当使用一个组件的多个版本时，它们会按顺序编号。例如，FileUpload3 组件位于 /file-upload-3 下。
组件定义 (.razor file) 顶部的 Razor 指令按以下顺序放置：@page、@rendermode（.NET 8 或更高版本）、@using 语句、其他按字母顺序排列的指令。
虽然 private 成员不需要，但文章示例和示例应用中会使用访问修饰符。例如，private 用于将名为 maxAllowedFiles 的字段声明为 private int maxAllowedFiles = 3;。
组件参数值以 Razor 保留 @ 符号开头，但这不是必需的。文本（例如布尔值）、关键字（例如 this）和 null 组件参数值未使用前缀 @，但这只是文档约定。如果愿意，可以给自己的代码文本添加 @ 前缀。
C# 类使用 this 关键字并避免在构造函数中分配的字段前加下划线 (_)，这与 ASP.NET Core 框架工程指南不同。
在使用主构造函数（C# 12 或更高版本）的示例中，主构造函数参数通常由类成员直接使用。

有关 Razor 组件语法的更多信息，请参阅 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 变量的值。

呈现模式

“基础”节点中的文章引用了呈现模式的概念。 “组件”节点中的 ASP.NET Core Blazor 呈现模式文章中详细介绍了此主题，其出现在“基础”文章节点之后。

对于本文章节点中关于呈现模式概念的早期引用，此时只需注意以下内容：

Blazor Web App 中的每个组件都采用呈现模式来确定其使用的托管模型、呈现位置，以及是否在服务器上静态呈现、在服务器上呈现以实现用户交互，还是在客户端上呈现以实现用户交互（通常是在服务器上预呈现）。

.NET 8 之前的 ASP.NET Core 版本的 Blazor Server 和 Blazor WebAssembly 应用仍专注于承载模型概念，而不是呈现模式。呈现模式在概念上应用于 .NET 8 或更高版本中的 Blazor Web App。

下表显示了用于呈现 Blazor Web App 中 Razor 组件的可用呈现模式。呈现模式通过 @rendermode 指令应用于组件实例或组件定义上的组件。还可以为整个应用设置呈现模式。

名称	描述	呈现位置	交互
静态服务器	静态服务器端呈现（静态 SSR）	服务器	否
交互式服务器	使用 Blazor Server 的交互式服务器端呈现（交互式 SSR）	服务器	是
交互式 WebAssembly	使用 Blazor WebAssembly 的客户端呈现 (CSR)†	客户端	是
交互式自动	下载 Blazor 捆绑包后，在后续访问时先使用 Blazor Server 然后使用 CSR 的交互式 SSR	服务器，然后客户端	是

†客户端呈现 (CSR) 假定为交互式。行业或 Blazor 文档中不使用“交互式客户端呈现”和“交互式 CSR”。

有关呈现模式的上述信息是了解“基础”节点文章所需的全部信息。如果不熟悉 Blazor，并且按照目录的顺序阅读 Blazor 文章，则可以推迟阅读有关呈现模式的深入信息，直到到达“组件”节点中的 ASP.NET Core Blazor 呈现模式文章。

文档对象模型 (DOM)

对文档对象模型的引用使用缩写 DOM。

有关更多信息，请参见以下资源：

适用于 Blazor WebAssembly 应用的部分 .NET API

目前还没有适用于 Blazor WebAssembly 的浏览器上支持的特定 .NET API 的精选列表。但是，可以手动搜索带有注释的 .NET API 列表[UnsupportedOSPlatform("browser")]，发现 WebAssembly 中不支持的 .NET API。

注意

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

有关更多信息，请参见以下资源：

示例应用

文档示例应用可用于检查和下载：

Blazor 示例 GitHub 存储库 (dotnet/blazor-samples)

首先选择与正在使用的 .NET 版本匹配的版本文件夹，找到示例应用。

存储库中的示例应用：

Blazor Web App
Blazor WebAssembly
具有 EF Core 的 Blazor Web App（具有 Entity Framework Core (EF Core) 的 ASP.NET Core Blazor）
具有 SignalR 的 Blazor Web App（将 ASP.NET Core SignalR 与 Blazor 结合使用）
两个 Blazor Web App 和一个用于调用 Web（服务器）API 的 Blazor WebAssembly 应用（从 ASP.NET Core Blazor 应用调用 Web API）
具有 OIDC（BFF 和非 BFF 模式）的 Blazor Web App（使用 OpenID Connect (OIDC) 保护 ASP.NET Core Blazor Web App）
Blazor WebAssembly 已启用范围的日志记录（ASP.NET CoreBlazor 日志记录）
具有 ASP.NET Core Identity 的 Blazor WebAssembly（使用 ASP.NET Core Identity 保护 ASP.NET Core Blazor WebAssembly 的安全）
具有 Blazor Web App 和由 Razor 类库 (RCL) 提供的共享 UI 的 .NET MAUIBlazor Hybrid 应用（使用 Blazor Web App 生成 .NET MAUIBlazor Hybrid 应用）

示例存储库包含两种类型的示例：

代码片段示例提供文章中出现的代码示例。这些应用可执行编译，但不一定是可运行的应用。这些应用仅用于获取文章中显示的示例代码。
Blazor 文章中随附的示例应用用于编译和运行以下方案：
- 使用 EF Core 的 Blazor Server
- Blazor Server 和使用 SignalR 的 Blazor WebAssembly
- Blazor WebAssembly 启用了范围的日志记录

有关详细信息和存储库中的示例列表，请参阅 Blazor GitHub 存储库 README.md 文件的示例。

ASP.NET Core 存储库的基本测试应用也是一组适用于各种 Blazor 方案的有用示例：

ASP.NET Core 中 BasicTestApp 的引用源 (dotnet/aspnetcore)

说明

若要下载示例应用：

下载 Blazor 示例存储库 ZIP 文件。
解压缩文件。

字节倍数

.NET 字节大小使用基于 1024 的幂的非十进制字节倍数的国际单位制词头。

名称（缩写）	大小	示例
千字节 (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 存储库。对于产品支持，不要打开文档问题。请通过以下一个或多个支持渠道寻求帮助：

对于框架或产品反馈中的潜在 bug，请在遇到 dotnet/aspnetcore 问题时向 ASP.NET Core 产品团队提交问题。 Bug 报告通常需要以下各项：

问题的清晰解释：提交问题时，请按照产品团队提供的 GitHub 问题模板中的说明进行操作。
最小重现项目：在 GitHub 上放置一个项目，供产品团队工程师下载和运行。将项目交叉链接到问题的开始注释。

有关 Blazor 文章的潜在问题，请打开文档问题。若要打开文档问题，请使用文章底部的打开文档问题反馈链接。添加到问题中的元数据提供跟踪数据，并自动对文章作者进行 ping 操作。如果在打开文档问题之前已与产品单位讨论过该主题，请在文档问题的开始注释中放置工程问题的交叉链接。

如有关于 Visual Studio 的问题或反馈，请使用报告问题或从 Visual Studio 中使用建议功能手势，这将打开 Visual Studio 的内部问题。有关详细信息，请参阅 Visual Studio 反馈。

有关 Visual Studio Code 的问题，请在社区支持论坛上寻求支持。对于 bug 报告和产品反馈，请在 microsoft/vscodeGitHub 存储库上提出问题。

Blazor 文档的 GitHub 问题会自动标记为在 Blazor.Docs 项目（dotnet/AspNetCore.Docs GitHub 存储库）上进行分类。请等待回复，尤其是在周末和节假日。通常，文档作者会在工作日的 24 小时内回复。

Blazor 资源的社区链接

有关社区维护的 Blazor 资源的链接集合，请访问令人惊叹的 Blazor。

说明

Microsoft 不拥有、维护或支持“令人惊叹的 Blazor”以及其中描述和链接的大多数社区产品和服务。

通过