umbraco-add-extension-reference

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Extension Reference to Umbraco Instance

向Umbraco实例添加扩展引用

What is it?

说明

After creating a new Umbraco backoffice extension project, it must be added as a project reference in the main Umbraco instance's

.csproj

file. Without this reference, the extension will not be loaded when running the Umbraco site.

If a solution file (

.sln

) exists, the extension should also be added to it for proper IDE support (Visual Studio, Rider). This is optional - the extension will work without being in the solution.

在创建新的Umbraco后台扩展项目后，必须将其作为项目引用添加到主Umbraco实例的

.csproj

文件中。如果没有此引用，运行Umbraco站点时扩展将不会被加载。

如果存在解决方案文件（

.sln

），还应将扩展添加到其中以获得完善的IDE支持（Visual Studio、Rider）。这一步是可选的——即使不在解决方案中，扩展也能正常工作。

When to Use

使用场景

Use this skill after:

Creating a new extension with
```
dotnet new umbraco-extension
```
Moving or copying an extension project to your solution
Setting up a new extension from the
```
umbraco-backoffice
```
blueprints

在以下操作之后使用此技能：

使用
```
dotnet new umbraco-extension
```
创建新扩展
将扩展项目移动或复制到你的解决方案中
基于
```
umbraco-backoffice
```
蓝图搭建新扩展

Workflow

操作流程

Step 1: Find the Main Umbraco Project

步骤1：找到主Umbraco项目

The main Umbraco instance

.csproj

file must be discovered dynamically. Search for it using these criteria:

bash

undefined

需要动态定位主Umbraco实例的

.csproj

文件。可通过以下条件搜索：

bash

undefined

Find all .csproj files

查找所有.csproj文件

Glob: **/*.csproj

Then search for the one containing Umbraco.Cms package reference

然后在.csproj文件中搜索包含Umbraco.Cms包引用的文件

Grep: Umbraco.Cms" Version (in *.csproj files)


The main Umbraco project will have:
- A `<PackageReference Include="Umbraco.Cms" ...>` entry
- SDK of `Microsoft.NET.Sdk.Web`
- Usually located at the solution root or in a dedicated folder

Grep: Umbraco.Cms" Version (在*.csproj文件中)


主Umbraco项目具备以下特征：
- 包含`<PackageReference Include="Umbraco.Cms" ...>`条目
- 使用`Microsoft.NET.Sdk.Web` SDK
- 通常位于解决方案根目录或专用文件夹中

Step 2: Read the Project File

步骤2：读取项目文件

Once found, read the

.csproj

file to understand its structure and find where

<ProjectReference>

entries are located.

找到主项目文件后，读取

.csproj

文件以了解其结构，并确定

<ProjectReference>

条目的位置。

Step 3: Calculate Relative Path

步骤3：计算相对路径

Calculate the relative path from the main project's directory to the new extension's

.csproj

file:

Use forward slashes
```
/
```
(cross-platform compatible)
Path is relative to the main
```
.csproj
```
file's directory

Example paths:

Extension Location	Example Relative Path
Sibling folder	`../MyExtension/MyExtension.csproj`
Subfolder	`./extensions/MyExtension/MyExtension.csproj`
Skills folder	`../.claude/skills/.../MyExtension.csproj`

计算从主项目目录到新扩展的

.csproj

文件的相对路径：

使用正斜杠
```
/
```
（跨平台兼容）
路径是相对于主
```
.csproj
```
文件所在目录的路径

路径示例：

扩展位置	示例相对路径
同级文件夹	`../MyExtension/MyExtension.csproj`
子文件夹	`./extensions/MyExtension/MyExtension.csproj`
Skills文件夹	`../.claude/skills/.../MyExtension.csproj`

Step 4: Add the ProjectReference

步骤4：添加ProjectReference

Add a

<ProjectReference>

entry in an

<ItemGroup>

xml

<ItemGroup>
  <!-- Existing references -->
  <ProjectReference Include="../ExistingExtension/ExistingExtension.csproj" />
  <!-- Add new extension here -->
  <ProjectReference Include="../NewExtension/NewExtension.csproj" />
</ItemGroup>

If there's already an

<ItemGroup>

with

<ProjectReference>

entries, add to that one. Otherwise, create a new

<ItemGroup>

在

<ItemGroup>

中添加

<ProjectReference>

条目：

xml

<ItemGroup>
  <!-- 现有引用 -->
  <ProjectReference Include="../ExistingExtension/ExistingExtension.csproj" />
  <!-- 在此处添加新扩展 -->
  <ProjectReference Include="../NewExtension/NewExtension.csproj" />
</ItemGroup>

如果已有包含

<ProjectReference>

条目的

<ItemGroup>

，则添加到该组中。否则，创建一个新的

<ItemGroup>

。

Step 5: Add Extension to Solution File (Optional)

步骤5：将扩展添加到解决方案文件（可选）

If a solution file (

.sln

) exists, the extension project should be added to it for proper IDE support. This step is optional - not all projects use solution files.

Find the solution file:

bash

undefined

如果存在解决方案文件（

.sln

），应将扩展项目添加到其中以获得完善的IDE支持。此步骤是可选的——并非所有项目都使用解决方案文件。

查找解决方案文件：

bash

undefined

Find any .sln files in the workspace

在工作区中查找所有.sln文件

Glob: **/*.sln


**Scenarios to handle:**

| Scenario | Action |
|----------|--------|
| No `.sln` file found | Skip this step - it's not required |
| One `.sln` file found | Add the extension to it |
| Multiple `.sln` files found | Ask the user which solution to use |
| Extension already in solution | `dotnet sln add` will report this - safe to ignore |

**Add the extension project to the solution:**
```bash
dotnet sln <path-to-solution.sln> add <path-to-extension.csproj>

Example:

bash

undefined

Glob: **/*.sln


**需处理的场景：**

| 场景 | 操作 |
|----------|--------|
| 未找到`.sln`文件 | 跳过此步骤——这不是必需的 |
| 找到一个`.sln`文件 | 将扩展添加到该解决方案中 |
| 找到多个`.sln`文件 | 询问用户要使用哪个解决方案 |
| 扩展已在解决方案中 | `dotnet sln add`会报告此情况——可安全忽略 |

**将扩展项目添加到解决方案：**
```bash
dotnet sln <path-to-solution.sln> add <path-to-extension.csproj>

示例：

bash

undefined

If solution is at ./MySite/MySite.sln and extension is at ./MyExtension/MyExtension.csproj

如果解决方案位于./MySite/MySite.sln，扩展位于./MyExtension/MyExtension.csproj

dotnet sln ./MySite/MySite.sln add ./MyExtension/MyExtension.csproj


When a solution file exists, adding the extension ensures:
- The extension appears in Visual Studio/Rider solution explorer
- Building the solution builds the extension
- IDE features like "Go to Definition" work across projects

dotnet sln ./MySite/MySite.sln add ./MyExtension/MyExtension.csproj


当存在解决方案文件时，添加扩展可确保：
- 扩展出现在Visual Studio/Rider的解决方案资源管理器中
- 构建解决方案时会同时构建扩展
- IDE的“转到定义”等功能可跨项目使用

Example

示例

Before

添加前

xml

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Umbraco.Cms" Version="16.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="../BlankExtension/BlankExtension.csproj" />
  </ItemGroup>
</Project>

xml

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Umbraco.Cms" Version="16.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="../BlankExtension/BlankExtension.csproj" />
  </ItemGroup>
</Project>

After Adding "MyNewExtension"

添加“MyNewExtension”后

xml

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Umbraco.Cms" Version="16.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="../BlankExtension/BlankExtension.csproj" />
    <ProjectReference Include="../MyNewExtension/MyNewExtension.csproj" />
  </ItemGroup>
</Project>

xml

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Umbraco.Cms" Version="16.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="../BlankExtension/BlankExtension.csproj" />
    <ProjectReference Include="../MyNewExtension/MyNewExtension.csproj" />
  </ItemGroup>
</Project>

Implementation Checklist

实施检查清单

Discover the main Umbraco project using Glob + Grep for
```
Umbraco.Cms
```
Read the main project file to understand structure
Calculate relative path from main project to new extension
Verify the extension
```
.csproj
```
file exists at the calculated path
Edit the main project file to add
```
<ProjectReference>
```
Check for a solution file (
```
.sln
```
) using Glob
If found, add the extension to the solution using
```
dotnet sln add
```
Ask user to verify with
```
dotnet build
```

发现：使用Glob + Grep查找包含
```
Umbraco.Cms
```
的主Umbraco项目
读取：读取主项目文件以了解其结构
计算：计算从主项目到新扩展的相对路径
验证：验证扩展
```
.csproj
```
文件是否存在于计算出的路径中
编辑：编辑主项目文件以添加
```
<ProjectReference>
```
检查：使用Glob查找解决方案文件（
```
.sln
```
）
如果找到：使用
```
dotnet sln add
```
将扩展添加到解决方案中
询问用户：请用户使用
```
dotnet build
```
进行验证

Verification

验证

After adding the reference, the user should verify by:

Building the solution:
```
dotnet build
```
Running the Umbraco instance:
```
dotnet run
```
Checking the backoffice loads the extension

添加引用后，用户应通过以下步骤进行验证：

构建解决方案：
```
dotnet build
```
运行Umbraco实例：
```
dotnet run
```
检查后台是否加载了扩展

Troubleshooting

故障排除

Build error: Project not found

Check the relative path is correct
Verify the extension
```
.csproj
```
file exists
Ensure forward slashes are used in the path

Extension not loading

Verify the extension has been built:

cd ExtensionName/Client && npm run build

Check the
```
umbraco-package.json
```
exists in the extension's
```
wwwroot
```
folder
Look for errors in the browser console

Multiple Umbraco projects found

If there are multiple
```
.csproj
```
files with
```
Umbraco.Cms
```
, ask the user which one is the main instance
The main instance is typically the one with
```
Microsoft.NET.Sdk.Web
```
SDK and a
```
Program.cs
```
or
```
Startup.cs
```

No solution file found

This is fine - solution files are optional
The
```
<ProjectReference>
```
in the
```
.csproj
```
is sufficient for the extension to work
Skip the solution step and proceed with verification

Multiple solution files found

Ask the user which solution they want the extension added to
Common scenarios: separate solutions for different IDEs, test solutions, etc.

Extension already in solution

```
dotnet sln add
```
will report the project is already added - this is safe to ignore
The command is idempotent and won't create duplicates

构建错误：未找到项目

检查相对路径是否正确
验证扩展
```
.csproj
```
文件是否存在
确保路径中使用了正斜杠

扩展未加载

验证扩展是否已构建：

cd ExtensionName/Client && npm run build

检查扩展的
```
wwwroot
```
文件夹中是否存在
```
umbraco-package.json
```
查看浏览器控制台中的错误信息

找到多个Umbraco项目

如果存在多个包含
```
Umbraco.Cms
```
的
```
.csproj
```
文件，请询问用户哪个是主实例

主实例通常使用

Microsoft.NET.Sdk.Web

SDK，并包含

Program.cs

或

Startup.cs

未找到解决方案文件

这是正常的——解决方案文件是可选的
```
.csproj
```
中的
```
<ProjectReference>
```
已足够让扩展正常工作
跳过解决方案步骤，直接进行验证

找到多个解决方案文件

询问用户要将扩展添加到哪个解决方案中
常见场景：不同IDE的独立解决方案、测试解决方案等

扩展已在解决方案中

```
dotnet sln add
```
会报告项目已添加——这是安全的，可忽略
该命令具有幂等性，不会创建重复项