用途:本技能面向 Umbraco 17 的 Settings > Health Check 仪表板需求,帮助实现自定义健康检查;当用户明确需要通过视图/组件呈现本地化的健康检查指引或状态文案时,也可涉及 Razor 前端呈现。若需求仅限后台检查,则不应添加 Razor 呈现面。若需求是 Kubernetes、负载均衡、存活/就绪探针,则应改用官方 Health Probes 文档,而非本技能。
版本兼容:本技能及其资产面向 Umbraco 17 编写,资产针对固定版本 17.5.3 编译和运行。早期版本存在差异:在 15.3 之前,检查会重写 GetStatus() 而不是 GetStatusAsync()。实现前应确认目标项目的 Umbraco 包版本和确切的 API 表面。
实现面选择:默认使用后端 C#,适用于仪表板检查、配置比较、运行时检查或安全修复操作,可基于 AbstractSettingsCheck 或 HealthCheck,要求检查快速并如实报告失败。仅当用户明确需要由视图/组件渲染本地化健康检查指引或状态文案时,才使用 Razor 前端,此时状态计算仍保留在 C# 中,遵循项目既有的 Razor/本地化约定,对输出进行编码,绝不暴露机密。
后端 C# 要点:实现前应获取官方 Health Check 文档,并在回答中链接所依据的官方页面;先打开 references/backend-health-check.md,从 assets/RobotsTxtHealthCheck.cs 及其语言文件 assets/en-US.xml 起步,不要凭记忆复制 API 示例,也不要照抄文档示例(其在 17 上无法编译)。需生成稳定 GUID、使用合适分组、校验操作别名、保持修复操作幂等,并将写入失败作为错误(含日志)暴露,而不是吞掉后当作成功。
Razor、多语言 Dictionary 条目与回退:先检查现有视图/组件与本地化约定;用户可见文本应放在 Dictionary 条目中而非硬编码译文;按功能与消息用途组织条目,使用稳定别名,并为每种受支持文化有意识地创建值;遵循项目既有的文化选择机制。实现前需定义回退行为:请求文化、配置/默认文化,最后是安全的非敏感固定消息。缺失 Dictionary 条目或翻译时,必须产生可见的受控回退或明确的失败状态,不能是空白成功、泄漏配置值、吞掉异常或静默默认。需对 Razor 输出编码,绝不渲染机密或原始配置值。注意 Umbraco 不会自动在文化间回退:Umbraco.GetDictionaryValue(key)(当前文化)和 GetDictionaryValue(key, culture) 在条目或翻译缺失时返回空字符串而非 null,因此 ?? 链不会继续回退;应检测空值,或使用会回退的 GetDictionaryValueOrDefault。示例思路为:先取当前文化翻译,若为空再取默认文化的 GetDictionaryValueOrDefault 并提供安全固定消息;Razor 中正常使用 @translation 渲染(默认已编码),除非内容已确认安全且经过清理,否则避免 Html.Raw。
验证:客观场景与构建真实性要求位于 evals/evals.json。存在真实项目时应实际构建,无法验证时需明确说明。后端面为 Asserted:dotnet test 门禁将资产编译进参考宿主(examples/robots-txt/),检查其状态、Fix 操作、消息是否从语言文件解析,以及创建的 robots.txt 是否在 /robots.txt 提供。Razor 面为 Documented:不附带代码,上述草图未编译,评估针对指引进行。