如何用Visual Studio 17创建可安装的Umbraco 13后台API插件包？

核心结论 #

完全可以通过VS的「Umbraco Package」模板创建包含Section、Dashboard、AngularJS控制器及服务端MVC内容的插件包，直接通过Umbraco后台的「Packages」板块安装，无需必须在Umbraco项目内开发。下面是具体操作步骤：

步骤1：创建Umbraco Package项目 #

1. 打开VS17，新建项目时搜索「Umbraco Package」模板，填写项目名称（比如CustomUmbracoPackage）和存储路径后确认创建。
2. 模板会自动生成完整的包结构，包括App_Plugins目录、.targets配置文件、项目依赖等，无需手动从零搭建。

步骤2：添加自定义Section #

新建C#类（比如CustomSection.cs），实现ISection接口定义板块标识与名称：

using Umbraco.Cms.Core.Sections;

namespace CustomUmbracoPackage.Sections;

public class CustomSection : ISection
{
    // 板块唯一小写别名，无空格
    public string Alias => "customSection";
    // 后台显示的板块名称
    public string Name => "我的自定义板块";
}

步骤3：添加自定义Dashboard #

新建C#类（比如CustomDashboard.cs），通过[Dashboard]特性配置仪表盘关联信息：

using Umbraco.Cms.Core.Dashboards;

namespace CustomUmbracoPackage.Dashboards;

[Dashboard(
    Alias = "customDashboard",
    Name = "我的自定义仪表盘",
    // 关联到自定义板块
    Sections = new[] { "customSection" },
    // 指向仪表盘前端视图路径
    ViewPath = "/App_Plugins/CustomUmbracoPackage/Views/Dashboard.html",
    // 配置访问权限，此处允许admin角色访问
    AccessRules = new[] { new AccessRule { Type = AccessRuleType.Grant, Value = "admin" } }
)]
public class CustomDashboard : IDashboard
{
}

步骤4：开发前端资源（AngularJS控制器+视图） #

1. 在项目根目录创建App_Plugins/CustomUmbracoPackage目录，依次新建Controllers、Views子目录。
2. 在Controllers下创建customDashboard.controller.js，编写AngularJS逻辑：

angular.module("umbraco").controller("CustomUmbracoPackage.CustomDashboardController", function ($scope, $http) {
    $scope.welcomeMsg = "欢迎使用自定义仪表盘";
    
    // 示例：调用后端API获取数据
    $http.get("/umbraco/api/CustomApi/GetDashboardData")
        .then(function(res) {
            $scope.apiData = res.data;
        });
});

3. 在Views下创建Dashboard.html作为仪表盘前端视图：

<div ng-controller="CustomUmbracoPackage.CustomDashboardController">
    <h3>{{welcomeMsg}}</h3>
    <p>后端API返回：{{apiData}}</p>
    
    <!-- 加载MVC部分视图内容容器 -->
    <div ng-bind-html="renderedMvcContent"></div>
</div>

4. 在App_Plugins/CustomUmbracoPackage下新建package.manifest，告知Umbraco加载前端资源：

{
    "dashboards": [
        {
            "alias": "customDashboard",
            "view": "/App_Plugins/CustomUmbracoPackage/Views/Dashboard.html",
            "js": ["/App_Plugins/CustomUmbracoPackage/Controllers/customDashboard.controller.js"]
        }
    ]
}

步骤5：添加服务端MVC/API内容 #

方案A：创建Umbraco API控制器

新建C#类（比如CustomApiController.cs），继承UmbracoApiController编写后端接口：

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Controllers;

namespace CustomUmbracoPackage.Controllers;

public class CustomApiController : UmbracoApiController
{
    [HttpGet]
    public string GetDashboardData()
    {
        return "来自Umbraco API的测试数据";
    }
}

方案B：创建SurfaceController渲染MVC视图

如果需要展示Razor视图内容，可创建SurfaceController：

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Web.Common.Controllers;

namespace CustomUmbracoPackage.Controllers;

public class CustomSurfaceController : SurfaceController
{
    public IActionResult RenderDashboardContent()
    {
        var model = new DashboardViewModel { Content = "SurfaceController渲染的内容" };
        return PartialView("/App_Plugins/CustomUmbracoPackage/Views/DashboardContent.cshtml", model);
    }
}

// 对应视图模型
public class DashboardViewModel
{
    public string Content { get; set; }
}

在Views下新建DashboardContent.cshtml：

@model CustomUmbracoPackage.Controllers.DashboardViewModel
<p>MVC视图内容：@Model.Content</p>

修改AngularJS控制器，调用Surface接口加载内容：

$http.get("/umbraco/surface/CustomSurface/RenderDashboardContent")
    .then(function(res) {
        $scope.renderedMvcContent = res.data;
    });

步骤6：理解.targets文件（模板自动生成，无需手动编写） #

VS模板生成的CustomUmbracoPackage.targets是MSBuild配置，负责打包/安装时将资源复制到Umbraco项目对应目录。模板已默认包含App_Plugins、控制器等文件的复制逻辑，无需手动修改。若需添加额外文件，可在文件中补充ItemGroup和Copy任务，比如：

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="CopyCustomFiles" AfterTargets="Build">
        <Copy SourceFiles="@(CustomFiles)" DestinationFolder="$(UmbracoProjectPath)\%(RecursiveDir)" />
    </Target>
    <ItemGroup>
        <CustomFiles Include="Models\**\*.cs" />
    </ItemGroup>
</Project>

步骤7：打包并安装插件 #

1. 在VS中右键包项目，选择「Pack」，生成的.nupkg文件存放在项目的bin/Debug或bin/Release目录。
2. 打开Umbraco后台「Packages」板块，点击「Install local package」，上传.nupkg文件完成安装。
3. 重启Umbraco应用（或刷新后台），即可在左侧导航看到自定义Section，点击进入查看Dashboard。

开发调试技巧 #

开发阶段可将包项目直接引用到本地Umbraco项目，修改代码后编译即可实时看到效果，无需反复打包安装。

内容的提问来源于stack exchange，提问作者Ross Ekberg