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 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 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 entry in an : < ItemGroup

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

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

If there's already an with entries, add to that one. Otherwise, create a new . 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 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 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 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 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 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