用途
本技能用于自定义 Umbraco 在运行升级迁移（upgrade migrations）期间展示给访问者的页面。它针对 Umbraco 17 及以上版本，其中 UpgradingViewPath 的指导适用于 Umbraco 17.3 及之后，因为该版本中无人值守迁移（unattended migrations）在后台运行。更早的 Umbraco 17 版本以及其他升级模式必须遵循对应版本的官方文档。
需要强调的是，这不是应用错误页面。404、500 和 Boot Failed 的处理应使用 umbraco-custom-error-pages。
选择合适的 Umbraco 做法
- Umbraco 17.3+ 无人值守升级：使用 Umbraco:CMS:Global:UpgradingViewPath 配置加自定义 Razor 视图，将设置指向如 ~/Views/MyUpgrading.cshtml 的视图。这是当前后台升级流程的推荐做法。
- 有文档记载的通用维护页约定：项目根目录下的 UmbracoWebsite/maintenance.cshtml。当该约定与项目的升级流程和版本匹配时，遵循官方自定义维护页教程。
务必先获取官方文档。在未核对项目的 Umbraco 版本和升级模式前，不要假定这两条路径可以互换。
选择合适的托管层面
- Umbraco 运行时：当 Umbraco 正在执行升级或迁移时使用，通过 UpgradingViewPath 或文档记载的 UmbracoWebsite/maintenance.cshtml 约定实现。
- Umbraco Cloud 平台：当 Cloud 基础设施或平台操作导致应用不可用时使用，通过 Cloud 门户的 Error Pages 功能实现。
- 托管或 Web 服务器：当应用离线、正在重启或无法启动时使用，通过 app_offline.htm、部署槽（deployment slots）或 Web 服务器回退页实现。
不要把 Umbraco 运行时页面当作通用的部署或应用重启页面。当用户描述的是普通部署停机时，应提供相应的托管层方案。
Umbraco 运行时实现
对于 Umbraco 17.3 及之后，先获取无人值守升级文档和全局设置文档。当前无人值守流程在 RuntimeLevel 为 Upgrading 时以 HTTP 503 提供 Upgrading.cshtml。可通过如下配置自定义：
{
"Umbraco": {
"CMS": {
"Global": {
"UpgradingViewPath": "~/Views/MyUpgrading.cshtml"
}
}
}
}
创建所配置的 Razor 视图，内容需自包含。可提供 assets/maintenance.cshtml 作为起始模板，告知用户将其复制到配置的视图路径，或在遵循通用教程时复制到根级的 UmbracoWebsite/maintenance.cshtml 位置。
对于当前的 Umbraco 就绪流程，应轮询匿名端点 /umbraco/api/health/ready，而不是轮询首页。该端点应用未就绪时返回 503，可以接收正常流量时返回 200。除非项目因其他原因需要，否则不要新增自定义健康端点。
保持所提供文件的自包含性。使用内联 CSS，不引用外部资源，不使用布局，不使用实时 Umbraco 或 Razor 数据（如 IPublishedContent）。在页面被提供期间，内容缓存或数据库可能不可用。特别地，不要让升级视图为获取标题或消息去查询后台内容节点：这会对可能不可用的服务产生硬依赖，可能把一个有用的 503 页面变成另一次故障。
编辑器控制的文案（安全的折中方案）
编辑器仍可拥有措辞，但文案必须在升级前烘焙进已部署的视图中。创建一个小的后台内容节点（例如 maintenanceCopy），包含两个必填属性，如 heading 和 message。在站点健康运行时执行的部署/发布步骤读取已发布的值，对其进行 HTML 编码，并替换 maintenance.cshtml 副本中的显式令牌（例如 <!-- MAINTENANCE_HEADING --> 和 <!-- MAINTENANCE_MESSAGE -->）。将该生成的、自包含的文件连同应用一起部署到配置的 UpgradingViewPath。当任一值缺失时使用安全的回退文本。
这不是实时内容渲染：编辑器的更改在下次成功的、重新生成文件的发布/部署时才会生效。将最后一份已知良好的生成文件保留在制品中；在 RuntimeLevel 为 Upgrading 时，绝不要要求后台请求、IPublishedContent、作用域或数据库连接。工作流程与权衡参见 references/editor-controlled-copy.md。
官方文档警告不要让项目停留在升级模式超过必要时间。在预发布环境用真实的版本升级路径进行测试。除非实际运行了构建或升级测试，否则不要声称已验证该页面。
Cloud 与托管层
为保持品牌一致，可在各层复用同一套自包含的视觉设计：
- Umbraco Cloud：在给出门户操作说明前，先获取 Cloud Error Pages 文档。该页面通过门户上传，按主机名分配，必须自包含且在文档记载的大小限制内。可提供 assets/cloud-error-page.html 作为起始模板。
- Azure 或 IIS：使用 app_offline.htm 或部署槽。在推荐该做法时，先获取 Azure 部署槽文档。
Cloud 平台停机和普通应用重启停机需要托管层页面。它们不在 Umbraco 运行时升级视图的覆盖范围内。
改为禁用
大多数升级并不需要站点下线。如果团队倾向于不显示维护页，可在 appsettings.json 中添加 Umbraco:CMS:Global:ShowMaintenancePageWhenInUpgradeState: false，具体依项目版本的官方文档操作。
完成时告知用户
- 哪种 Umbraco 做法适用于他们的版本和升级模式。
- 所配置的视图或维护文件应放在哪里。
- 页面在升级状态下出现，并在迁移完成后消失。
- 在支持的情况下，可使用就绪端点进行安全的自动刷新。
- Cloud 平台停机和普通应用重启停机需要各自的托管层页面。
验证
本技能的断言位于 evals/evals.json，使用 umbraco-skill-evaluator 技能运行，并在交付前用 umbraco-skill-validator 和 umbraco-skill-code-analyzer 验证技能。