umbraco-add-extension-reference by umbraco/umbraco-cms-backoffice-skills
npx skills add https://github.com/umbraco/umbraco-cms-backoffice-skills --skill umbraco-add-extension-reference在创建新的 Umbraco 后台扩展项目后,必须将其作为项目引用添加到主 Umbraco 实例的 .csproj 文件中。没有此引用,运行 Umbraco 站点时将不会加载该扩展。
如果存在解决方案文件(.sln),为了获得更好的 IDE 支持(Visual Studio、Rider),也应将扩展添加到其中。这是可选的——扩展即使不在解决方案中也能工作。
在以下情况后使用此技能:
dotnet new umbraco-extension 创建新扩展后umbraco-backoffice 蓝图设置新扩展后必须动态发现主 Umbraco 实例的 .csproj 文件。使用以下条件进行搜索:
# 查找所有 .csproj 文件
Glob: **/*.csproj
# 然后搜索包含 Umbraco.Cms 包引用的文件
Grep: Umbraco\.Cms" Version (在 *.csproj 文件中)
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
主 Umbraco 项目将具有:
<PackageReference Include="Umbraco.Cms" ...> 条目Microsoft.NET.Sdk.Web找到后,读取 .csproj 文件以了解其结构并找到 <ProjectReference> 条目的位置。
计算从主项目目录到新扩展的 .csproj 文件的相对路径:
/(跨平台兼容).csproj 文件所在的目录示例路径:
| 扩展位置 | 示例相对路径 |
|---|---|
| 同级文件夹 | ../MyExtension/MyExtension.csproj |
| 子文件夹 | ./extensions/MyExtension/MyExtension.csproj |
| Skills 文件夹 | ../.claude/skills/.../MyExtension.csproj |
在 <ItemGroup> 中添加一个 <ProjectReference> 条目:
<ItemGroup>
<!-- 现有引用 -->
<ProjectReference Include="../ExistingExtension/ExistingExtension.csproj" />
<!-- 在此处添加新扩展 -->
<ProjectReference Include="../NewExtension/NewExtension.csproj" />
</ItemGroup>
如果已存在包含 <ProjectReference> 条目的 <ItemGroup>,则添加到该组中。否则,创建一个新的 <ItemGroup>。
如果存在解决方案文件(.sln),为了获得适当的 IDE 支持,应将扩展项目添加到其中。此步骤是可选的——并非所有项目都使用解决方案文件。
查找解决方案文件:
# 在工作区中查找任何 .sln 文件
Glob: **/*.sln
需要处理的场景:
| 场景 | 操作 |
|---|---|
未找到 .sln 文件 | 跳过此步骤 - 不是必需的 |
找到一个 .sln 文件 | 将扩展添加到其中 |
找到多个 .sln 文件 | 询问用户要使用哪个解决方案 |
| 扩展已在解决方案中 | dotnet sln add 会报告此情况 - 可以安全忽略 |
将扩展项目添加到解决方案:
dotnet sln <path-to-solution.sln> add <path-to-extension.csproj>
示例:
# 如果解决方案位于 ./MySite/MySite.sln 且扩展位于 ./MyExtension/MyExtension.csproj
dotnet sln ./MySite/MySite.sln add ./MyExtension/MyExtension.csproj
当存在解决方案文件时,添加扩展可确保:
<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>
<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>
Umbraco.Cms.csproj 文件存在于计算出的路径<ProjectReference>.sln),使用 Globdotnet sln add 将扩展添加到解决方案dotnet build 进行验证添加引用后,用户应通过以下方式验证:
dotnet builddotnet run构建错误:找不到项目
.csproj 文件是否存在扩展未加载
cd ExtensionName/Client && npm run buildwwwroot 文件夹中是否存在 umbraco-package.json找到多个 Umbraco 项目
Umbraco.Cms 的 .csproj 文件,询问用户哪个是主实例Microsoft.NET.Sdk.Web SDK 和 Program.cs 或 Startup.cs 的那个未找到解决方案文件
.csproj 中的 <ProjectReference> 足以让扩展工作找到多个解决方案文件
扩展已在解决方案中
dotnet sln add 会报告项目已添加 - 这可以安全忽略每周安装次数
75
仓库
GitHub 星标数
17
首次出现
2026 年 2 月 4 日
安全审计
安装于
github-copilot54
cursor24
opencode23
codex23
gemini-cli20
amp20
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.
Use this skill after:
dotnet new umbraco-extensionumbraco-backoffice blueprintsThe main Umbraco instance .csproj file must be discovered dynamically. Search for it using these criteria:
# Find all .csproj files
Glob: **/*.csproj
# Then search for the one containing Umbraco.Cms package reference
Grep: Umbraco\.Cms" Version (in *.csproj files)
The main Umbraco project will have:
<PackageReference Include="Umbraco.Cms" ...> entryMicrosoft.NET.Sdk.WebOnce found, read the .csproj file to understand its structure and find where <ProjectReference> entries are located.
Calculate the relative path from the main project's directory to the new extension's .csproj file:
/ (cross-platform compatible).csproj file's directoryExample paths:
| Extension Location | Example Relative Path |
|---|---|
| Sibling folder | ../MyExtension/MyExtension.csproj |
| Subfolder | ./extensions/MyExtension/MyExtension.csproj |
| Skills folder | ../.claude/skills/.../MyExtension.csproj |
Add a <ProjectReference> entry in an <ItemGroup>:
<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>.
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:
# Find any .sln files in the workspace
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:
dotnet sln <path-to-solution.sln> add <path-to-extension.csproj>
Example:
# If solution is at ./MySite/MySite.sln and extension is at ./MyExtension/MyExtension.csproj
dotnet sln ./MySite/MySite.sln add ./MyExtension/MyExtension.csproj
When a solution file exists, adding the extension ensures:
<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>
<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>
Umbraco.Cms.csproj file exists at the calculated path<ProjectReference>.sln) using Globdotnet sln adddotnet buildAfter adding the reference, the user should verify by:
dotnet builddotnet runBuild error: Project not found
.csproj file existsExtension not loading
cd ExtensionName/Client && npm run buildumbraco-package.json exists in the extension's wwwroot folderMultiple Umbraco projects found
.csproj files with Umbraco.Cms, ask the user which one is the main instanceMicrosoft.NET.Sdk.Web SDK and a Program.cs or Startup.csNo solution file found
<ProjectReference> in the .csproj is sufficient for the extension to workMultiple solution files found
Extension already in solution
dotnet sln add will report the project is already added - this is safe to ignoreWeekly Installs
75
Repository
GitHub Stars
17
First Seen
Feb 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
github-copilot54
cursor24
opencode23
codex23
gemini-cli20
amp20
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
120,000 周安装
OpenMAIC 使用指南:AI 课堂生成工具部署与配置全流程详解
131 周安装
Playwright端到端测试最佳实践:TypeScript/JavaScript自动化测试指南
132 周安装
esbuild 极速打包工具配置指南:JavaScript/TypeScript 构建专家教程
133 周安装
Contact Hunter:AI驱动的联系人信息查找与丰富工具 - 支持人员、公司、职位搜索
131 周安装
Koa TypeScript开发指南:洋葱模型中间件与API构建最佳实践
136 周安装
Excalidraw MCP 技能:AI 驱动图表绘制与自动化工具使用指南
133 周安装