Sparkdo.Messaging.Visualization.Blazor 3.0.0-preview.1

Sparkdo.Messaging.Visualization.Blazor

把消息冻结图渲染成整页 HTML 与快照 JSON 的 Blazor 组件与宿主接线。

• 页面是静态 SSR：宿主机不必是 Blazor 应用，不需要 AddRazorComponents、MapRazorComponents 或 SignalR。
• 读图不依赖 JS；内联脚本只增强「拖拽平移 / Ctrl + 滚轮缩放 / 适应窗口 / 选中高亮 / Esc 清除」，禁用脚本也能点节点看详情。
• 结果按冻结图缓存：同一张图只投影、布局、渲染一次；每个节点的详情也预先渲染好，?node={id} 只拼接详情片段，不重渲染整页。

宿主接入

// 1) 消息基础设施（冻结图由它建）
builder.Services
    .AddSparkdoMessaging(serializers)
    .AddSparkdoMessagingHosting();

// 2) 可视化页面
builder.Services.AddSparkdoMessagingVisualizer(options =>
{
    options.Title = "订单服务消息拓扑";
    options.ServiceName = "order-service";
    options.InstanceId = null; // 多实例部署时填实例名
});

var app = builder.Build();

// 3) 两头端点：GET /messaging/visualizer 与 GET /messaging/visualizer/diagram.json
app.MapSparkdoMessagingVisualizer("/messaging/visualizer");

图必须已经建好（MessageGraphAccessor.Graph 有值）。宿主可以：

• 启动时调一次 await provider.BuildMessagingAsync(ct)，或
• 按正常流程让 hosting 建图（接收端点在启动后开跑）。

图还没建时端点是 503 而不是 500，正文是中文修法提示；这不是代码异常，不要去翻日志。

MapSparkdoMessagingVisualizer 返回 RouteGroupBuilder，宿主可以接着挂授权：

app.MapSparkdoMessagingVisualizer("/messaging/visualizer").RequireAuthorization();

端点

JSON 的 ETag 是内容完整 SHA-256 的强标签（" + 64 位小写十六进制 + "），图不变 ETag 就不变，适合前端轮询。

选中节点与详情

• 页壳（头、SVG、表格、图例）与每个节点的详情面板都在首次请求时渲染好，缓存起来；?node={id} 只把预生成的详情片段拼进页壳，SVG 与页壳逐字不变。
• 未知的 node 值按「没选中」处理，回默认详情，不报错。
• 选中高亮由内联脚本按查询串给对应节点加 mv-selected，服务端不再输出选中态；Esc 清除选中（回到无查询串的地址）。
• 无脚本时链接照样工作：服务端读查询串拼详情，页面仍是完整可读的。

选项

资产模式

• Inline（默认）：css/js 作为嵌入资源随 HTML 内联，宿主不用配静态资产、不用管 cwd。适合内网工具、单文件部署。

• StaticWebAssets：页面输出

  <link rel="stylesheet" href="/_content/Sparkdo.Messaging.Visualization.Blazor/messaging-visualizer.css" />
  <script src="/_content/Sparkdo.Messaging.Visualization.Blazor/messaging-visualizer.js" defer></script>
  

  这些文件由 dotnet publish 带进产物。必须走发布产物：直接 dotnet run 且 cwd 不是发布目录时，_content 会 500（FileNotFoundException）。发布后从发布目录启动即可。

生产注意

• 目标框架 net11.0 单框架；跟随 Directory.Build.props，csproj 不写 TFM。
• 服务端包：不声明 SupportedPlatform，按服务端引用；页面用 HtmlRenderer 静态 SSR，不要求宿主是 Blazor 应用。
• 零 NuGet 依赖：ASP.NET Core 走 FrameworkReference Microsoft.AspNetCore.App；核心包 Sparkdo.Messaging 是显式 ProjectReference（端点直接用 MessageBusGraph 与 MessageGraphAccessor，不靠 A 包的传递引用）。
• 页面渲染缓存持有冻结图（引用相等），图冻结后不会失效，内存占用按图的规模固定。
• 图很大时（上千节点）首访渲染会慢一次；之后命中缓存。SVG 由服务端生成，节点链接是普通 <a href="?node=...">，可用浏览器前进后退。
• 样式用全局 mv- 前缀类名，主题变量在 :root（--mv-canvas、--mv-surface、--mv-border、--mv-fg、--mv-fg-muted、--mv-accent、--mv-danger），宿主可覆盖。

组件

Components/ 下都是公开组件（Razor 生成的组件类固定是 public；没有 @code 分部类，避免 .razor.cs 触发源码布局门禁）：

• MessagingVisualizerPage.razor：整页根组件，宿主渲染入口。
• DetailPanel.razor：选中节点详情。
• TransportTable.razor：传输与拓扑表。
• Legend.razor：图例与规模统计。

SVG 由 Sparkdo.Messaging.Visualization 的 DiagramSvgRenderer 生成，组件只负责套页面，不手拼图形。