practical-aspnetcore 之 Hydro 实战:用 C 编写交互式服务器端组件

原创2026-10-14 13:35:163,304 阅读
文章标签:示例工程

practical-aspnetcore 之 Hydro 实战:用 C# 编写交互式服务器端组件

Hydro 是一个面向 ASP.NET Core 的服务器端组件框架:你既不需要写大量 JavaScript,也不需要把应用切分成前后端两套工程,只需在 Razor 视图(.cshtml)与 C# 类之间组合出可交互的 UI 组件,浏览器端通过 WebSocket 与服务器保持同步。在 practical-aspnetcore 仓库的 projects/hydro 模块中,官方以 8 个递进式示例完整演示了 Hydro 的核心能力:组件定义、父子事件、全局事件、事件主题过滤、Cookie 读写、组件嵌套、数据流与生命周期钩子。读完本文,你将掌握在 ASP.NET Core 项目中从零接入 Hydro、编写可交互组件并完成组件间通信的完整实战方案。

一、Hydro 模块总览与示例地图

projects/hydro 目录下每个子目录都是一个独立可运行的 ASP.NET Core 示例工程,遵循"一个示例讲透一个主题"的渐进式设计:

示例目录 核心主题
hello-world Hydro 组件的基本概念与交互性处理
event-child-parent 子组件向父组件派发事件
event-global 全局事件广播,任意订阅组件均可接收
event-global-subject 按事件主题(subject)过滤事件
cookies 在组件中读写 Cookie,并配合重定向导航
component-1 组件嵌套、父子数据流与 key 参数
component-2 多层嵌套渲染的微妙细节
component-3 通过 Mount/MountAsync、Render/RenderAsync 接入生命周期

二、Hello World:第一个 Hydro 组件

2.1 三步接入 Hydro

打开 hello-world/Program.cs,可以看到 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();
  • AddHydro():把 Hydro 所需的组件发现、依赖注入、事件订阅等能力注册进容器;
  • UseHydro():作为中间件插入请求管线,负责拦截组件交互请求并返回增量更新;
  • Hydro 构建在 Razor Pages 之上,因此 AddRazorPages() 与 MapRazorPages() 必不可少。

工程文件 hello-world.csproj 使用 Microsoft.NET.Sdk.Web,目标框架为 net10.0,核心依赖只有一个 NuGet 包:

<PackageReference Include="Hydro" Version="1.3.0" />

2.2 组件由什么组成

在 Hydro 中,一个组件 = 一个继承 HydroComponent 的 C# 类 + 一个同名的 .cshtml 模板。看 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;
    }
}

组件类的公开属性(Text)就是组件的状态,公开方法(Show)就是组件的动作。模板 Message.cshtml 则负责把状态渲染出来,并把用户的点击绑定到动作上:

@model HelloWorld.Pages.Components.Message

<div>
    <h1>@Model.Text</h1>
    <button on:click="@(() => Model.Show("Hello World"))">Show</button>
</div>

这里的关键是 on:click 指令:它把按钮的点击事件直接绑定到 C# 方法 Model.Show("Hello World")。点击后,Show 修改了 Text 属性,Hydro 检测到状态变化,只把 h1 中的文本增量同步到浏览器——整个过程你完全不需要手写 JavaScript。

2.3 在页面中放置组件

组件以自定义标签形式出现在 Razor 页面中,例如 Index.cshtml:

@page "/"
@using Hydro
@{
    Layout = "/Pages/Shared/_Layout.cshtml";
}

<message></message>

要让 <message> 标签能被识别,需要在 _ViewImports.cshtml 中声明 Tag Helper:

@addTagHelper *, Hydro
@addTagHelper *, HelloWorld
@using HelloWorld.Pages.Components
  • @addTagHelper *, Hydro:启用 Hydro 框架自身提供的组件标签解析;
  • @addTagHelper *, HelloWorld:HelloWorld 是程序集名(见 hello-world.csproj 中的 <AssemblyName>HelloWorld</AssemblyName>),它让本项目内所有组件类都能按 <message> 这种小写命名约定被解析。

另外,_Layout.cshtml 里有两个 Hydro 运行所必需的引用,任何一个缺失都会导致交互失效:

<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>

hydro.js 负责建立 WebSocket 连接与执行增量 DOM 更新,alpine.js 为 Hydro 的事件与数据绑定提供底层支持。

三、组件间事件通信

3.1 子组件向父组件派发事件

event-child-parent 演示的是最基础的事件流:子组件触发事件,父组件订阅并更新自己。

事件本身只是一个 record 类型,见 MessageChangedEvent.cs:

namespace Events.Pages.Components;

public record MessageChangedEvent(string Message);

父组件 Message.cshtml.cs 在构造函数中订阅该事件,收到事件后更新自己的 Text:

public Message()
{
    Subscribe<MessageChangedEvent>(e => Text = e.Message);
}

子组件 MessageButton.cshtml.cs 在动作中调用 Dispatch 把事件派发出去:

public void Show(string text)
{
    Dispatch(new MessageChangedEvent(text));
}

默认情况下 Dispatch 只将事件投递给订阅该事件的直接父组件链路。父组件 Message.cshtml 中通过 <message-button/> 标签嵌套子组件:

<div>
    <h1>@Model.Text</h1>
    <message-button/>
</div>

这里有一个 README 特别提醒的实战坑:在 MessageButton.cshtml 中,不能把 <button> 直接作为组件的根标签,否则点击后按钮会因组件的重新渲染而"消失"(根元素被整体替换)。必须用一个容器标签包裹,让按钮在重渲染后得以保留:

<div>
    <button on:click="@(() => Model.Show("This greeting comes from MessageButton component"))">Show</button>
</div>

3.2 全局事件:任何订阅组件都能接收

event-global 把事件的作用范围从"父子之间"扩展到"全局"。子组件 MessageButton.cshtml.cs 只需把 Dispatch 换成 DispatchGlobal:

public void Show(string text)
{
    DispatchGlobal(new MessageChangedEvent(text));
}

页面 Index.cshtml 中放入了两个 Message 组件实例和一个 MessageButton:

<div class="container">
    <div class="row">
        <div class="col-md-6">
            <message></message>
        </div>
        <div class="col-md-6">
            <message></message>
        </div>
    </div>
    <message-button/>
</div>

两个 Message 实例都在构造函数里 Subscribe<MessageChangedEvent>(e => Text = e.Message)(见 Message.cshtml.cs),因此点击按钮后,两个实例会同时更新——这就是"全局广播"的直观体现。对比 3.1 节可以看出 Dispatch 与 DispatchGlobal 在投递范围上的本质区别。

3.3 按主题(subject)过滤事件

event-global-subject 在全局事件之上引入了主题过滤:订阅方声明自己关心的 subject,派发方在派发时携带 subject,只有两者匹配的事件才会被投递。

订阅方 Message.cshtml.cs 用 subject: 命名参数声明过滤条件,Filter 是组件的公开属性:

public string Filter { get; set; }

public Message()
{
    Subscribe<MessageChangedEvent>(subject: () => Filter , e => Text = e.Message);
}

派发方 MessageButton.cshtml.cs 随机挑选 "left" 或 "right" 作为 subject 随事件一起广播:

public void Show(string text)
{
    var r = Random.Shared.GetItems(["left", "right"], 1);
    DispatchGlobal(new MessageChangedEvent(text), subject:r[0]);
}

页面上两个组件实例分别被赋予不同的 filter 值(见 Index.cshtml):

<message filter="left"></message>
<message filter="right"></message>

运行后点击按钮,两个组件会因为收到的 subject 不同而各自更新、互不干扰——这正是主题过滤在"多个同类组件共存"场景下的价值。

四、在组件中读写 Cookie

cookies 示例演示了两件事:组件内读写 Cookie,以及用全局事件 + 页面重定向完成状态提示。

CookieControl.cshtml.cs 通过 CookieStorage 服务直接操作 Cookie:

public class CookieControl : HydroComponent
{
    public bool ShowSetCookies { get; set; }

    /// <summary>
    /// Called when the component is instantiated on the page
    /// </summary>
    public override void Mount()
    {
        var msg = CookieStorage.Get<string>("date");
        ShowSetCookies = string.IsNullOrWhiteSpace(msg);
    }

    public void SetCookie()
    {
        CookieStorage.Set("date", DateTime.Now.ToString());
        Dispatch(new MessageUpdatedEvent("A cookie is now set"), scope: Scope.Global);
        Redirect(Url.Page("/Index")); // Url.Page is a helper method to generate a URL to a Razor page. It starts from /Pages folder.
    }

    public void RemoveCookie()
    {
        CookieStorage.Delete("date");
        Dispatch(new MessageUpdatedEvent("Cookie removed"), scope: Scope.Global);
        Redirect(Url.Page("/Index"));
    }
}

值得注意的实现细节:

  • CookieStorage.Get<string>("date") 读取名为 date 的 Cookie 并反序列化为 string;
  • CookieStorage.Set(...)、CookieStorage.Delete(...) 分别对应写入与删除;
  • 这里 Dispatch(..., scope: Scope.Global) 与 3.2 节的 DispatchGlobal(...) 效果等价——全局作用域也可以通过命名参数显式指定;
  • Redirect(Url.Page("/Index")) 生成指向 /Pages/Index 页面的 URL 并执行重定向,Url.Page 是 Razor Pages 内置的 URL 生成辅助方法。

视图 CookieControl.cshtml 根据 ShowSetCookies 切换按钮文案:

@if(Model.ShowSetCookies){
    <button class="btn btn-primary" on:click="@(() => Model.SetCookie())">Set New Cookie</button>
}else{
    <button class="btn btn-primary" on:click="@(() => Model.RemoveCookie())">Remove Cookie</button>
}

同时,页面上的 Message 组件(见 Message.cshtml.cs)订阅了 MessageUpdatedEvent 来展示操作结果,并在 Mount 中读取同一 Cookie 初始化文本:

public override void Mount()
{
    var msg = CookieStorage.Get<string>("date");

    if (!string.IsNullOrWhiteSpace(msg))
        Text = msg;
    else
        Text = "No cookies set";
}

由于 SetCookie/RemoveCookie 都带着 Scope.Global 派发事件并随后重定向,页面刷新后 Mount 会重新执行,形成"写入 → 全局通知 → 刷新 → 读回展示"的完整闭环。

五、组件嵌套与数据流

5.1 key 参数:父组件如何把变化"推"给子组件

component-1 解决了一个 Hydro 新手最容易困惑的问题:父组件属性变了,子组件为什么不跟着变?

父组件 Container.cshtml.cs 持有一个 Text 属性,按钮把它改成当前 UTC 时间:

public class Container : HydroComponent
{
    public string Text { get; set; } = "Hello, World!";

    public void Show(string text)
    {
        Text = text;
    }
}

在 Container.cshtml 中声明了两个 message 子组件,都接收 text="@Model.Text",唯一区别是第二个带 key:

<!-- 不用 key:父属性修改不会传播到子组件 -->
<message text="@Model.Text"></message>

<!-- 用 key:key 变化会强制子组件重新渲染 -->
<message text="@Model.Text" key="@Model.Text"></message>

示例中的说明文字写得很明确:"Without the key attribute, the modification of the parent property is not propagated to the child component."(不使用 key 属性,父组件属性的修改不会传播到子组件。)

其背后可以这样理解:Hydro 为每个组件实例维护一个"身份",默认情况下子组件一旦挂载,其内部状态就与父组件参数解耦;而 key 值参与组件的身份判定,当 key 变化时 Hydro 会重建该子组件实例,从而用最新的属性值重新初始化它。运行该示例即可看到:点击按钮后,右侧带 key 的子组件文本立即变为 UTC 时间,左侧不带 key 的保持不变。

5.2 两层嵌套:key 用在哪一层

component-2 把嵌套加深一层,演示 key 的精确使用位置。组件结构为:container(父)→ message(子)→ inner-message(孙)。

  • 父组件 container 持有 Text,通过 <message text="@Model.Text" key="@Model.Text"> 传给 message(见 Container.cshtml);
  • message 组件有两个属性 Text 和 Text2,模板 Message.cshtml 中声明了两个 inner-message:
<!-- 第一个:绑定 Model.Text,由 container 传入,无需 key -->
<inner-message text="@Model.Text"></inner-message>

<!-- 第二个:绑定 Model.Text2,由 message 自身通过按钮改变,需要 key -->
<inner-message text="@Model.Text2" key="@Model.Text2"></inner-message>

关键推理在于数据变化的源头:

  • Text 由最外层 container 传入。当 container 的 Text 变化时,message 组件的 key 跟着变化,Hydro 会整体重建 message,重建时其内部所有 inner-message 都会以最新属性重新初始化,所以第一个 inner-message 不需要自己的 key;
  • Text2 则由 message 组件内部的按钮(TriggerRender 方法)自己修改,这个修改发生在 message 内部,不会触发 message 自身重建。若第二个 inner-message 不带 key,它就会保持旧状态不更新,因此必须用 key="@Model.Text2" 强制它在值变化时重新渲染。

示例 Index.cshtml 的说明指出:"The same principle applies to unlimited nested components"(同样的原理适用于任意层级的嵌套)。记忆口诀:key 加在"属性值会被同层或上层组件自身修改"的那个子组件上,而属性值来自更高层重建动作的子组件通常不需要 key。

六、组件生命周期:Mount 与 Render 钩子

component-3 演示 Hydro 组件生命周期的四个可重写钩子:Mount、MountAsync、Render、RenderAsync。

完整重写四个钩子的 Message.cshtml.cs:

public class Message : HydroComponent
{
    public string Text { get; set; }
    public string Text2 { get; set; }

    public override void Mount()
    {
        Text = "From Mount";
    }

    public override Task MountAsync()
    {
        Text = "From MountAsync";
        return Task.CompletedTask;
    }

    public override void Render()
    {
        Text2 = "From Render";
    }

    public override Task RenderAsync()
    {
        Text2 = "From RenderAsync";
        return Task.CompletedTask;
    }

    public void TriggerRender()
    {
        Text2 = "Render Triggered";
    }
}

同时只重写同步版本的 Message2.cshtml.cs 作为对照组:

public class Message2 : HydroComponent
{
    public string Text { get; set; }
    public string Text2 { get; set; }

    public override void Mount()
    {
        Text = "From Mount";
    }

    public override void Render()
    {
        Text2 = "From Render";
    }

    public void TriggerRender()
    {
        Text2 = "Render Triggered";
    }
}

Container.cshtml 中明确点出了执行顺序:"This demonstrates that MountAsync is called after Mount and RenderAsync is called after Render."(MountAsync 在 Mount 之后调用,RenderAsync 在 Render 之后调用。)

由此可以推导各钩子的语义与职责:

钩子 触发时机 典型用途
Mount / MountAsync 组件实例化(挂载)时 初始化数据、读取 Cookie、加载依赖(见 cookies 中的 Mount 用法)
Render / RenderAsync 每次渲染输出前 在渲染前对属性做最终加工

由于 MountAsync 在 Mount 之后执行、RenderAsync 在 Render 之后执行,运行时 Message 组件的最终状态是:Text = "From MountAsync"、Text2 = "From RenderAsync"(后执行的钩子覆盖先执行的赋值)。需要异步初始化(如读取数据库、调用远程服务)时,优先在 MountAsync/RenderAsync 中完成;同步钩子则适合轻量初始化。其余交互动作(如 TriggerRender)由用户在事件方法中显式触发,不会额外经过 Mount。

七、如何运行这些示例

所有 Hydro 示例都是标准 ASP.NET Core Web 工程,运行方式一致:

cd projects/hydro/hello-world   # 换成任意示例目录
dotnet run

前提条件:

  • 安装了与工程目标框架匹配的 .NET SDK(示例目标框架为 net10.0,且工程启用了 <LangVersion>preview</LangVersion>,见 hello-world.csproj);
  • 首次运行会自动从 NuGet 还原 Hydro 1.3.0 包(离线环境需先配置 NuGet 镜像)。

启动后浏览器访问控制台输出的本地地址(默认 https://localhost:5001 或 http://localhost:5000),即可看到各示例页面:

  • hello-world:点击 Show 按钮,标题文本即时更新;
  • event-child-parent / event-global:点击按钮观察单个或多个组件同步刷新;
  • event-global-subject:反复点击,两个组件随机各自更新;
  • cookies:首次显示 "No cookies set",点击 Set New Cookie 后写入 Cookie 并重定向,再次打开显示 Cookie 中的日期值,点击 Remove Cookie 则删除并提示;
  • component-1 / component-2:点击父组件按钮,对比带 key 与不带 key 的子组件更新差异;
  • component-3:观察 Mount/MountAsync、Render/RenderAsync 对 Text/Text2 的最终赋值结果。

八、小结

通过 projects/hydro 的 8 个示例,可以完整掌握 Hydro 在 ASP.NET Core 中的核心使用面:

  1. 组件模型:HydroComponent 基类 + .cshtml 模板,公开属性即状态、公开方法即动作,on:click 等指令完成事件绑定;
  2. 通信体系:Dispatch(父子定向)、DispatchGlobal(全局广播)、subject 主题过滤三档粒度,事件用 record 定义、Subscribe<T> 订阅;
  3. 状态读写:CookieStorage 便捷操作 Cookie,Redirect(Url.Page(...)) 完成页面导航;
  4. 嵌套数据流:父子组件间默认"参数传入不追踪",用 key 参数强制子组件在值变化时重建,实现父组件状态向子组件的精准推送;
  5. 生命周期:Mount/MountAsync 负责挂载初始化,Render/RenderAsync 负责渲染前加工,异步版本按顺序在同步版本之后执行。

这套组合能力让"后端 C# 开发者少写前端交互代码"成为可能,也为需要轻量交互、又不愿引入独立前端工程的 ASP.NET Core 项目提供了一条务实的实现路径。

登录后查看全文
practical-aspnetcore