Blazor Server 跨组件通信实战:用 Blazor.EventAggregator 事件聚合器解耦页面与组件(practical-aspnetcore ComponentEvents-2)

原创2026-10-14 13:04:211,462 阅读
文章标签:示例工程

Blazor Server 跨组件通信实战:用 Blazor.EventAggregator 事件聚合器解耦页面与组件(practical-aspnetcore ComponentEvents-2)

导读

在 Blazor Server 应用中,父子组件之间可以通过参数和回调通信,但位于不同组件层级、不同页面之间的组件并没有原生的事件总线机制。本篇文章基于 practical-aspnetcore 仓库中的 ComponentEvents-2 示例,完整讲解如何借助第三方库 Blazor.EventAggregator(事件聚合器),以"发布—订阅"模式打通页面与组件、组件与组件之间的通信。读完本文,你将掌握该库的核心 API(IEventAggregator、IHandle<T>、PublishAsync、Subscribe/Unsubscribe)、正确的服务注册方式,以及一套可复制的解耦式跨组件通信模板。

一、为什么需要事件聚合器:跨层级组件通信的痛点

Blazor 组件的通信方式主要有以下几种:

  • 父 → 子:通过组件参数([Parameter])传递;
  • 子 → 父:通过 EventCallback 回调;
  • 共享状态:注入一个共享服务对象。

前两种方式在组件层级清晰时非常自然,但一旦两个组件位于不同的层级树中(例如一个在布局 MainLayout 中,一个在某个路由页面深处),或者需要"任意组件通知任意组件"时,直接传参和回调就变得异常繁琐。这正是仓库 README 中描述的痛点:"There are many ways for Parent component to communicate to Children components in Blazor and vice versa. However there is no straightforward way to manage communication between components that are located in different hierarchy."

针对这一场景,仓库给出了两个递进式的解决方案:

  1. 手动 AppState 中介对象(ComponentEvents):用 C# 原生 event 实现通知;
  2. 事件聚合器库(ComponentEvents-2,即本文主体):用 Blazor.EventAggregator 库统一管理订阅与发布。

两个示例的界面和交互完全一致(页面上有一个"Notify from Page"按钮、子组件卡片中有一个"Notify from a Child Component"按钮,点击后通知出现在布局顶部的横幅中),差别仅在于通信基础设施。对比阅读两个示例,能非常直观地看出从"手写事件"到"库化事件总线"的演进。

二、两种通信方案的对比:AppState vs EventAggregator

2.1 方案一:Scoped 生命周期的手写 AppState(ComponentEvents)

ComponentEvents 示例 的核心是一个以 Scoped 生命周期注册的 AppState 中介对象:

public class AppState
{
    public event Action<string> OnNotification;

    public void Notify(string notification)
    {
        OnNotification?.Invoke(notification);
    }
}

注册方式(见 ComponentEvents/Program.cs):

builder.Services.AddScoped<AppState>();

发布方注入 AppState 并调用 AppState.Notify(...),订阅方在 OnInitialized 中挂接 AppState.OnNotification += UpdateNotification,并在 Dispose 中解除挂接(见 Notification.razor)。

该方案的关键约束在 README 中写得很明确:AppState 必须是 Scoped 生命周期,而不是 Singleton。因为在 Blazor Server 宿主模型中,Scoped 服务的生命周期被限定在"当前用户的 SignalR 连接/会话"内;若注册为 Singleton,则所有用户的 AppState 是同一个实例,一个用户触发的通知会被其他用户的会话接收到,造成状态串扰。

2.2 方案二:事件聚合器库(ComponentEvents-2)

ComponentEvents-2 的定位是:"The sample is similar to Component Events except that it uses Blazor.EventAggregator to handle cross components and pages communication."

即:通信需求不变,但把"谁在监听、如何通知"的样板代码交给 Blazor.EventAggregator 库统一处理。该库以 NuGet 包形式引入,版本信息见 ComponentEvents.csproj:

<PackageReference Include="EventAggregator.Blazor" Version="2.0.0" />

相较于手写 event,事件聚合器带来的核心收益是解耦:发布方不再需要持有任何订阅方引用,甚至不需要知道谁在听;订阅方通过实现统一的 IHandle<T> 接口声明"我关心某类消息",库负责维护订阅清单并按消息类型分发。从源码结构看,整个 ComponentEvents-2 项目不依赖任何中间状态对象,只依赖一个 NotificationMessage 消息模型,发布与订阅全部围绕消息类型展开。

三、项目结构一览

ComponentEvents-2 是一个标准的 Blazor Server(服务端渲染 + SignalR 实时交互)应用,目录结构如下(完整文件见 projects/blazor-ss/ComponentEvents-2):

ComponentEvents-2/
├── Components/
│   ├── App.razor               # 根组件,配置 Router
│   ├── Child.razor             # 子组件(发布方)
│   ├── Notification.razor      # 订阅者(横幅显示消息)
│   ├── _Imports.razor          # 组件级 using
│   ├── Pages/
│   │   └── Index.razor         # 首页(发布方)
│   └── Shared/
│       └── MainLayout.razor    # 布局,挂载 Notification
├── Pages/
│   ├── Index.cshtml            # 服务端宿主页
│   └── _ViewImports.cshtml
├── wwwroot/css/site.css
├── AppState.cs                 # 消息模型(NotificationMessage)
├── ComponentEvents.csproj      # net10.0 + EventAggregator.Blazor 2.0.0
├── Program.cs                  # 服务注册与管线
└── README.md

其中 AppState.cs 文件虽沿用旧命名,但实际内容只是消息模型类 NotificationMessage(下文详述),并非事件状态对象——这也侧面说明该示例已完全放弃手写状态对象方案。

四、核心配置:正确注册 EventAggregator 服务

Program.cs 是理解本示例的第一把钥匙(见 Program.cs):

var builder = WebApplication.CreateBuilder();

//do not use services.AddEventAggregator
builder.Services.AddScoped<EventAggregator.Blazor.IEventAggregator, EventAggregator.Blazor.EventAggregator>();
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStaticFiles();

app.MapBlazorHub();
app.MapRazorPages();
app.MapFallbackToPage("/Index");

app.Run();

要点逐条说明:

  1. 手动注册而非扩展方法:源码中有一行醒目的注释 //do not use services.AddEventAggregator,提示该库虽然可能提供 AddEventAggregator 扩展方法,但本示例刻意采用显式注册:

    builder.Services.AddScoped<EventAggregator.Blazor.IEventAggregator, EventAggregator.Blazor.EventAggregator>();
    

    这样注册的是"接口 → 实现"的映射,组件中以 IEventAggregator 接口注入,便于测试替换,也避免了扩展方法可能带来的隐式配置。

  2. 生命周期选择 Scoped:与 AppState 方案同理,事件聚合器也被注册为 Scoped。在 Blazor Server 中这意味着每个用户会话(SignalR 连接)拥有独立的订阅清单,订阅不会跨用户泄漏。这一点与本仓库 ComponentEvents README 中强调的 Scoped vs Singleton 注意事项一脉相承:若注册为 Singleton,所有用户的订阅会混在一起,某用户发布的页面消息可能被推送到其他用户的界面上。

  3. 其余为 Blazor Server 标准配置:AddRazorPages() + AddServerSideBlazor() 注册服务;MapBlazorHub() 挂载 SignalR 集线器;MapRazorPages() 映射宿主 Razor Pages;MapFallbackToPage("/Index") 让未匹配路由回退到 Index.cshtml 宿主页;UseHttpsRedirection() 强制 HTTPS 跳转(仓库 blazor-ss 章节说明所有示例默认运行在 SSL 下)。

五、定义消息契约:NotificationMessage

事件聚合器以消息类型为通信契约,发布与订阅都围绕具体消息类展开。本示例的消息模型定义在 AppState.cs:

using System;

namespace ComponentEvents
{
  public class NotificationMessage
  {
    public string Message { get; set; }
  }
}

NotificationMessage 是一个极简的 POCO:只有一个 Message 字符串属性。后续所有通信都通过发布 NotificationMessage 实例、订阅 NotificationMessage 类型完成。在实际项目中,消息类型通常按业务语义定义(如 UserLoggedInMessage、CartChangedMessage),并可携带任意结构化载荷。

六、发布消息:页面与子组件

事件聚合器的发布端 API 是 IEventAggregator.PublishAsync(TMessage)。本示例有两个发布方,二者代码模式完全一致。

6.1 页面发布者(Index.razor)

首页通过 @inject 注入 IEventAggregator,点击按钮后发布消息(见 Index.razor):

@page "/"
@inject EventAggregator.Blazor.IEventAggregator Events

<h1>Component Events</h1>

<button @onclick="NotifyAsync" class="btn btn-primary">Notify from Page</button>

<br/>
<br/>

<Child></Child>
@code {
  async Task NotifyAsync()
  {
    await Events.PublishAsync(new NotificationMessage { Message = "Hello World from a page" });
  }
}

6.2 子组件发布者(Child.razor)

同一页面上还嵌入了 Child 子组件,它也注入同一 IEventAggregator 并发布消息(见 Child.razor):

@inject EventAggregator.Blazor.IEventAggregator Events

<div class="card">
  <div class="card-body">
    <button @onclick="NotifyAsync" class="btn btn-primary">Notify from a Child Component</button>
  </div>
</div>

@code{
  async Task NotifyAsync()
  {
    await Events.PublishAsync(new NotificationMessage { Message = "Hello World from a child component"});
  }
}

关键点:发布方只认识 IEventAggregator 和消息类型,不持有任何订阅者引用。页面与子组件、甚至后续任意新增的发布者,都可以零改动地接入同一个事件总线。这正是与手写 AppState(发布方需注入具体状态对象)的本质差异。

七、订阅消息:Notification 组件

订阅方是理解事件聚合器模式的核心。本示例的 Notification 组件实现了三个关键点(见 Notification.razor):

@inject EventAggregator.Blazor.IEventAggregator Events
@implements EventAggregator.Blazor.IHandle<NotificationMessage>
@implements IDisposable

@Message

@code {

  string Message { get; set; }

  protected override void OnInitialized()
  {
    Events.Subscribe(this);
  }

  public Task HandleAsync(NotificationMessage message)
  {
    Message = message.Message;
    InvokeAsync(() => StateHasChanged());
    return Task.CompletedTask;
  }

  public void Dispose()
  {
    Events.Unsubscribe(this);
  }
}

逐点拆解:

  1. 声明订阅身份:@implements EventAggregator.Blazor.IHandle<NotificationMessage> 表明该组件是"通知消息"的订阅者。泛型参数 NotificationMessage 即订阅的消息类型,也是库进行分发路由的依据。

  2. 注册订阅:在 OnInitialized() 中调用 Events.Subscribe(this)。库会把 this 登记为该消息类型的监听者。必须注意:订阅发生在组件初始化阶段,这样后续任何 PublishAsync 都能命中该订阅者。

  3. 实现处理回调:实现接口方法 Task HandleAsync(NotificationMessage message)。当消息发布时,库调用所有订阅者的 HandleAsync 分发消息。回调中更新 Message 字段后,调用 InvokeAsync(() => StateHasChanged()) 触发组件重新渲染——由于事件聚合器的调用上下文不一定在 Blazor 的同步上下文中,用 InvokeAsync 把 UI 更新调度回组件线程是必要的稳妥做法(本示例中 HandleAsync 返回 Task.CompletedTask,属于异步接口的同步实现形式)。

  4. 优雅退订:@implements IDisposable 并在 Dispose() 中调用 Events.Unsubscribe(this)。退订是必须的,否则已销毁的组件仍留在订阅清单中,会造成内存泄漏和幽灵回调(被销毁组件依然被通知、甚至触发异常)。这也与手写 AppState 方案中 OnNotification -= UpdateNotification 的释放逻辑一一对应。

八、把订阅者挂到布局:MainLayout

订阅者组件放在哪里,决定消息"显示在哪里"。本示例把 Notification 挂在布局的头部区域(见 MainLayout.razor):

@inherits LayoutComponentBase

<div class="container">
  <header style="margin-bottom:10px; background-color: #001f3f;color:white;padding:5px;">
    <Notification></Notification>
  </header>
  <div>
          @Body
  </div>
</div>

由于 App.razor 中 RouteView 的 DefaultLayout 指向 Shared.MainLayout(见 App.razor),因此无论用户导航到哪个页面,布局头部都会渲染 Notification 组件;而页面路由内容通过 @Body 注入。于是:

  • 用户在首页(Index.razor)点击按钮 → 页面发布消息;
  • 用户点击内嵌子组件(Child.razor)按钮 → 子组件发布消息;
  • 消息经由 Scoped 的事件聚合器分发到布局中的 Notification 订阅者 → 横幅更新。

这就实现了"发布者与订阅者处于完全不同的组件层级(页面 vs 布局)"的典型跨层级通信场景。

九、宿主入口与组件命名空间

9.1 服务端宿主页

Pages/Index.cshtml 是传统 Razor Pages 宿主,负责把 Blazor 根组件 App 以服务端预渲染模式挂到页面上:

<app>@(await Html.RenderComponentAsync<App>(RenderMode.ServerPrerendered))</app>
<script src="_framework/blazor.server.js"></script>

RenderMode.ServerPrerendered 意味着首次请求先由服务端预渲染 HTML(利于 SEO 与首屏),随后通过 blazor.server.js 建立 SignalR 连接接管交互。这也是 Program.cs 中 MapRazorPages() 与 MapFallbackToPage("/Index") 存在的意义:所有未匹配路由最终都落到这个宿主页,确保 SPA 式导航(地址栏直接输入任意路由)都能正确加载应用。

9.2 命名空间导入

组件能直接使用 NotificationMessage、EventAggregator.Blazor.IEventAggregator 等类型,依赖两处导入配置:

  • Components/_Imports.razor:导入 Blazor 常用命名空间(Microsoft.AspNetCore.Components.Forms、Routing、Web、Authorization、Microsoft.JSInterop 等),供所有 .razor 组件共享;
  • Pages/_ViewImports.cshtml:包含 @using ComponentEvents.Components 和 @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers,使宿主页能识别并渲染 App 组件。

从源码结构可以推断,NotificationMessage 定义在根命名空间 ComponentEvents 下,而组件所在命名空间为 ComponentEvents.Components,二者同属 ComponentEvents 程序集,因此组件无需额外 using 即可引用消息类型。

十、运行与验证

该示例目标框架为 net10.0(见 ComponentEvents.csproj,LangVersion 为 preview),仓库根目录 global.json 指定 SDK 版本 10.0.0(rollForward: major)。在已安装对应 .NET SDK 的环境下,可于项目目录运行:

dotnet restore
dotnet run

启动后(默认走 HTTPS),在浏览器打开首页,可以依次验证两条完整链路:

  1. 点击 Notify from Page 按钮 → 顶部横幅显示 Hello World from a page;
  2. 点击 Notify from a Child Component 按钮 → 顶部横幅显示 Hello World from a child component。

注意本项目同时提供了 clean.sh 与 restore.sh(仓库根目录),用于批量清理与还原各示例依赖;单项目操作时直接使用 dotnet 命令即可。

十一、小结与源码索引

通过 ComponentEvents-2 这个示例,可以提炼出一套通用的 Blazor Server 跨组件通信模板:

环节 做法 本仓库证据
引入库 NuGet 包 EventAggregator.Blazor 2.0.0 ComponentEvents.csproj
注册服务 AddScoped<IEventAggregator, EventAggregator>()(勿用 AddEventAggregator) Program.cs
定义契约 消息 POCO,如 NotificationMessage AppState.cs
发布 注入 IEventAggregator,PublishAsync(new TMessage{...}) Index.razor、Child.razor
订阅 @implements IHandle<T>、Subscribe、HandleAsync、Dispose 中 Unsubscribe Notification.razor
挂载位置 布局头部等全局位置,随路由常驻 MainLayout.razor

两个核心注意事项务必牢记:

  • 生命周期:事件聚合器(以及手写 AppState)必须注册为 Scoped,才能把订阅隔离在当前用户会话内;注册为 Singleton 会导致消息跨用户串扰。
  • 及时退订:订阅者必须实现 IDisposable 并在 Dispose() 中调用 Unsubscribe,否则会产生内存泄漏与幽灵回调。

如需深入对照"手写事件"与"库化事件总线"的差异,可将本示例与 ComponentEvents 示例 并排阅读:前者以 AppState + C# event 实现同一交互,后者以 IEventAggregator + 消息类型实现,二者是同一场景下从"中介对象"到"消息总线"的典型演进路径,也共同构成了 practical-aspnetcore 仓库 blazor-ss 章节 中关于服务端 Blazor 组件通信的完整知识闭环。

登录后查看全文
practical-aspnetcore