umbraco-add-extension-reference

将扩展引用添加到 Umbraco 实例

这是什么？

创建新的 Umbraco 后台扩展项目后，必须将其作为项目引用添加到主 Umbraco 实例的 .csproj 文件中。没有此引用，运行 Umbraco 站点时将不会加载该扩展。

如果存在解决方案文件（.sln），还应将扩展添加到其中，以便 IDE 提供正确支持（Visual Studio、Rider）。此操作为可选项——即使不将扩展添加到解决方案中，它也能正常运行。

何时使用

在以下情况后使用此技能：

• 使用 dotnet new umbraco-extension 创建新扩展
• 将扩展项目移动或复制到解决方案中
• 根据 umbraco-backoffice 蓝图设置新扩展

工作流

步骤 1：查找主 Umbraco 项目

必须动态查找主 Umbraco 实例的 .csproj 文件。使用以下条件进行搜索：

# Find all .csproj files
Glob: **/*.csproj

# Then search for the one containing Umbraco.Cms package reference
Grep: Umbraco\.Cms" Version  (in *.csproj files)

主 Umbraco 项目具有以下特征：

• 包含 <PackageReference Include="Umbraco.Cms" ...> 条目
• SDK 为 Microsoft.NET.Sdk.Web
• 通常位于解决方案根目录或专用文件夹中

步骤 2：读取项目文件

找到后，读取 .csproj 文件以了解其结构，并查找 <ProjectReference> 条目的位置。

步骤 3：计算相对路径

计算从主项目目录到新扩展 .csproj 文件的相对路径：

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

路径示例：

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

步骤 4：添加 ProjectReference

在 <ItemGroup> 中添加 <ProjectReference> 条目：

<ItemGroup>
  
  <ProjectReference Include="../ExistingExtension/ExistingExtension.csproj" />
  
  <ProjectReference Include="../NewExtension/NewExtension.csproj" />
</ItemGroup>

如果已有包含 <ProjectReference> 条目的 <ItemGroup>，请将其添加到该组中。否则，创建新的 <ItemGroup>。

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

如果存在解决方案文件（.sln），应将扩展项目添加到其中，以便 IDE 提供正确支持。此步骤为可选项——并非所有项目都使用解决方案文件。

查找解决方案文件：

# Find any .sln files in the workspace
Glob: **/*.sln

需要处理的情况：

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

将扩展项目添加到解决方案：

dotnet sln <path-to-solution.sln> add <path-to-extension.csproj>

示例：

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

存在解决方案文件时，添加扩展可确保：

• 扩展显示在 Visual Studio/Rider 解决方案资源管理器中
• 生成解决方案时也会生成扩展
• “转到定义”等 IDE 功能可跨项目使用

示例

添加前

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

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

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

添加“MyNewExtension”后

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

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

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

实施清单

1. 使用 Glob + Grep 搜索 Umbraco.Cms，发现主 Umbraco 项目
2. 读取主项目文件以了解其结构
3. 计算从主项目到新扩展的相对路径
4. 验证扩展 .csproj 文件是否存在于计算出的路径
5. 编辑主项目文件以添加 <ProjectReference>
6. 使用 Glob 检查是否存在解决方案文件（.sln）
7. 如果找到，使用 dotnet sln add 将扩展添加到解决方案
8. 请用户使用 dotnet build 进行验证

验证

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

1. 生成解决方案：dotnet build
2. 运行 Umbraco 实例：dotnet run
3. 检查后台是否加载了扩展

故障排查

构建错误：未找到项目

• 检查相对路径是否正确
• 确认扩展的 .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 会提示项目已添加——可以放心忽略
• 该命令具有幂等性，不会创建重复项