Hydro Hello World 实战:在 ASP.NET Core 中构建第一个服务端交互组件
Hydro Hello World 实战:在 ASP.NET Core 中构建第一个服务端交互组件
导读
本文基于 practical-aspnetcore 仓库中的 projects/hydro/hello-world 示例,讲解 Hydro 框架的核心概念——HydroComponent 组件模型及其服务端交互机制。你将学会:如何用几行代码定义一个带状态的 Hydro 组件、如何通过 on:click 指令触发服务端方法调用并自动刷新页面片段、以及组件与 Razor Pages 路由、Tag Helper、布局页之间的协作关系。阅读完本文后,你能够独立搭建一个最小的 Hydro 应用,并为后续学习组件嵌套、事件派发与生命周期钩子打下基础。
Hydro 是什么:一个服务端优先的 ASP.NET Core 组件框架
Hydro 是一个面向 ASP.NET Core 的服务端组件框架,它的核心思想是:把交互状态保存在服务器端,通过轻量级请求驱动页面局部更新。与 Blazor Server 类似,Hydro 组件在服务端渲染,但它的消息传递和 DOM 更新方式更接近传统的 HTML/JavaScript 工作流——每个组件即是一个 Razor 视图(.cshtml)配一个继承自 HydroComponent 的代码隐藏类(.cshtml.cs)。
在 practical-aspnetcore 仓库中,Hydro 是一个独立主题目录,包含 8 个递进式示例。其中 hello-world 是整套示例的起点,仓库根 hydro/README.md 用一句话概括了它的定位:
This sample introduces the usage of a Hydro component.
也就是说,本文要讲透的正是"一个 Hydro 组件到底是什么、它是如何做到交互的"。
项目结构与最小组成
先看 hello-world 项目的完整文件布局(来源:projects/hydro/hello-world):
hello-world/
├── Pages/
│ ├── Components/
│ │ ├── Message.cshtml # 组件视图(Razor 标记)
│ │ └── Message.cshtml.cs # 组件逻辑(HydroComponent 子类)
│ ├── Shared/
│ │ └── _Layout.cshtml # 布局页,挂载 hydro.js 与 alpine.js
│ ├── Index.cshtml # 根页面,承载 <message> 组件
│ └── _ViewImports.cshtml # Tag Helper 注册
├── Program.cs # 应用入口,注册并启用 Hydro
├── hello-world.csproj # 项目文件,引用 Hydro 1.3.0
└── hello-world.sln
一个 Hydro 应用的最小骨架由四部分组成:
- 一个继承
HydroComponent的 C# 类:持有状态(属性)并暴露可被视图调用的方法; - 一个与该类同名的 Razor 视图(
.cshtml):声明组件标记,用@Model访问组件状态,用on:click等指令绑定交互; - 一个使用组件的页面:通过自定义 Tag Helper(如
<message></message>)把组件嵌入页面; - Program.cs 中的两行 Hydro 注册代码:
AddHydro()与UseHydro()。
三个文件看懂组件模型
1. 组件代码隐藏类:状态与行为
Message.cshtml.cs 是组件的全部逻辑,完整代码如下:
using Hydro;
namespace HelloWorld.Pages.Components;
public class Message : HydroComponent
{
public string Text { get; set; }
public void Show(string text)
{
Text = text;
}
}
这里揭示了 Hydro 组件模型的三个关键约定:
- 命名约定:类名
Message与视图文件Message.cshtml同名同目录,Hydro 借此把两者关联成一个组件;页面中通过<message>标签(小写化类名)使用它。 - 状态即属性:
Text是一个普通 C# 属性,它就是组件的状态。属性值默认绑定在服务器端,渲染时写入 HTML。 - 方法即事件处理器:
Show(string text)是普通公共方法。当客户端触发对应交互时,Hydro 在服务端找到该组件实例、调用Show、更新Text,然后重新渲染组件对应的 DOM 片段返回给浏览器。这正是"服务端交互"的本质。
2. 组件视图:标记与指令绑定
Message.cshtml 是组件的可视化部分:
@model HelloWorld.Pages.Components.Message
<div>
<h1>@Model.Text</h1>
<button on:click="@(() => Model.Show("Hello World"))">Show</button>
</div>
值得注意的细节:
@model指令指向组件的代码隐藏类Message,因此视图中可以直接通过@Model.Text输出组件状态;on:click是 Hydro 提供的 DOM 事件绑定指令,其值是一个 C# 表达式() => Model.Show("Hello World")。点击按钮后,浏览器把该事件连同参数序列化发送到服务端,由 Hydro 执行对应方法并局部更新<div>内的内容;- 视图中的
<div>就是该组件在页面上的"更新边界"——组件重渲染时只替换自己管理的这段 DOM。
3. 页面承载:Tag Helper 组件用法
Index.cshtml 是一个标准的 Razor Page:
@page "/"
@using Hydro
@{
Layout = "/Pages/Shared/_Layout.cshtml";
}
<message></message>
页面本身没有任何业务逻辑,只负责把 Message 组件挂载到根路由 / 上。组件之所以能被当作 <message> 标签使用,靠的是 _ViewImports.cshtml 中的两行注册:
@addTagHelper *, Hydro
@addTagHelper *, HelloWorld
*, Hydro:注册 Hydro 框架自带的指令解析 Tag Helper(处理on:click等指令);*, HelloWorld:注册程序集HelloWorld(即本项目,见 hello-world.csproj 的AssemblyName)中所有继承HydroComponent的组件,使其变为可用的自定义标签。
注册与启用:Program.cs 的两行代码
Program.cs 展示了在 ASP.NET Core 最小托管模型中接入 Hydro 的完整流程:
using Hydro.Configuration;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHydro(); // Hydro
var app = builder.Build();
app.UseStaticFiles();
app.UseRouting();
app.MapRazorPages();
app.UseHydro(); // Hydro
app.Run();
与普通 Razor Pages 应用相比,只多了两行:
builder.Services.AddHydro():向依赖注入容器注册 Hydro 所需的服务(组件工厂、指令处理器、消息管线等),该方法位于Hydro.Configuration命名空间;app.UseHydro():在中间件管线中挂载 Hydro 的请求处理中间件,负责处理组件交互请求。
必须遵守的顺序约束:UseHydro() 应放在 UseRouting() 之后、MapRazorPages() 之后,确保交互请求能被 Hydro 中间件正确接管。如果忘记调用 AddHydro() 或 UseHydro(),组件页面可以正常渲染,但点击 on:click 按钮不会产生任何交互效果。
布局页与客户端脚本:交互的另一半
Hydro 的交互依赖两个客户端脚本,它们统一在 _Layout.cshtml 中加载:
<html>
<head>
<meta name="hydro-config" />
<script defer src="~/hydro/hydro.js" asp-append-version="true"></script>
<script defer src="~/hydro/alpine.js" asp-append-version="true"></script>
</head>
<body>
@RenderBody()
<script src="/_framework/aspnetcore-browser-refresh.js"></script>
</body>
</html>
三个要点:
<meta name="hydro-config" />:Hydro 的配置占位符,框架运行时会把必要的配置注入该元素;hydro.js:Hydro 运行时,负责拦截on:click等指令、发起组件交互请求并把服务端返回的新 DOM 应用到页面;alpine.js:Hydro 内置了对 Alpine.js 的集成,供后续示例(如data-*响应式指令)使用。hello-world 虽未直接使用 Alpine 指令,但加载它是 Hydro 标准布局的组成部分。
此外,asp-append-version="true" 为脚本 URL 附加版本指纹,便于静态资源变更后浏览器能及时刷新缓存。
运行与验证
在仓库根目录按顺序执行以下命令即可体验(示例目标框架为 .NET 10,见 global.json 中的 SDK 版本 10.0.0):
# 1. 还原依赖
dotnet restore projects/hydro/hello-world/hello-world.csproj
# 2. 运行应用
dotnet run --project projects/hydro/hello-world/hello-world.csproj
应用启动后,在浏览器打开根地址(默认 http://localhost:5000),页面显示一个空标题和一个 Show 按钮。点击按钮后,Text 属性被设置为 "Hello World",标题立即更新为 Hello World——整个过程没有整页刷新,只有组件所在 DOM 片段被替换。
如果按 Ctrl+F5 强制刷新,标题会重新变为空,这印证了一个重要事实:组件状态只保存在服务器端的组件实例中,客户端刷新页面会重建整个组件,状态随之重置。要持久化状态,需要配合 Session、Cookie 或数据库等机制(仓库中的 cookies 示例演示了如何在组件中读写 Cookie)。
从 Hello World 延伸:Hydro 的进阶能力
hello-world 演示了组件交互的最小闭环,而 hydro 目录下的其他示例恰好围绕它逐层展开,可作为后续学习路径:
- component-1:组件嵌套与父子数据流。父组件
Container通过<message text="@Model.Text">向子组件传参;同时演示key属性的作用——Container.cshtml 中不带key的子组件在父状态变化时不更新,带key="@Model.Text"的子组件则随父状态重新渲染; - component-3:组件生命周期钩子。通过覆写
Mount/MountAsync与Render/RenderAsync在挂载和渲染阶段注入逻辑,Message.cshtml.cs 展示了四个钩子的完整用法; - event-child-parent:子组件通过
Dispatch(new MessageChangedEvent(text))向父组件派发事件,父组件在构造函数中用Subscribe<MessageChangedEvent>(e => ...)订阅(见 Message.cshtml.cs); - event-global:通过
DispatchGlobal派发全局事件,任何订阅了该事件类型的组件都能收到; - event-global-subject:在全局事件基础上按
subject过滤,实现精准定向通知。
这些示例共同勾勒出 Hydro 的能力边界:服务端状态管理、组件化复用、事件驱动通信、生命周期控制,全部建立在"普通 C# 类 + Razor 视图"的简单模型之上。
小结
通过 hello-world 这个最小示例,可以提炼出 Hydro 的核心心智模型:
- 组件 = 状态类 + 视图:
HydroComponent子类管理状态与方法,同名.cshtml负责渲染,两者靠命名约定绑定; - 交互 = 服务端方法调用:
on:click等指令把浏览器事件映射为服务端方法执行,Hydro 负责局部 DOM 更新,开发者无需手写任何 JavaScript; - 接入成本极低:只需
AddHydro()+UseHydro()两行代码,即可让现有 Razor Pages 应用获得组件化交互能力。
无论是用于原型验证还是生产项目,理解这个最小闭环都是掌握 Hydro 的第一步——后续的嵌套、事件、生命周期等高级特性,本质上都是在"服务端组件实例"这个模型上叠加能力。