Back to Details

umbraco-extension-template

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Extension Template

Umbraco 扩展模板

What is it?

这是什么？

The Umbraco Extension Template is the official .NET template for creating backoffice extensions. It provides a pre-configured project structure with TypeScript/Vite tooling, proper folder structure, and all essential files needed for extension development. Every Umbraco backoffice extension should start with this template.
Umbraco 扩展模板是官方的.NET模板，用于创建后台扩展。它提供了预配置的项目结构，包含TypeScript/Vite工具链、规范的文件夹结构以及扩展开发所需的所有必要文件。所有Umbraco后台扩展都应从该模板开始创建。

Documentation

文档

Always fetch the latest docs before implementing:
在开始实现前，请务必获取最新文档：

Prerequisites

前提条件

  • .NET SDK 9.0 or later
  • Node.js 22 or later
  • .NET SDK 9.0 或更高版本
  • Node.js 22 或更高版本

Workflow

工作流程

  1. Install template (one-time): 
    dotnet new install Umbraco.Templates
  2. Create extension: 
    dotnet new umbraco-extension -n MyExtension
  3. Install dependencies: 
    cd MyExtension/Client && npm install
  4. Start development: 
    npm run watch
  5. Build for production: 
    npm run build
  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

Commands

命令

Install the Template

安装模板

bash
dotnet new install Umbraco.Templates
bash
dotnet new install Umbraco.Templates

Create New Extension (Basic)

创建新扩展（基础版）

bash
dotnet new umbraco-extension -n MyExtension
bash
dotnet new umbraco-extension -n MyExtension

Create New Extension (With Examples)

创建新扩展（带示例）

bash
dotnet new umbraco-extension -n MyExtension -ex
The 
-ex
flag adds example code including:
  • Sample API controller
  • Swagger API registration
  • Example dashboard component
  • Generated API client
bash
dotnet new umbraco-extension -n MyExtension -ex
-ex
标志会添加示例代码，包括：
  • 示例API控制器
  • Swagger API注册
  • 示例仪表盘组件
  • 生成的API客户端

Project Structure

项目结构

Basic Template

基础模板

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
MyExtension/
├── MyExtension.csproj        # .NET 项目文件
├── Constants.cs              # 扩展常量
├── README.md                 # 安装说明
└── Client/                   # TypeScript 源码
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        └── ...               # 你的扩展代码

With Examples (-ex flag)

带示例版本（-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
MyExtension/
├── MyExtension.csproj
├── Constants.cs
├── README.md
├── Composers/                # C# 组合器
│   └── SwaggerComposer.cs    # API文档配置
├── Controllers/              # C# API控制器
│   └── MyExtensionController.cs
└── Client/
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        ├── api/              # 生成的API客户端
        ├── dashboards/       # 示例仪表盘
        └── entrypoints/      # 扩展入口点

Development Commands

开发命令

bash
undefined
bash
undefined

Navigate to Client folder

进入Client文件夹

cd MyExtension/Client
cd MyExtension/Client

Install dependencies

安装依赖

npm install
npm install

Development with hot reload

带热重载的开发模式

npm run watch
npm run watch

Production build

生产构建

npm run build
npm run build

Type checking

类型检查

npm run check
undefined
npm run check
undefined

Build and Deploy

构建与部署

Publish the Extension

发布扩展

bash
dotnet publish --configuration Release
bash
dotnet publish --configuration Release

Create NuGet Package

创建NuGet包

bash
dotnet pack --configuration Release
bash
dotnet pack --configuration Release

Minimal Example

最简示例

After running the template, add your first manifest in 
Client/src/
:
运行模板后，在
Client/src/
中添加你的第一个清单文件：

manifest.ts

manifest.ts

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

entrypoint.ts

entrypoint.ts

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

export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
  console.log("Extension loaded!");
};
typescript
import type { UmbEntryPointOnInit } from "@umbraco-cms/backoffice/extension-api";

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

IMPORTANT: Add Extension to Umbraco Instance

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

After creating a new extension, you MUST add it as a project reference to the main Umbraco instance. Without this step, the extension will not load.
Reference skill: 
umbraco-add-extension-reference
This skill explains how to add the new extension's 
.csproj
file as a 
<ProjectReference>
in the main Umbraco project (e.g., 
Umbraco-CMS.Skills.csproj
).
创建新扩展后，必须将其作为项目引用添加到主Umbraco实例中。不执行此步骤，扩展将无法加载。
参考技能：
umbraco-add-extension-reference
该技能说明了如何将新扩展的
.csproj
文件作为
<ProjectReference>
添加到主Umbraco项目中（例如
Umbraco-CMS.Skills.csproj
）。

Related Skills

相关技能

After creating your extension, use these skills to add functionality:
  • Sections: Reference skill: 
    umbraco-sections
  • Dashboards: Reference skill: 
    umbraco-dashboard
  • Menus: Reference skill: 
    umbraco-menu
  • Workspaces: Reference skill: 
    umbraco-workspace
  • Trees: Reference skill: 
    umbraco-tree
For complete extension blueprints with working examples:
  • Reference skill: 
    umbraco-backoffice
That's it! Always fetch fresh docs, use the template to scaffold, add the project reference, then add extension types as needed.
创建扩展后，可使用以下技能添加功能：
  • 板块：参考技能：
    umbraco-sections
  • 仪表盘：参考技能：
    umbraco-dashboard
  • 菜单：参考技能：
    umbraco-menu
  • 工作区：参考技能：
    umbraco-workspace
  • 树状结构：参考技能：
    umbraco-tree
如需完整的扩展蓝图及可运行示例：
  • 参考技能：
    umbraco-backoffice
就是这样！请务必获取最新文档，使用模板搭建项目，添加项目引用，然后根据需要添加扩展类型。