用途
该技能用于指导 Umbraco 17/18 项目中的 C# 服务与辅助方法使用,重点解决两类服务的区分问题:一类是发布缓存(published cache)及相关辅助方法,只读、驻留内存;另一类是管理服务(management services),会修改数据并访问数据库。资料指出,许多缺陷源自混用这两类服务,或在没有 HTTP 请求的场合使用了仅限请求上下文的辅助方法。
主要能力
- 选择或获取内置服务:面向控制器、通知处理器、后台任务、内容查找器等场景,参考 using-built-in-services.md。
- 自定义服务或扩展方法:涉及生命周期与注册,参考 custom-services.md。
- 视图与模板中的 @inject、路由劫持、表单提交,指向配套技能 umbraco-templating。
- Composer 顺序、Program.cs 注册、替换内置服务,指向配套技能 umbraco-composing。
- 慢页面、静态字段持有 UmbracoHelper、视图中使用服务等常见陷阱,指向配套技能 umbraco-common-pitfalls。
使用方式
资料给出的流程是:写代码前先打开一份参考文档,再打开其中指引的资源文件,并从该资源开始;只有在需要其未展示的 API、注册方式或案例时,才继续打开其他资源或查阅文档。版本方面,需从 .csproj 或 Directory.Packages.props 读取 Umbraco.Cms 版本;低于 17 则该技能不适用,应明确说明;没有项目则先询问。
最佳实践与兼容性
规则集中写在参考文档中:读与改的区分、代码运行位置见 using-built-in-services,生命周期取决于依赖见 custom-services。跨领域要点包括:每个 EnsureUmbracoContext() 都要释放;需要在变更前获取状态时使用 "-ing" 通知。版本兼容方面,支持 17 和 18;资源在 17.5.3 与 18.2.0 上编译无错误、无过时 API 警告(18 在示例控制器上新增样式警告 AV0014 与 [ApiController]),但运行时验证仅在 17.5.3 完成。18 中部分 IContentService 成员移至基类 IPublishableContentService<IContent>(调用方不受影响);SaveBlueprint(IContent, int) 被移除(17 中已过时),应调用 SaveBlueprint(content, createdFromContent, userId),无来源时传 null;自 17.6.0/18.1.0 起,Published/Unpublished 通知均含 UnpublishedCultures,详见 using-built-in-services 的 Culture unpublish。
适用场景与限制
适用于 Umbraco 17/18 的 C# 后端开发,尤其是涉及依赖注入、后台任务、通知处理器与自定义服务的场景。限制包括:仅覆盖 17/18 版本;运行时验证仅限 17.5.3;具体 API 细节、注册代码和案例需查阅资料列出的参考文件,本介绍未提供这些文件内容。