umbraco-extension-template

Umbraco 扩展模板

这是什么？

Umbraco 扩展模板是用于创建后台扩展的官方 .NET 模板。它提供预配置的项目结构、TypeScript/Vite 工具链、规范的文件夹结构，以及扩展开发所需的所有基本文件。每个 Umbraco 后台扩展都应以此模板为起点。

文档

实现前请务必获取最新文档：

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/development-flow/umbraco-extension-template
• 开发流程：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/development-flow
• 基础知识：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

先决条件

• .NET SDK 10.0 或更高版本
• Node.js 24 或更高版本

工作流

0. 版本检查：首先调用 umbraco-version-guard，确认目标站点的 Umbraco 主版本与这些技能面向的主版本一致。若不一致，请停止。
1. 安装模板（仅需一次）：dotnet new install Umbraco.Templates
2. 创建扩展：dotnet new umbraco-extension -n MyExtension
3. 安装依赖项：cd MyExtension/Client && npm install
4. 开始开发：npm run watch
5. 生产环境构建：npm run build

命令

安装模板

dotnet new install Umbraco.Templates

创建新扩展（基本版）

dotnet new umbraco-extension -n MyExtension

创建新扩展（包含示例）

dotnet new umbraco-extension -n MyExtension -ex

-ex 标志会添加示例代码，包括：

• 示例 API 控制器
• Swagger API 注册
• 示例仪表板组件
• 生成的 API 客户端

项目结构

基本模板

MyExtension/
├── MyExtension.csproj        # .NET project file
├── Constants.cs              # Extension constants
├── README.md                 # Setup instructions
└── Client/                   # TypeScript source
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        └── ...               # Your extension code

包含示例（-ex 标志）

MyExtension/
├── MyExtension.csproj
├── Constants.cs
├── README.md
├── Composers/                # C# composers
│   └── SwaggerComposer.cs    # API documentation setup
├── Controllers/              # C# API controllers
│   └── MyExtensionController.cs
└── Client/
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        ├── api/              # Generated API client
        ├── dashboards/       # Example dashboard
        └── entrypoints/      # Extension entry point

开发命令

# Navigate to Client folder
cd MyExtension/Client

# Install dependencies
npm install

# Development with hot reload
npm run watch

# Production build
npm run build

# Type checking
npm run check

构建与部署

发布扩展

dotnet publish --configuration Release

创建 NuGet 包

dotnet pack --configuration Release

最小示例

运行模板后，在 Client/src/ 中添加第一个清单：

manifest.ts

export const manifests: Array<UmbExtensionManifest> = [
  {
    name: "My Extension Entrypoint",
    alias: "MyExtension.Entrypoint",
    type: "backofficeEntryPoint",
    js: () => import("./entrypoint.js"),
  },
];

entrypoint.ts

import type { UmbEntryPointOnInit } from "@umbraco-cms/backoffice/extension-api";

export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
  console.log("Extension loaded!");
};

重要：将扩展添加到 Umbraco 实例

创建新扩展后，必须将其添加为主 Umbraco 实例的项目引用。否则，扩展将无法加载。

参考技能：umbraco-add-extension-reference

此技能介绍如何将新扩展的 .csproj 文件作为 <ProjectReference> 添加到主 Umbraco 项目中（例如，Umbraco-CMS.Skills.csproj）。

相关技能

创建扩展后，可使用以下技能添加功能：

• 区段：参考技能：umbraco-sections
• 仪表板：参考技能：umbraco-dashboard
• 菜单：参考技能：umbraco-menu
• 工作区：参考技能：umbraco-workspace
• 树：参考技能：umbraco-tree

如需包含可运行示例的完整扩展蓝图：

• 参考技能：umbraco-backoffice

就是这样！务必获取最新文档，使用模板搭建项目，添加项目引用，然后按需添加扩展类型。