Add Extension Reference to Umbraco Instance

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.

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

Workflow

Step 1: Find the Main Umbraco Project

The 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:

• A <PackageReference Include="Umbraco.Cms" ...> entry
• SDK of Microsoft.NET.Sdk.Web
• Usually located at the solution root or in a dedicated folder

Step 2: Read the Project File

Once found, read the .csproj file to understand its structure and find where <ProjectReference> entries are located.

Step 3: Calculate Relative Path

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

Step 4: Add the ProjectReference

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>.

Step 5: Add Extension to Solution File (Optional)

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:

• The extension appears in Visual Studio/Rider solution explorer
• Building the solution builds the extension
• IDE features like "Go to Definition" work across projects

Example

Before

<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"

<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

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

Verification

After adding the reference, the user should verify by:

1. Building the solution: dotnet build
2. Running the Umbraco instance: dotnet run
3. Checking the backoffice loads the extension

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