Hydro Hello World 实战:在 ASP.NET Core 中构建第一个服务端交互组件

原创2026-10-14 13:45:341,739 阅读
文章标签:示例工程

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 应用的最小骨架由四部分组成:

  1. 一个继承 HydroComponent 的 C# 类:持有状态(属性)并暴露可被视图调用的方法;
  2. 一个与该类同名的 Razor 视图(.cshtml):声明组件标记,用 @Model 访问组件状态,用 on:click 等指令绑定交互;
  3. 一个使用组件的页面:通过自定义 Tag Helper(如 <message></message>)把组件嵌入页面;
  4. 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 的核心心智模型:

  1. 组件 = 状态类 + 视图:HydroComponent 子类管理状态与方法,同名 .cshtml 负责渲染,两者靠命名约定绑定;
  2. 交互 = 服务端方法调用:on:click 等指令把浏览器事件映射为服务端方法执行,Hydro 负责局部 DOM 更新,开发者无需手写任何 JavaScript;
  3. 接入成本极低:只需 AddHydro() + UseHydro() 两行代码,即可让现有 Razor Pages 应用获得组件化交互能力。

无论是用于原型验证还是生产项目,理解这个最小闭环都是掌握 Hydro 的第一步——后续的嵌套、事件、生命周期等高级特性,本质上都是在"服务端组件实例"这个模型上叠加能力。

登录后查看全文
practical-aspnetcore