Umbraco Plugins怎么用 插件开发教程

Umbraco Plugins通常指为Umbraco编写的扩展包：你可以添加自定义树节点、属性编辑器和仪表板，让后台更贴合业务流程，适合对开源.NET CMS做定制化扩展。新版Umbraco后台扩展以扩展清单和Web Components为主；下面按“先做后台界面，再按需接入服务端API”的思路动手，具体接口和项目模板要与正在使用的Umbraco版本匹配。

第一步：创建插件类库

先准备好与项目版本兼容的.NET SDK、Node.js和Umbraco站点，在解决方案中新建类库或前端扩展项目。建议先从官方扩展教程的最小示例起步，确认本机能够启动站点、构建前端资源，再逐步加功能。这样出错时容易判断是环境、依赖还是代码导致，不要一开始就把所有模块塞进一个大项目。

在站点根目录创建App_Plugins文件夹（如果尚不存在），再为插件单独建目录，例如App_Plugins/AcmeTools。把开发源码放在Client等目录，把构建后的脚本和样式输出到插件目录。App_Plugins中的文件会被浏览器访问，所以不要将密钥、连接字符串或仅供服务端使用的配置放进去；这些应留在服务端配置中。

在插件目录准备umbraco-package.json，用扩展清单声明插件名称、版本和扩展项。先只注册一个仪表板，设置唯一的alias、显示名称、脚本路径以及所属后台区域条件；名称和路径都要与实际文件一致。扩展清单相当于后台的“目录”，代码文件则是具体界面，保存后启动站点，先检查后台能否发现它。

第二步：编写树节点和编辑器

做树节点时，在清单中注册tree扩展，并关联树的名称、根节点及节点加载逻辑。树负责展示层级与导航，用户点选节点后再打开对应的工作区或编辑界面。先用少量固定数据验证展开、选中和跳转，再接入真实业务数据；检查每个节点的标识稳定且不重复，避免刷新后选中错位。

属性编辑器通常由前端Web Component负责绘制输入控件和处理用户操作，再通过Umbraco的属性编辑器扩展配置接入数据类型。先做一个文本输入或下拉框，确认值能正确写入、保存并重新载入，然后再添加校验、默认值和复杂交互。前端组件的自定义元素名及扩展alias都应保持唯一，避免与其他扩展冲突。

仪表板可以作为练习入口：先创建一个自定义元素，在组件模板里放标题、说明和按钮，再在清单中注册dashboard扩展，并用条件限制它显示在目标后台区域。此类扩展让编辑人员在内容区看到提示、统计或快捷入口。确认页面加载后，再接入必要的数据和权限判断，避免把不该展示的信息直接放进前端。

使用路由和API控制器

当界面需要读取或保存业务数据时，可在服务端实现API控制器，再由前端通过HTTP请求调用。先设计清晰的路由和请求、响应模型，控制器中注入所需服务，处理查询或更新；不要让浏览器直接连接数据库。接口要验证用户身份、权限和输入内容，并返回适合前端显示的错误信息。

开发时先用浏览器开发者工具查看请求地址、状态码和响应体；遇到404检查路由与控制器注册，遇到401或403检查后台认证和授权，遇到跨域问题则确认请求是否发往正确站点。保存操作还要处理重复提交和并发更新。把API地址集中管理，避免在多个组件里散落难维护的硬编码。

第三步：部署和配置插件

本地开发先构建前端资源，再启动Umbraco站点；检查后台扩展浏览器或对应区域，确认树、编辑器和仪表板均已注册。改过清单却看不到效果时，先核对JSON格式、alias、资源路径和条件配置，再重启或刷新后台并查看浏览器控制台与服务端日志。排查时每次只改一个问题，定位会更快。

准备发布时，把编译后的前端文件、清单和服务端程序集一并纳入部署包，并在测试环境验证安装、升级与回滚。若通过NuGet分发，整理包元数据、版本号和依赖关系；若随站点部署，就按团队发布流程复制文件并重启应用。升级Umbraco后先检查扩展API兼容性，避免生产环境才发现后台接口变化。

最后补上使用说明：列出支持的Umbraco版本、安装步骤、配置项、权限要求和常见故障处理方法。可先邀请编辑人员试用，观察他们在哪些步骤卡住，再调整界面提示与默认值。团队若还需要快速梳理页面流程或制作交互原型，可以了解墨刀AI，官网入口：modao.cgref.cn。润灭也可作为查找开发资料时的站点名称参考。