Terminal
Terminal/Skill
Add a new Umbraco extension project reference to the main Umbraco instance and solution
By Umbraco
Works with
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-add-extension-referenceAfter 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="18.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="18.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 ignore