返回资讯中心
外部精选
软件工程
#开发者实时流

开发者用 .NET 框架实现文档截图自动化

来源标题:Automate Documentation Screenshots with .NET

一位开发者为 StellarAdmin 文档构建了基于 .NET 的截图自动化框架,取代手动截图与维护。他指出,截图需先复现特定功能场景,耗时较长,且文档站常需明暗两种模式,同一区域要各截一张。

Hacker News 最新jerriep2026/11/9 · 8 天前30 分钟阅读

以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。

多年来,我在多个文档团队工作过,而创建文档过程中最令人头疼的环节之一就是截图的管理与维护。因此,当我开始为 StellarAdmin 编写文档时,我就下定决心要把这件事彻底自动化。

在这篇博客中,我将介绍我为实现截图自动生成与维护而搭建的框架。

在深入框架本身之前,先聊聊为什么截图会成为文档工作中如此令人沮丧的一部分。

第一个痛点在于,你需要先搭建正确的场景。截图通常是为了展示应用的某个特定功能,或者某种边缘情况。所以在截图之前,你得先在应用中重现那个特定的场景,这往往很耗时。

现在很多文档网站都支持亮色和暗色模式。因此,你大概会希望两种模式下都截图,然后根据文档网站当前所处的模式来使用对应的那张。这意味着你需要对完全相同的屏幕区域各截一张——除非你希望用户切换模式时截图的视口跟着跳来跳去。而当屏幕上还有标注时,这件事就更难了,如果不借助某种自动化手段,(大概)根本无法做到。

最后,随着应用不断变化,你需要回头更新这些截图,确保它们准确反映用户运行应用时的实际体验。这意味着你得把第一次截图时做的所有事情再重复一遍。

我搭建的架构用到了 Playwright 和 WebApplicationFactory。如果你不熟悉 ASP.NET Core,WebApplicationFactory 是用于 ASP.NET Core 集成测试的,它允许你在内存中的测试服务器里托管应用。

从高层来看,我的截图框架架构如下:

flowchart LR spec["<b>Specification</b><br/>YAML:要执行的步骤<br/>以及要截取的内容"] scenario["<b>Scenario</b><br/>C#:StellarAdmin<br/>如何配置"] cli["<b>StellarAdmin CLI</b><br/>针对每个场景<br/>运行对应的 spec"] chromium["<b>Chromium</b><br/>由 Playwright 驱动,<br/>按照 spec 的步骤执行"] subgraph factory["WebApplicationFactory"] host["<b>Test host</b><br/>一个普通的 ASP.NET Core 应用<br/>加上场景的配置,<br/>运行在真实端口上"] end screenshots["<b>Screenshots</b><br/>PNG 和 GIF,<br/>亮色与暗色"] docs["<b>Website docs</b><br/>页面按截图名称<br/>引用它们"] spec --> cli scenario --> cli cli -- 驱动 --> chromium cli -- 启动 --> factory chromium <-- HTTP --> host chromium --> screenshots screenshots --> docs

在博客的后续部分我会详细展开所有内容,这里先简要说明一下图中发生了什么。

两个关键部分是 scenario 和 specification。scenario 是一个 C# 类,负责将 StellarAdmin 配置到我截图所需的状态。specification 是一个 YAML 文件,使用我自己创建的 DSL,通过 Playwright 自动化浏览器,到达我想要截取的目标状态。

这两者都由我内部的开发 CLI 使用。CLI 通过 WebApplicationFactory 启动测试服务器,也就是一个 ASP.NET Core Web 应用。WebApplicationFactory 启动测试服务器时会执行 scenario,从而让应用进入正确的状态。

接着它执行 specification,后者使用 Playwright 自动化浏览器,还提供了一些额外功能,比如截图(以及 GIF 动画)、添加标注等。截取的图片会存入 docs 仓库,再从这里嵌入到各个文档页面中。

在详细讨论上述每个元素之前,我认为有必要先基本了解 StellarAdmin 是什么,以及用户如何配置它。

StellarAdmin 是一个面向 ASP.NET Core 的框架,让开发者能够快速为应用创建管理后台页面。换句话说,它是一个“强化版”的 CRUD 框架。

StellarAdmin 通过注册各种服务和端点集成到任何 ASP.NET Core 应用中。从高层来看,一个安装了 StellarAdmin 的典型 ASP.NET Core 应用大致如下:

1 var builder = WebApplication.CreateBuilder(args); 2 3 builder.Services.AddControllersWithViews(); 4 builder.Services.AddStellarAdmin(admin => 5 6 // ... 7 }); 8 9 var app = builder.Build(); 10 11 if (!app.Environment.IsDevelopment()) 12 13 app.UseExceptionHandler("/Home/Error"); 14 app.UseHsts(); 15 16 17 app.UseHttpsRedirection(); 18 app.UseStaticFiles(); 19 20 app.UseRouting(); 21 22 app.UseAuthorization(); 23 24 app.MapControllerRoute( 25 name: "default", 26 pattern: "{controller=Home}/{action=Index}/{id?}"); 27 app.MapStellarAdmin(); 28 29 app.Run(); { // ...});var app = builder.Build();if (!app.Environment.IsDevelopment()){ app.UseExceptionHandler("/Home/Error"); app.UseHsts();}app.UseHttpsRedirection();app.UseStaticFiles();app.UseRouting();app.UseAuthorization();app.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");app.MapStellarAdmin();app.Run();">

StellarAdmin 要求开发者调用 AddStellarAdmin() 来注册 StellarAdmin 服务并进行配置,同时调用 MapStellarAdmin 来映射各个 StellarAdmin 端点。

(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →