Umbraco-CMS Documentation

File: CLAUDE.md Copy Chapter

Umbraco CMS - Multi-Project Repository

Enterprise-grade CMS built on .NET 10.0. This repository contains 21 production projects organized in a layered architecture with clear separation of concerns.

Repository: https://github.com/umbraco/Umbraco-CMS
License: MIT
Main Branch: main

1. Overview Copy Chapter

What This Repository Contains Copy Section

21 Production Projects organized in 3 main categories:

1. Core Architecture (Domain & Infrastructure)

   • Umbraco.Core - Interface contracts, domain models, notifications
   • Umbraco.Infrastructure - Service implementations, data access, caching

2. Web & APIs (Presentation Layer)

   • Umbraco.Web.UI - Main ASP.NET Core web application
   • Umbraco.Web.Common - Shared web functionality, controllers, middleware
   • Umbraco.Cms.Api.Management - Backoffice Management API (REST)
   • Umbraco.Cms.Api.Delivery - Content Delivery API (headless)
   • Umbraco.Cms.Api.Common - Shared API infrastructure

3. Specialized Features (Pluggable Modules)

   • Persistence: EF Core (modern), NPoco (legacy) for SQL Server & SQLite
   • Caching: PublishedCache.HybridCache (in-memory + distributed)
   • Search: Examine.Lucene (full-text search)
   • Imaging: Imaging.ImageSharp v1 & v2 (image processing)
   • Other: Static assets, targets, development tools

6 Test Projects:

• Umbraco.Tests.Common - Shared test utilities
• Umbraco.Tests.UnitTests - Unit tests
• Umbraco.Tests.Integration - Integration tests
• Umbraco.Tests.Benchmarks - Performance benchmarks
• Umbraco.Tests.AcceptanceTest - E2E tests
• Umbraco.Tests.AcceptanceTest.UmbracoProject - Test instance

Key Technologies Copy Section

• .NET 10.0 - Target framework for all projects
• ASP.NET Core - Web framework
• Entity Framework Core - Modern ORM
• OpenIddict - OAuth 2.0/OpenID Connect authentication
• Microsoft.AspNetCore.OpenApi - OpenAPI document generation
• Swashbuckle.AspNetCore.SwaggerUI - Swagger UI for API documentation
• Lucene.NET - Full-text search via Examine
• ImageSharp - Image processing

2. General-Purpose by Default Copy Chapter

This repository is a product platform, not an application. Every layer is consumed by code that does not live here — implementors, package developers, and other parts of the CMS. A change is finished when it serves the use case that prompted it and the use cases nobody has described yet.

Design to the contract. When you change shared code, work out the rule the layer must uphold for any implementation of it, and make that rule hold there. Name a concrete implementation freely in the code that owns it — a specific service, package, or project; a shared or generic layer implements only the contract. A specific editor alias, content type alias, or class name appearing in generic code is the signal that a fix has been fitted to one caller — express it instead as a capability the contract exposes.

Describe the contract. Comments and public docs use the vocabulary of the layer they sit in. In public XML doc / JSDoc a concrete illustration is welcome where it reads as one possible implementation ("for example, an editor that emits several groups may…"), never as the definition of the behaviour.

3. Repository Structure Copy Chapter

Umbraco-CMS/
├── src/                                    # 21 production projects
│   ├── Umbraco.Core/                      # Domain contracts (interfaces only)
│   │   └── CLAUDE.md                      # ⭐ Core architecture guide
│   ├── Umbraco.Infrastructure/            # Service implementations
│   ├── Umbraco.Web.Common/                # Web utilities
│   ├── Umbraco.Web.UI/                    # Main web application
│   ├── Umbraco.Cms.Api.Management/        # Management API
│   ├── Umbraco.Cms.Api.Delivery/          # Delivery API (headless)
│   ├── Umbraco.Cms.Api.Common/            # Shared API infrastructure
│   │   └── CLAUDE.md                      # ⭐ API patterns guide
│   ├── Umbraco.PublishedCache.HybridCache/ # Content caching
│   ├── Umbraco.Examine.Lucene/            # Search indexing
│   ├── Umbraco.Cms.Persistence.EFCore/    # EF Core data access
│   ├── Umbraco.Cms.Persistence.EFCore.Sqlite/
│   ├── Umbraco.Cms.Persistence.EFCore.SqlServer/
│   ├── Umbraco.Cms.Persistence.Sqlite/    # Legacy SQLite
│   ├── Umbraco.Cms.Persistence.SqlServer/ # Legacy SQL Server
│   ├── Umbraco.Cms.Imaging.ImageSharp/    # Image processing v1
│   ├── Umbraco.Cms.Imaging.ImageSharp2/   # Image processing v2
│   ├── Umbraco.Cms.StaticAssets/          # Embedded assets
│   ├── Umbraco.Cms.DevelopmentMode.Backoffice/
│   ├── Umbraco.Cms.Targets/               # NuGet targets
│   └── Umbraco.Cms/                       # Meta-package
│
├── tests/                                  # 6 test projects
│   ├── Umbraco.Tests.Common/
│   ├── Umbraco.Tests.UnitTests/
│   ├── Umbraco.Tests.Integration/
│   ├── Umbraco.Tests.Benchmarks/
│   ├── Umbraco.Tests.AcceptanceTest/
│   └── Umbraco.Tests.AcceptanceTest.UmbracoProject/
│
├── templates/                              # Project templates
│   └── Umbraco.Templates/
│
├── tools/                                  # Build tools
│   └── Umbraco.JsonSchema/
│
├── umbraco.sln                            # Main solution file
├── Directory.Build.props                  # Shared build configuration
├── Directory.Packages.props               # Centralized package versions
├── .editorconfig                          # Code style
└── .globalconfig                          # Roslyn analyzers

Architecture Layers Copy Section

Dependency Flow (unidirectional, always flows inward):

Web.UI → Web.Common → Infrastructure → Core
                ↓
          Api.Management → Api.Common → Infrastructure → Core
                ↓
          Api.Delivery → Api.Common → Infrastructure → Core

Key Principle: Core has NO dependencies (pure contracts). Infrastructure implements Core. Web/APIs depend on Infrastructure.

Project Dependencies Copy Section

Core Layer:

• Umbraco.Core → No dependencies (only Microsoft.Extensions.*)

Infrastructure Layer:

• Umbraco.Infrastructure → Umbraco.Core
• Umbraco.PublishedCache.* → Umbraco.Infrastructure
• Umbraco.Examine.Lucene → Umbraco.Infrastructure
• Umbraco.Cms.Persistence.* → Umbraco.Infrastructure

Web Layer:

• Umbraco.Web.Common → Umbraco.Infrastructure + caching + search
• Umbraco.Web.UI → Umbraco.Web.Common + all features

API Layer:

• Umbraco.Cms.Api.Common → Umbraco.Web.Common
• Umbraco.Cms.Api.Management → Umbraco.Cms.Api.Common
• Umbraco.Cms.Api.Delivery → Umbraco.Cms.Api.Common

4. Teamwork & Collaboration Copy Chapter

Branching Strategy Copy Section

• Main branch: main (protected)
• Branch naming convention: v<version>/<type>/<description>

Format: v{major-version}/{type}/{kebab-case-description}

Version: Read from version.json in the repository root. Use the major version number (e.g., v17 for version 17.x.x).

Types:

Description: A short, kebab-case description (a few words). This should be prefixed with the GitHub issue number if the update is related to resolving a tracked issue.

Examples:

v17/bugfix/12345-correct-display-of-pending-migrations
v17/feature/add-webhook-support
v17/improvement/optimize-content-cache
v17/qa/add-media-service-tests
v17/task/update-ef-core-dependency

See .github/CONTRIBUTING.md for full guidelines.

Pull Request Process Copy Section

• PR Template: .github/pull_request_template.md
• Required CI Checks:
  • All tests pass
  • Code formatting (dotnet format)
  • No build warnings
• Merge Strategy: Squash and merge (via GitHub UI)
• Reviews: Required from code owners

PR Naming Convention

Use the format: Area: Description (closes #IssueID)

Examples:

Area: The feature or aspect affected (e.g., UFM, TipTap, Docs, Segmentation, Migrations). Helps readers quickly understand what is being changed.

Description Best Practices:

• Include the area of change (Relations, Management API, etc.)
• Describe the change and its impact
• Be specific, not vague (describe "a golden retriever" not just "a dog")

Issue Linking: Add (closes #IssueID) to the title for readability, AND include a closing keyword on its own line in the PR body (e.g., Fixes #IssueID) so GitHub actually auto-links and auto-closes the issue on merge. GitHub only parses closing keywords (closes, fixes, resolves) from the PR body or commit messages — the title suffix is cosmetic and does not trigger auto-close on its own.

Commit Messages Copy Section

Follow Conventional Commits format:

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore
Scope: project name (core, web, api, etc.)

Examples:
feat(core): add IContentService.GetByIds method
fix(api): resolve null reference in schema handler
docs(web): update routing documentation

Code Owners Copy Section

Project ownership is distributed across teams. Check individual project directories for ownership.

5. Architecture Patterns Copy Chapter

Core Architectural Decisions Copy Section

1. Layered Architecture with Dependency Inversion

   • Core defines contracts (interfaces)
   • Infrastructure implements contracts that need Infrastructure-owned machinery
   • Web/APIs consume implementations via DI

   Where service implementations live: Services whose dependencies are satisfiable from Core interfaces alone (repositories, scope, config, other Core services) live in Umbraco.Core/Services/ — this covers the majority of domain services (MemberService, ContentService, MediaService, ContentTypeService, EntityService, AuditService, ExternalMemberService, etc.). Service implementations only live in Umbraco.Infrastructure/Services/Implement/ when they genuinely need Infrastructure concerns — Examine indexes (ContentSearchService, MediaSearchService, IndexedEntitySearchService), log files (LogViewerRepository), packaging internals (PackagingService), webhook firing (WebhookFiringService), distributed-job coordination (DistributedJobService). When adding a new service, default to Core and only move to Infrastructure if a concrete dependency forces it.

2. Interface-First Design

   • All services defined as interfaces in Core
   • Enables testing, polymorphism, extensibility

3. Notification Pattern (not C# events)

   • See /src/Umbraco.Core/CLAUDE.md → "2. Notification System (Event Handling)"

4. Composer Pattern (DI registration)

   • See /src/Umbraco.Core/CLAUDE.md → "3. Composer Pattern (DI Registration)"

5. Scoping Pattern (Unit of Work)

   • See /src/Umbraco.Core/CLAUDE.md → "5. Scoping Pattern (Unit of Work)"

6. Attempt Pattern (operation results)

   • Attempt instead of exceptions
   • Strongly-typed operation status enums

Key Design Patterns Used Copy Section

• Repository Pattern - Data access abstraction
• Unit of Work - Scoping for transactions
• Builder Pattern - ProblemDetailsBuilder for API errors
• Strategy Pattern - OpenAPI handlers (schema ID, operation ID)
• Options Pattern - All configuration via IOptions<T>
• Factory Pattern - Content type factories
• Mediator Pattern - Notification aggregator

6. Avoiding Breaking Changes Copy Chapter

No binary breaking changes are allowed within a major version. Three patterns are used:

6.1 Obsolete Constructor + StaticServiceProvider Copy Section

When a public class needs new dependencies, obsolete the existing constructor and add a new one. The old constructor delegates to the new one, resolving missing deps via StaticServiceProvider.

[Obsolete("Please use the constructor with all parameters. Scheduled for removal in Umbraco 19.")]
public MyService(IDependencyA depA)
    : this(
        depA,
        StaticServiceProvider.Instance.GetRequiredService<IDependencyB>())
{
}

public MyService(IDependencyA depA, IDependencyB depB)
{
    _depA = depA;
    _depB = depB;
}

Examples:

• ContentCollectionPresentationFactory - added FlagProviderCollection
• CacheInstructionService - added ILastSyncedManager, IRepositoryCacheVersionService
• DocumentPresentationFactory - added FlagProviderCollection

Rules:

• Old constructor marked [Obsolete("... Scheduled for removal in Umbraco {current-major+2}.")]
• Old constructor calls new constructor via : this(...)
• Uses StaticServiceProvider.Instance.GetRequiredService<T>() for new params only
• DI registration must use the NEW constructor (old is for external consumers only)

6.2 Obsolete Method + New Overload Copy Section

When a public method signature needs to change, add the new method/overload and obsolete the old. The obsolete method should call the new one with suitable defaults.

[Obsolete("Use the overload taking all parameters. Scheduled for removal in Umbraco 19.")]
public void DoThing(string name)
    => DoThing(name, extraParam: null);

public void DoThing(string name, string? extraParam)
{
    // Real implementation here
}

Rules:

• Old method marked [Obsolete] with removal schedule
• DRY: old method calls new method, providing defaults for new parameters
• All internal callers must be updated to use the new method
• No callers should remain on the obsolete method within the codebase

6.3 Default Interface Implementation Copy Section

When adding methods to a public interface, provide a default implementation so existing external implementations don't break.

public interface IMyService
{
    // Existing method
    void ExistingMethod();

    // New method with default implementation
    void NewMethod(string param)
        => ExistingMethod(); // delegate to existing if possible
}

Strategies for the default (in order of preference):

1. Use existing interface methods to satisfy the contract (even if not optimal)
2. Return a sensible default like empty collection, null, etc.
3. Throw NotImplementedException if no reasonable default exists

Example: IContentService.SaveBlueprint - new overload with IContent? createdFromContent has a default impl that calls the old method (ignoring the new param).

Example: IDocumentPresentationFactory.CreateCulturePublishScheduleModels - full default implementation with logic, uses StaticServiceProvider for dependency resolution within the interface.

Rules:

• Add // TODO (V{next-major}): Remove the default implementation when {obsolete method} is removed. comment
• Default impl should be functionally correct even if not optimal
• If using StaticServiceProvider in a default impl, note this is temporary

6.4 General Rules Copy Section

• Removal policy: Obsoleted members must remain for at least one full major version before removal. If obsoleted in version N, the earliest removal is version N+2. For example, something obsoleted in v17 is scheduled for removal in v19 (giving the whole of v18 as a deprecation period).
• All [Obsolete] attributes must include "Scheduled for removal in Umbraco {current+2}"
• Read version.json to determine the current major version
• Suppress CS0618 warnings where obsolete members must call each other:
  csharp Copy

  #pragma warning disable CS0618 // Type or member is obsolete
      => OldMethod(param);
  #pragma warning restore CS0618 // Type or member is obsolete

• Update ALL internal callers to use the new API - no internal code should use obsolete members

7. Project-Specific Notes Copy Chapter

Centralized Package Management Copy Section

NuGet package versions are centralized in Directory.Packages.props. There are two Directory.Packages.props files in the source tree, with multi-level merging enabled so the test file inherits from the root:

When updating dependencies, decide which file the package belongs in:

• A package used only by test projects → tests/Directory.Packages.props
• A package used by any production project (or by both production and tests) → root Directory.Packages.props

<!-- Individual projects reference WITHOUT version -->
<PackageReference Include="Microsoft.AspNetCore.OpenApi" />

<!-- Versions defined in Directory.Packages.props -->
<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />

Opt-out: src/Umbraco.Web.UI/Umbraco.Web.UI.csproj sets <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally> and specifies versions inline (for Microsoft.EntityFrameworkCore.Design, Microsoft.Build.Tasks.Core, Microsoft.ICU.ICU4C.Runtime, etc.). Update those versions directly in that csproj when bumping. Two further Directory.Packages.props files exist under templates/ for the project/extension templates and have their own version sets — keep Microsoft.AspNetCore.OpenApi aligned between the root file and templates/UmbracoExtension/.

Build Configuration Copy Section

• Directory.Build.props - Shared properties (target framework, company, copyright)
• .editorconfig - Code style rules
• .globalconfig - Roslyn analyzer rules

SBOM Generation & License Policy (Azure Pipelines) Copy Section

build/azure-pipelines.yml generates a CycloneDX SBOM per project (Backend/NuGet, Login UI, Backoffice, E2E), each in its own job in the Dependency_Track stage, via umbraco-sbom (the Umbraco.Internal.Sbom .NET 10 global tool), not plain dotnet CycloneDX / @cyclonedx/cyclonedx-npm. It adds license-policy enforcement over CycloneDX. Repo (private): https://github.com/umbraco/Umbraco.Internal.Sbom — README has the full flag/exit-code/policy reference.

When editing those steps:

• Output filenames and artifacts (bom-dotnet.xml, bom-login.xml, bom-backoffice.xml, bom-e2e.xml) are mapped to Dependency-Track projects in the stage's build/templates/dependency-track.yml parameters — keep them in step.
• Usage: umbraco-sbom --output-file <full-path> [policy flags]. Only --output-file plus policy flags (--allow-package, --allow-commercial, --allow-copyleft, --fail-on-unknown, --policy-allow-file) exist.
• Commercial packages need --allow-package, else exit 50. Backend uses nuget:SixLabors.* (covers both SixLabors.ImageSharp and .ImageSharp.Web).
• isLatest: DT allows one latest version per project name, and projects are Umbraco-CMS (children Umbraco-CMS-Backend etc.) versioned by major. Only a stable public release of main's major (read from main's version.json at upload time) is marked latest; older-major releases upload with false.
• Exit 10 = success-with-warnings (unresolved licenses; SBOM still written). Each step tolerates it: if ($LASTEXITCODE -ne 0 -and $LASTEXITCODE -ne 10) { exit $LASTEXITCODE }; exit 0.
• Every BOM job needs a UseDotNet@2 (useGlobalJson: true) step before the tool install (the .NET 10 tool needs the SDK, including in the otherwise Node-only frontend jobs).
• Backend must restore before scanning: umbraco-sbom needs every project in the solution restored, including the two the solution restore skips (Umbraco.Tests.AcceptanceTest.UmbracoProject, Umbraco.JsonSchema).

Persistence Layer - NPoco and EF Core Copy Section

The repository contains BOTH (actively supported):

• Current: NPoco-based persistence (Umbraco.Cms.Persistence.Sqlite, Umbraco.Cms.Persistence.SqlServer) - widely used and fully supported
• Future: EF Core-based persistence (Umbraco.Cms.Persistence.EFCore.*) - migration in progress

Note: The codebase is actively migrating to EF Core, but NPoco remains the primary persistence layer and is not deprecated. Both are fully supported.

Authentication: OpenIddict Copy Section

All APIs use OpenIddict (OAuth 2.0/OpenID Connect):

• Reference tokens (not JWT) for better security
• Secure cookie-based token storage (v17+) - tokens stored in HTTP-only cookies with __Host- prefix
• Tokens are redacted from client-side responses and passed via secure cookies only ([redacted] placeholder)
• ASP.NET Core Data Protection for token encryption
• Configured in Umbraco.Cms.Api.Common
• API requests must include credentials (credentials: include for fetch)

Load Balancing Requirement: All servers must share the same Data Protection key ring.

Frontend auth pitfalls — see src/Umbraco.Web.UI.Client/docs/edge-cases.md (Auth & Cross-tab section) and docs/security.md. Key points:

• Never call validateToken() per API request — it revokes the previous reference token (ID2019 errors)
• window.opener is set for ANY window.open() target, not only OAuth popups — scope guards to the pathname too
• BroadcastChannel does not deliver messages to the sender's own tab

Content Caching Strategy Copy Section

HybridCache (Umbraco.PublishedCache.HybridCache):

• In-memory cache + distributed cache support
• Published content only (not draft)
• Invalidated via notifications and cache refreshers

API Versioning Copy Section

APIs use Asp.Versioning.Mvc:

• Management API: /umbraco/management/api/v{version}/*
• Delivery API: /umbraco/delivery/api/v{version}/*
• OpenAPI docs: /umbraco/openapi/management.json, /umbraco/openapi/delivery.json
• Swagger UI: /umbraco/openapi/

Updating `OpenApi.json` (Management API) Copy Section

When a PR changes Management API controllers or models, the OpenApi.json file in the Management API project must be updated, along with the generated backoffice client that is derived from it.

With the Umbraco instance running locally (in a non-Production environment — Swagger isn't mapped in Production):

npm --prefix src/Umbraco.Web.UI.Client run generate:openapi
npm --prefix src/Umbraco.Web.UI.Client run generate:server-api

The first fetches the document from /umbraco/swagger/management/swagger.json byte-for-byte into src/Umbraco.Cms.Api.Management/OpenApi.json; the second regenerates the hey-api client from that committed file. Both results must be committed together.

They are two separate commands on purpose. The client generator only ever reads the committed schema — never a running site — so the schema and the client it produced always land in the same commit.

The /umb-update-openapi skill wraps this: it starts and stops a backend for you if one isn't already running, and explains the diff. Reach for it when you want the whole round trip handled.

Important: The fetch is byte-for-byte on purpose, so the endpoint stays the source of truth. Don't reformat the result — commit only the substantive changes, not IDE-applied formatting (whitespace, reordering, etc.). Extraneous formatting diffs make PRs harder to review and merge-ups more error-prone.

Backoffice npm Package Copy Section

The backoffice is published to npm as @umbraco-cms/backoffice. Runtime dependencies are provided via importmap; npm peerDependencies provide types only. For full details on dependency hoisting, version range logic, and plugin development, see /src/Umbraco.Web.UI.Client/CLAUDE.md → "npm Package Publishing".

SQL Server 2100-parameter limit Copy Section

Any WHERE IN (@0, @1, ...) built from a runtime-sized collection risks hitting SQL Server's 2100-parameter ceiling and throwing SqlException 8003 in production.

Batch with IEnumerable<T>.InGroupsOf(Constants.Sql.MaxParameterCount) or Database.FetchByGroups(...) whenever the collection size is driven by user data — not just when it currently fits. Watch for products of two scaling dimensions (documents × languages, properties × versions) and config-tunable batch sizes whose defaults are safe but ceilings aren't.

Full guidance, safe patterns and decision rule: see /src/Umbraco.Infrastructure/CLAUDE.md → "Avoiding the SQL Server 2100-parameter limit".

Known Limitations Copy Section

1. Circular Dependencies: Avoided via Lazy<T> or event notifications
2. Multi-Server: Requires shared Data Protection key ring and synchronized clocks (NTP)
3. Database Support: SQL Server, SQLite

8. CI/CD — Claude AI Assistant Copy Chapter

Two GitHub Actions workflows powered by anthropics/claude-code-action@v1. Advisory only — does not block merging.

Workflows Copy Section

Auto-Review (`claude-review.yml`) Copy Section

Runs the full .claude/skills/umb-review/SKILL.md procedure on every newly opened or un-drafted PR. Produces inline comments per finding and one summary comment with a verdict. Skips draft PRs. No turn limit.

Interactive (`claude.yml`) Copy Section

Responds to @claude mentions on PRs and issues. The trigger phrase is stripped before Claude sees the message, so:

• @claude review → light review using gh pr diff (not the umb-review skill)
• @claude fix ... → implements a fix on a new branch
• @claude help → answers questions about the codebase
• @claude label → applies labels
• @claude (empty) → defaults to review on PRs, help on issues

Also triggers on issue assignment to claude or adding the claude label. Gated: only runs when @claude appears in the comment/issue body. Max 50 turns.

Allowed tools:

• Auto-review: inline comments, gh auth status, gh pr view/diff/comment/edit, and git diff/log/show/fetch.
• Interactive: inline comments, git, npm and dotnet, file edits inside the checkout (--permission-mode acceptEdits), and the gh commands for PRs, issues and runs that the requests need (gh pr view/diff/checks/comment/edit/create, gh issue view/comment/edit, gh search issues/prs, gh run view/list). Node and .NET are set up from .nvmrc and global.json.

Labels Copy Section

Both workflows apply labels based on content:

On PRs (based on changed files):

On Issues (based on content): same area/* and category/* labels, plus affected/v14 through affected/v17 and affected/backoffice.

Labels are only added, never removed. Claude applies only labels it is confident about.

Key Implementation Notes Copy Section

• Checkout required — the action internally runs git fetch origin main for trusted file restoration. Without actions/checkout, it fails with fatal: not a git repository.
• id-token: write permission — required for OIDC token exchange with the Claude GitHub App.
• Workflow files must match main — the action skips, with a warning, when the workflow file it runs from differs from the version on the default branch. A PR that changes claude-review.yml can't review itself, and reviews on other branches skip until the change has been merged up to main.
• Mode decides the default tools — track_progress: true runs the auto-review in tag mode, where the action adds read tools, file edits inside the checkout and its own commit tools. With a prompt and no progress tracking, the interactive and issue-deduplication workflows run in agent mode, where only --allowedTools applies: read-only tools always work, but file edits need --permission-mode acceptEdits.
• Trigger phrase stripping — the action strips @claude from comments before passing to Claude. Prompts must reference commands without the prefix (e.g., review not @claude review).
• PR number injection — the interactive workflow injects the PR/issue number into the prompt via ${{ github.event.issue.number }} since Claude can't discover it from gh pr view when checked out on main.

9. Code Comment Policy Copy Chapter

Default to no comment. Applies to all code in this repository — C#, TypeScript, Razor, build scripts. Identifiers, small functions, and recognized idioms (a guard clause, a null check, an early return) carry their own meaning, even when some other layer has a reason to trigger them redundantly — that reason belongs to that layer, not to a comment here. Write one only for what this code genuinely can't say on its own: a non-obvious why, an invariant the types don't enforce, or an edge case it deliberately handles. Public members get XML doc / JSDoc, kept concise.

When a comment is justified, pitch it at the altitude of the code it sits in — the vocabulary of the layer it lives in, not the incident that prompted it. §2 shows what that looks like in practice.

Comments aren't a changelog. An issue link (#21996) earns its place inline only while it's explaining a live why — a guard, a workaround, a regression test. It does not belong there as provenance (// Fix for X, // Used by Y, // See PR #1234); which task or PR produced a change lives in the commit message and PR description, where it stays accurate.

TODOs Copy Section

The one exception to "default to no comment" — deleted once the TODO is done, so it can't rot. Keep them short and trackable, anchored to an author or a version trigger: // TODO (V19): remove once obsolete overload is gone, // TODO: pagination [NL].

10. Testing Practices Copy Chapter

A test for shared code asserts the general rule from §2, not the scenario that reported it, and is named for the rule.

Tests for a bug fix must fail before the fix Copy Section

Verify any test you add for a bug fix actually catches the bug: either write the failing test first (TDD), or temporarily revert the production change and confirm the test fails before re-applying. A test that passes both ways proves nothing. Watch for coincidental passes — default seed/sort orders can make a buggy path produce the right answer for the test's specific inputs; construct inputs so the broken and fixed behaviours give visibly different results.

For integration tests that exercise caching or cache refreshers, see tests/Umbraco.Tests.Integration/CLAUDE.md — the harness disables caching by default, which can produce false greens.

11. Verification Discipline Copy Chapter

• Fresh build before trusting a green. Never treat --no-build or cached/incremental output as proof a change compiles or passes — a stale run can mask a compile error. Rebuild before reporting build or test state. (Integration tests have a related false-green trap — see tests/Umbraco.Tests.Integration/CLAUDE.md.)
• Grep the branch you think you're on. A search only supports a claim against the branch actually checked out, so confirm HEAD is where you expect before drawing a conclusion from a grep. Easy to get wrong whenever the tree moves under you — reviewing a PR head, switching worktrees, or mid merge-up/rebase.
• Remove unused usings — touched files only. Before handing back C# changes, remove unused using directives (IDE0005) from the .cs files the change adds or modifies, and never sweep other files (unrelated churn causes merge-up conflicts). Run it per affected project, not the solution, which is slow to load: dotnet format style .csproj --diagnostics IDE0005 --severity info --include <files>, then rebuild (a using may only be needed under an #if symbol).

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build solution
dotnet build

# Run all tests
dotnet test

# Run specific test category
dotnet test --filter "Category=Integration"

# Format code
dotnet format

# Pack all projects
dotnet pack -c Release

Integration Test Database Configuration Copy Section

Integration tests are configured in tests/Umbraco.Tests.Integration/appsettings.Tests.json.

The Tests:Database:DatabaseType setting controls which database is used:

• "SQLite" (default) - No external dependencies
• "LocalDb" - Uses SQL Server LocalDB, required for SQL Server-specific tests (e.g., page-level locking, sys.dm_tran_locks)

SQL Server-specific tests use BaseTestDatabase.IsSqlite() to skip when running on SQLite.

Key Projects Copy Section

Important Files Copy Section

• Solution: umbraco.sln
• Build Config: Directory.Build.props, Directory.Packages.props
• Code Style: .editorconfig, .globalconfig
• Documentation: /CLAUDE.md, /src/Umbraco.Core/CLAUDE.md, /src/Umbraco.Cms.Api.Common/CLAUDE.md

Project-Specific Documentation Copy Section

For detailed information about individual projects, see their CLAUDE.md files:

• Core Architecture: /src/Umbraco.Core/CLAUDE.md - Service contracts, notification patterns
• API Infrastructure: /src/Umbraco.Cms.Api.Common/CLAUDE.md - OpenAPI, authentication, serialization
• Backoffice Frontend: /src/Umbraco.Web.UI.Client/CLAUDE.md - Lit web components, extension system, auth client

Important: When working on backoffice client code (anything under src/Umbraco.Web.UI.Client/), read /src/Umbraco.Web.UI.Client/CLAUDE.md first. It contains action-specific checklists (deprecation, testing, security, etc.) that are not duplicated here.

Getting Help Copy Section

• Official Docs: https://docs.umbraco.com/
• Contributing Guide: .github/CONTRIBUTING.md
• Issues: https://github.com/umbraco/Umbraco-CMS/issues
• Community: https://forum.umbraco.com/
• Releases: https://releases.umbraco.com/

This repository follows a layered architecture with strict dependency rules. The Core defines contracts, Infrastructure implements them, and Web/APIs consume them. Each layer can be understood independently, but dependencies always flow inward toward Core.

File: context7.json Copy Chapter

{
"url": "https://context7.com/umbraco/umbraco-cms",
"public_key": "pk_GTIgsrGAQiHNxCirZBDIM"
}

File: global.json Copy Chapter

{
"sdk": {
"version": "10.0.100",
"rollForward": "latestFeature",
"allowPrerelease": false
}
}

File: LICENSE.md Copy Chapter

The MIT License (MIT)

Copyright (c) 2005-present Umbraco

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

File: MCP.md Copy Chapter

MCP (Model Context Protocol) Setup

This repository includes configuration for Model Context Protocol (MCP) servers, enabling AI tooling integration for Umbraco CMS development workflows.

Overview Copy Chapter

MCP allows AI assistants (like Claude) to interact with external tools and services. This repository configures two MCP servers:

Quick Start Copy Chapter

1. Start Umbraco Locally Copy Section

Ensure your local Umbraco instance is running at https://localhost:44339 (or update the URL in your .env.local).

2. Configure Environment Variables Copy Section

Copy the example environment file and customize it:

cp .env.example .env.local

Edit .env.local with your local settings:

UMBRACO_CLIENT_ID=umbraco-back-office-mcp
UMBRACO_CLIENT_SECRET=<your-client-secret>
UMBRACO_BASE_URL=https://localhost:44339
NODE_TLS_REJECT_UNAUTHORIZED=0
UMBRACO_INCLUDE_TOOL_COLLECTIONS=data-type,document-type,document,media-type,media

3. Configure the OAuth Client in Umbraco Copy Section

Create an OAuth client in your Umbraco instance with:

• Client ID: umbraco-back-office-mcp
• Client Secret: The value you set in .env.local
• Grant Type: Client Credentials

Environment Variables Reference Copy Chapter

Tool Collections Copy Section

The UMBRACO_INCLUDE_TOOL_COLLECTIONS variable controls which Umbraco MCP tools are available:

• data-type - Manage data types (property editors)
• document-type - Manage document types (content types)
• document - Manage content/documents
• media-type - Manage media types
• media - Manage media items

Security Considerations Copy Chapter

Warning: This configuration is for local development only.

Self-Signed Certificates Copy Section

NODE_TLS_REJECT_UNAUTHORIZED=0 disables SSL certificate validation. This is necessary for self-signed certificates in local development but:

• Never use in production
• Affects all HTTPS connections made by Node.js processes
• Consider trusting your local development certificate instead

Client Secrets Copy Section

• Never commit real secrets to source control
• The .env.local file is gitignored for this reason
• Use strong, unique secrets even in development
• The example value 1234567890 in .env.example is a placeholder only

File Structure Copy Chapter

Umbraco-CMS/
├── .mcp.json              # MCP server configuration
├── .env.example           # Example environment variables (committed)
├── .env.local             # Your local environment variables (gitignored)
├── .claude/
│   ├── settings.json      # Shared Claude AI permissions (committed)
│   └── settings.local.json # Local Claude overrides (gitignored)
├── .gitignore             # Ignores .env.local and settings.local.json
└── MCP.md                 # This documentation (you are here)

Claude AI Permissions Copy Chapter

The .claude/settings.json file configures which MCP tools Claude can use automatically without prompting. This is shared across the team for consistent developer experience.

Customizing Permissions Locally Copy Section

Create .claude/settings.local.json to override permissions for your environment:

{
  "permissions": {
    "allow": [
      "mcp__umbraco__get-all-document-types"
    ]
  }
}

Troubleshooting Copy Chapter

"Connection refused" errors Copy Section

• Ensure Umbraco is running at the configured UMBRACO_BASE_URL
• Check that the port matches your local setup

"Unauthorized" errors Copy Section

• Verify the OAuth client is configured in Umbraco
• Check that UMBRACO_CLIENT_ID and UMBRACO_CLIENT_SECRET match
• Ensure the client has appropriate permissions

"Certificate" errors Copy Section

• For local development, set NODE_TLS_REJECT_UNAUTHORIZED=0 in .env.local
• Alternatively, trust your local development certificate

MCP server not starting Copy Section

• Ensure Node.js is installed (v22+ recommended, matching .nvmrc)
• Run npx @umbraco-cms/mcp-dev@17 --help to verify the package works

Further Reading Copy Chapter

• Model Context Protocol Documentation
• Umbraco MCP Package
• Playwright MCP
• Claude Code Documentation

File: NOTICES.txt Copy Chapter

Third-Party Notices

This file contains notices and attributions for third-party software used in the Umbraco CMS project.

Third-party software may contain dependencies that are not explicitly listed here.

This notice is not a license and does not grant any rights to use the third-party software.

Umbraco CMS is licensed under the MIT License, which can be found in the LICENSE file.

@openid/AppAuth-JS: An OpenID Connect and OAuth 2.0 client library for JavaScript

URL: https://github.com/openid/AppAuth-JS
License: Apache License, Version 2.0
Copyright: 2017 Google Inc.

AutoFixture: Write maintainable unit tests, faster

URL: https://github.com/AutoFixture/AutoFixture
License: MIT License
Copyright: 2013 Mark Seemann

Asp.Versioning.Mvc: A library for ASP.NET Core versioning

URL: https://github.com/dotnet/aspnet-api-versioning
License: MIT License
Copyright: .NET Foundation and contributors

Babel: A JavaScript compiler

URL: https://babeljs.io/
License: MIT License
Copyright: 2014-present Sebastian McKenzie and other contributors

BenchmarkDotNet: Powerful .NET library for benchmarking

URL: https://github.com/dotnet/BenchmarkDotNet
License: MIT License
Copyright: .NET Foundation and Contributors

Bogus: A simple and sane data generator for populating objects that supports different locales.

URL: https://github.com/bchavez/Bogus
License: MIT License
Copyright: 2015 Brian Chavez

CommandLineParser: Terse syntax C# command line parser for .NET

URL: https://github.com/commandlineparser/commandline
License: MIT License
Copyright: 2005-2015 Giacomo Stelluti Scala & Contributors

cross-env: A CLI tool to set environment variables across platforms

URL: https://github.com/kentcdodds/cross-env
License: MIT License
Copyright: 2017 Kent C. Dodds

Dazinator.Extensions.FileProviders: A library for file provider extensions

URL: https://github.com/dazinator/Dazinator.Extensions.FileProviders
License: MIT License
Copyright: 2016 Darrell

DOMPurify: A DOM-only XSS sanitizer for HTML, MathML and SVG

URL: https://github.com/cure53/DOMPurify
License: Apache License, Version 2.0
Copyright: 2025 Dr.-Ing. Mario Heiderich, Cure53

Element Internals Polyfill: A polyfill for the Element Internals API

URL: https://github.com/calebdwilliams/element-internals-polyfill
License: MIT License
Copyright: 2021 Caleb Williams

Eslint: A tool for identifying and reporting on patterns in JavaScript

URL: https://eslint.org/
License: MIT License
Copyright: OpenJS Foundation and other contributors

Examine: A search and indexing library for .NET

URL: https://github.com/Shazwazza/Examine
License: Microsoft Public License (Ms-PL)
Copyright: 2023 Shannon Deminick

Globals: A library for managing global variables in JavaScript

URL: https://github.com/sindresorhus/globals
License: MIT License
Copyright: Sindre Sorhus

Html Agility Pack: An HTML parser for .NET

URL: https://html-agility-pack.net/
License: MIT License
Copyright: ZZZ Projects Inc.

ImageSharp: A cross-platform library for processing images in .NET

URL: https://github.com/SixLabors/ImageSharp
License: Apache License, Version 2.0 under the Six Labors Split License
Copyright: Six Labors

jsdiff: A JavaScript text differencing implementation

URL: https://github.com/kpdecker/jsdiff
License: BSD 3-Clause License
Copyright: 2009-2015 Kevin Decker [email protected]

JsonPatch.Net: A library for JSON Patch (RFC 6902) in .NET

URL: https://github.com/json-everything/json-everything
License: MIT License
Copyright: .NET Foundation and Contributors

K4os.Compression.LZ4: A fast LZ4 compression library for .NET

URL: https://github.com/MiloszKrajewski/K4os.Compression.LZ4
License: MIT License
Copyright: 2017 Milosz Krajewski

Lit: A simple library for building fast, lightweight web components

URL: https://lit.dev
License: BSD 3-Clause License
Copyright: 2020 Google LLC. All rights reserved.

Lucide: Beautiful & consistent icons for the web

URL: https://lucide.dev/
License: ISC License
Copyright: 2013-2022 Cole Bemis
Copyright: 2022 Lucide Contributors

Madge: A dependency graph generator for JavaScript

URL: https://github.com/pahen/madge
License: MIT License
Copyright: 2017 Patrik Henningsson

MailKit: A library for sending email in .NET

URL: https://github.com/jstedfast/MailKit
License: MIT License
Copyright: 2013-2024 .NET Foundation and Contributors

Markdig: A fast, powerful, CommonMark compliant, extensible Markdown processor for .NET

URL: https://github.com/xoofx/markdig
License: BSD-2-Clause license
Copyright: 2018+, Alexandre Mutel. All rights reserved.

Markdown: A library for parsing and compiling Markdown

URL: https://github.com/hey-red/Markdown
License: MIT License
Copyright: 2018 red

marked: A markdown parser and compiler

URL: https://marked.js.org/
License: MIT License
Copyright: 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
Copyright: 2018+, MarkedJS (https://github.com/markedjs/)

Message Pack: The extremely fast MessagePack serializer for C#

URL: https://github.com/MessagePack-CSharp/MessagePack-CSharp
License: MIT License
Copyright: 2017 Yoshifumi Kawai and contributors

Miniprofiler: A mini profiler for .NET

URL: https://github.com/MiniProfiler/dotnet
License: MIT License
Copyright: .NET MiniProfiler Contributors

Monaco Editor: A browser-based code editor

URL: https://microsoft.github.io/monaco-editor/
License: MIT License
Copyright: 2016-present Microsoft Corporation

Moq: A mocking library for .NET

URL: https://github.com/moq/moq
License: BSD 3-Clause License
Copyright: 2007 Clarius Consulting, Manas Technology Solutions, InSTEDD, and Contributors.

Mock Service Worker (MSW): A library for mocking API requests in JavaScript

URL: https://mswjs.io/
License: MIT License
Copyright: 2018–present Artem Zakharchenko

NCrontab: A cron schedule parser for .NET

URL: https://github.com/atifaziz/NCrontab
License: Apache License, Version 2.0
Copyright: 2001 The OpenSymphony Group
Copyright: 2008 Atif Aziz

Nerdbank.GitVersioning: A library for versioning .NET projects

URL: https://github.com/dotnet/Nerdbank.GitVersioning
License: MIT License
Copyright: .NET Foundation and Contributors

NJsonSchema: A JSON schema validator for .NET

URL: https://github.com/RicoSuter/NJsonSchema
License: MIT License
Copyright: 2022 Rico Suter

NPoco: A micro ORM for .NET

URL: https://github.com/schotime/NPoco
License: Apache License, Version 2.0
Copyright: Schotime

NUnit: A unit testing framework for .NET

URL: https://github.com/nunit/nunit
License: MIT License
Copyright: Charlie Poole, Rob Prouse and Contributors

Open Web Components: A set of standards and libraries for building web components

URL: https://open-wc.org/
License: MIT License
Copyright: 2018 open-wc

Openapi-ts: The OpenAPI to TypeScript codegen

URL: https://github.com/hey-api/openapi-ts
License: MIT License
Copyright: Hey API

OpenIddict: A simple and flexible OpenID Connect server for ASP.NET Core

URL: https://github.com/openiddict/openiddict-core
License: Apache License, Version 2.0
Copyright: Kévin Chalet

Playwright: A Node.js library to automate browser testing

URL: https://playwright.dev/
License: Apache License, Version 2.0
Copyright: 2025 Microsoft Corporation

Playwright-msw: A library to wrap Mock Service Worker with Playwright

URL: https://github.com/valendres/playwright-msw
License: MIT License
Copyright: 2022 Peter Weller

Prettier: An opinionated code formatter

URL: https://prettier.io/
License: MIT License
Copyright: James Long and contributors

Remark-gfm: A GitHub Flavored Markdown plugin for Remark

URL: https://github.com/remarkjs/remark-gfm
License: MIT License
Copyright: Titus Wormer

rxjs: Reactive Extensions for JavaScript

URL: https://rxjs.dev/
License: Apache License, Version 2.0
Copyright: 2015-present Ben Lesh , Google, Inc., Netflix, Inc., Microsoft Corp., and contributors

Serilog: A diagnostic logging library for .NET

URL: https://github.com/serilog/serilog
License: Apache License, Version 2.0
Copyright: Serilog Contributors

Simple Icons: A set of SVG icons for popular brands

URL: https://simpleicons.org/
License: CC0 1.0 Universal License
Copyright: Simple Icons Contributors

Storybook: A UI component explorer for Web Components

URL: https://storybook.js.org/
License: MIT License
Copyright: 2024 Storybook

StyleCop.Analyzers: Analyzers for StyleCop

URL: https://github.com/DotNetAnalyzers/StyleCopAnalyzers
License: MIT License
Copyright: Tunnel Vision Laboratories, LLC

SVGO: A tool for optimizing SVG files

URL: https://svgo.dev/
License: MIT License
Copyright: Kir Belevich

Swashbuckle.AspNetCore: A library for generating Swagger documentation for ASP.NET Core APIs

URL: https://github.com/domaindrivendev/Swashbuckle.AspNetCore
License: MIT License
Copyright: 2016 Richard Morris

Tiny Glob: A tiny globbing library for Node.js

URL: https://github.com/terkelg/tiny-glob
License: MIT License
Copyright: 2018 Terkel

Tiptap: A renderless rich-text editor for the web

URL: https://tiptap.dev/
License: MIT License
Copyright: 2025 Tiptap GmbH

Tsc-alias: A TypeScript compiler plugin for aliasing module paths

URL: https://github.com/justkey007/tsc-alias
License: MIT License
Copyright: 2018 Justkey

Typedoc: A documentation generator for TypeScript projects

URL: https://typedoc.org/
License: Apache License, Version 2.0
Copyright: Gerrit Birkeland and Contributors

Typescript: A typed superset of JavaScript that compiles to plain JavaScript

URL: https://www.typescriptlang.org/
License: Apache License, Version 2.0
Copyright: 2012-present Microsoft Corporation

Typescript-eslint: A set of tools for linting TypeScript code

URL: https://github.com/typescript-eslint/typescript-eslint
License: MIT License
Copyright: 2019 typescript-eslint and other contributors

Typescript-json-schema: A library for generating JSON schema from TypeScript types

URL: https://github.com/YousefED/typescript-json-schema
License: BSD 3-Clause License
Copyright: 2016 typescript-json-schema contributors

Umbraco.Code: Provides code-level tools for Umbraco

URL: https://github.com/umbraco/Umbraco-Code
License: MIT License
Copyright: 2005-present Umbraco A/S

Umbraco.GitVersioning.Extensions: Utilities for Nerdbank.GitVersioning

URL: https://github.com/umbraco/Umbraco.GitVersioning.Extensions
License: MIT License
Copyright: 2005-present Umbraco A/S

Umbraco.JsonSchema.Extensions: Utilities for JSON schema generation

URL: https://github.com/umbraco/Umbraco.JsonSchema.Extensions
License: MIT License
Copyright: 2005-present Umbraco A/S

Umbraco UI Library: A set of UI components for building web applications

URL: https://uui.umbraco.com/
License: MIT License
Copyright: 2005-present Umbraco A/S

uuid: A library for generating unique identifiers

URL: https://github.com/uuidjs/uuid
License: MIT License
Copyright: 2010-2020 Robert Kieffer and other contributors

Vite: A fast build tool and development server for modern web projects

URL: https://vite.dev/
License: MIT License
Copyright: 2019-present VoidZero Inc. and Vite contributors

Vite-plugin-static-copy: A Vite plugin for copying static files

URL: https://github.com/sapphi-red/vite-plugin-static-copy
License: MIT License
Copyright: 2021 sapphi-red

Vite-tsconfig-paths: A Vite plugin for resolving TypeScript paths

URL: https://github.com/aleclarson/vite-tsconfig-paths
License: MIT License
Copyright: Alec Larson

Web Component Analyzer: A tool for analyzing web components

URL: https://github.com/runem/web-component-analyzer
License: MIT License
Copyright: 2019 Rune Mehlsen

File: .mcp.json Copy Chapter

{
"mcpServers": {
"umbraco-cms": {
"command": "npx",
"args": ["@umbraco-cms/mcp-dev@18", "--env", ".env.local"]
},
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}

File: src/Umbraco.Cms.Api.Common/CLAUDE.md Copy Chapter

Umbraco.Cms.Api.Common

Shared infrastructure for Umbraco CMS REST APIs (Management and Delivery).

1. Architecture Copy Chapter

Type: Class Library (NuGet Package)
Target Framework: .NET 10.0
Purpose: Common API infrastructure - OpenAPI/Swagger, JSON serialization, OpenIddict authentication, problem details

Key Technologies Copy Section

• ASP.NET Core - Web framework
• Microsoft.AspNetCore.OpenApi - OpenAPI document generation
• Swashbuckle.AspNetCore.SwaggerUI - Swagger UI for browsing API documentation
• OpenIddict - OAuth 2.0/OpenID Connect authentication
• Asp.Versioning - API versioning
• System.Text.Json - Polymorphic JSON serialization

Dependencies Copy Section

• Umbraco.Core - Domain models and service contracts
• Umbraco.Web.Common - Web functionality

Project Structure (46 files) Copy Section

Umbraco.Cms.Api.Common/
├── OpenApi/                    # OpenAPI transformers and schema generators
│   ├── UmbracoSchemaIdGenerator.cs         # Generates schema IDs (e.g., "PagedUserModel")
│   ├── UmbracoOperationIdTransformer.cs    # Generates operation IDs
│   ├── SortTagsAndPathsTransformer.cs      # Sorts OpenAPI tags and paths
│   ├── TagActionsByGroupNameTransformer.cs # Tags operations by controller group
│   ├── FixFileReturnTypesTransformer.cs    # Fixes file return type schemas
│   ├── RequireNonNullablePropertiesSchemaTransformer.cs # Schema nullability
│   └── OpenApiRouteTemplatePipelineFilter.cs # Adds OpenAPI endpoints
├── Serialization/              # JSON type resolution
│   └── UmbracoJsonTypeInfoResolver.cs
├── Configuration/              # Options configuration
│   ├── ConfigureUmbracoOpenApiOptionsBase.cs
│   └── ConfigureOpenIddict.cs
├── DependencyInjection/        # Service registration
│   ├── UmbracoBuilderApiExtensions.cs
│   └── UmbracoBuilderAuthExtensions.cs
├── Builders/                   # RFC 7807 problem details
│   └── ProblemDetailsBuilder.cs
├── ViewModels/Pagination/      # Common DTOs
└── Security/                   # Auth paths and handlers

Design Patterns Copy Section

1. Builder Pattern - ProblemDetailsBuilder for fluent error responses
2. Options Pattern - All configuration via IConfigureOptions<T>

2. Commands Copy Chapter

See "Quick Reference" section at bottom for common commands.

3. Key Patterns Copy Chapter

Schema ID Generation (OpenApi/UmbracoSchemaIdGenerator.cs) Copy Section

Static utility class that generates OpenAPI schema IDs following Umbraco's naming conventions:

// Add "Model" suffix to avoid TypeScript name clashes
if (name.EndsWith("Model") == false)
{
    // because some models names clash with common classes in TypeScript (i.e. Document),
    // we need to add a "Model" postfix to all models
    name = $"{name}Model";
}

// Remove invalid characters to prevent OpenAPI generation errors
return Regex.Replace(name, @"[^\w]", string.Empty);

Generic Type Handling: PagedViewModel<RelationItemViewModel> becomes PagedRelationItemModel

Polymorphic Deserialization (Serialization/UmbracoJsonTypeInfoResolver.cs:29-35) Copy Section

// IMPORTANT: do NOT return an empty enumerable here. it will cause nullability to fail on reference
// properties, because "$ref" does not mix and match well with "nullable" in OpenAPI.
if (type.IsInterface is false)
{
    return new[] { type };
}

Why: Interfaces must return concrete types to avoid OpenAPI schema conflicts.

4. Testing Copy Chapter

Location: No direct tests - tested via integration tests in consuming APIs

How to test changes:

# Run integration tests that exercise this library
dotnet test tests/Umbraco.Tests.Integration/

# Verify OpenAPI generation
# 1. Run the application: dotnet run --project src/Umbraco.Web.UI
# 2. Navigate to /umbraco/openapi/ for Swagger UI
# 3. Check schema IDs and operation IDs
# OpenAPI JSON documents available at:
#   - /umbraco/openapi/management.json (Management API)
#   - /umbraco/openapi/delivery.json (Delivery API)

Focus areas when testing:

• OpenAPI document generation (schema IDs, operation IDs)
• Polymorphic JSON serialization/deserialization
• OpenIddict authentication flow
• Problem details formatting

5. OpenIddict Authentication Copy Chapter

Key Configuration (DependencyInjection/UmbracoBuilderAuthExtensions.cs) Copy Section

Reference Tokens over JWT (line 76-80):

// Enable reference tokens
// - see https://documentation.openiddict.com/configuration/token-storage.html
options
    .UseReferenceAccessTokens()
    .UseReferenceRefreshTokens();

Why: More secure (revocable), better for load balancing, uses ASP.NET Core Data Protection.

Token Lifetime (line 88-91):

// Make the access token lifetime 25% of the refresh token lifetime
options.SetAccessTokenLifetime(new TimeSpan(timeOut.Ticks / 4));
options.SetRefreshTokenLifetime(timeOut);

PKCE Required (line 59-63):

// Enable authorization code flow with PKCE
options
    .AllowAuthorizationCodeFlow()
    .RequireProofKeyForCodeExchange()
    .AllowRefreshTokenFlow();

Endpoints: Backoffice /umbraco/management/api/v1/security/*, Member /umbraco/member/api/v1/security/*

Secure Cookie-Based Token Storage (v17+) Copy Section

Implementation (DependencyInjection/HideBackOfficeTokensHandler.cs):

Back-office tokens are hidden from client-side JavaScript via HTTP-only cookies:

private const string AccessTokenCookieKey = "__Host-umbAccessToken";
private const string RefreshTokenCookieKey = "__Host-umbRefreshToken";

// Tokens are encrypted via Data Protection and stored in cookies
SetCookie(httpContext, AccessTokenCookieKey, context.Response.AccessToken);
context.Response.AccessToken = "[redacted]";  // Client sees redacted value

Key Security Features (lines 143-165): HttpOnly, IsEssential, Path="/", Secure (HTTPS), __Host- prefix

Configuration: BackOfficeTokenCookieSettings.Enabled (default: true in v17+)

Implications: Client-side cannot access tokens; encrypted with Data Protection; load balancing needs shared key ring; API requests need credentials: include

6. Common Issues & Edge Cases Copy Chapter

Polymorphic Deserialization Requires `$type` Copy Section

Issue: Deserializing to an interface without $type discriminator fails.

Handled in (Json/NamedSystemTextJsonInputFormatter.cs:24-29):

catch (NotSupportedException exception)
{
    // This happens when trying to deserialize to an interface, without sending the $type as part of the request
    context.ModelState.TryAddModelException(string.Empty, new InputFormatterException(exception.Message, exception));
    return await InputFormatterResult.FailureAsync();
}

Solution: Clients must include $type property for interface types, or use concrete types.

Schema ID Collisions with TypeScript Copy Section

Issue: Type names like Document clash with TypeScript built-ins.

Solution: UmbracoSchemaIdGenerator adds "Model" suffix to all schema names.

Generic Type Handling Copy Section

Issue: PagedViewModel<T> needs flattened schema name.

Solution: UmbracoSchemaIdGenerator.Generate() flattens generic types:

• PagedViewModel<RelationItemViewModel> becomes PagedRelationItemModel

7. Extending This Library Copy Chapter

Adding Custom OpenAPI Transformers Copy Section

OpenAPI transformers are scoped per-document. To customize a document, implement IOpenApiDocumentTransformer, IOpenApiOperationTransformer, or IOpenApiSchemaTransformer and register with your OpenAPI options.

For schema ID generation, use the static UmbracoSchemaIdGenerator.Generate(Type) method.

Customizing Problem Details Copy Section

var problemDetails = new ProblemDetailsBuilder()
    .WithTitle("Validation Failed")
    .WithDetail("The request contains errors")
    .WithType("ValidationError")
    .WithOperationStatus(MyOperationStatus.ValidationFailed)
    .WithRequestModelErrors(errors)
    .Build();

return BadRequest(problemDetails);

8. Project-Specific Notes Copy Chapter

Per-Document Transformer Scoping Copy Section

With Microsoft.AspNetCore.OpenApi, transformers are configured per OpenAPI document. This means custom transformers only apply to the documents they're registered with, not globally. Each API (Management, Delivery) configures its own transformers via ConfigureUmbracoOpenApiOptionsBase subclasses.

Performance: Subtype Caching Copy Section

Why: Cache discovered subtypes (UmbracoJsonTypeInfoResolver.cs:14) to avoid expensive reflection calls

Known Limitations Copy Section

1. Polymorphic Deserialization:

   • Requires $type discriminator in JSON for interfaces
   • Only discovers types in Umbraco namespaces
   • Not all .NET types are discoverable

2. OpenAPI Schema Generation:

   • Generic types are flattened (e.g., PagedViewModel<T> → PagedTModel)
   • Type names may need "Model" suffix to avoid clashes

3. OpenIddict Multi-Server:

   • Requires shared Data Protection key ring
   • All servers must have synchronized clocks (NTP)
   • Reference tokens require database storage

External Dependencies Copy Section

OpenIddict:

• OAuth 2.0 / OpenID Connect provider
• Version: See Directory.Packages.props
• Uses ASP.NET Core Data Protection for token encryption

Microsoft.AspNetCore.OpenApi:

• OpenAPI 3.1.1 document generation
• Custom transformers: SchemaIdTransformer, OperationIdTransformer, MimeTypeDocumentTransformer, ServerTransformer

Swashbuckle.AspNetCore.SwaggerUI:

• Swagger UI for browsing and testing API endpoints
• Accessed at /umbraco/openapi/

Asp.Versioning:

• API versioning via ApiVersion attribute
• API explorer integration for multi-version Swagger docs

Configuration Copy Section

HTTPS: DisableTransportSecurityRequirement for local dev only (ConfigureOpenIddict.cs:14). Warning: Never disable in production.

Usage Pattern Copy Section

Consuming APIs call builder.AddUmbracoOpenApi().AddUmbracoOpenIddict()

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build project
dotnet build src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj

# Pack for NuGet
dotnet pack src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj -c Release

# Test via integration tests
dotnet test tests/Umbraco.Tests.Integration/

# Check packages
dotnet list src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj package --outdated
dotnet list src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj package --vulnerable

Key Classes Copy Section

Important Files Copy Section

• Umbraco.Cms.Api.Common.csproj - Project dependencies
• DependencyInjection/UmbracoBuilderApiExtensions.cs - OpenAPI registration (line 12-31)
• DependencyInjection/UmbracoBuilderAuthExtensions.cs - OpenIddict setup (line 20-183)
• Security/Paths.cs - API endpoint path constants

Getting Help Copy Section

• Root documentation: /CLAUDE.md - Repository overview
• Core patterns: /src/Umbraco.Core/CLAUDE.md - Core contracts and patterns
• Official docs: https://docs.umbraco.com/
• OpenIddict docs: https://documentation.openiddict.com/

This library is the foundation for all Umbraco CMS REST APIs. Focus on OpenAPI customization, authentication configuration, and polymorphic serialization when working here.

File: src/Umbraco.Cms.Api.Delivery/CLAUDE.md Copy Chapter

Umbraco.Cms.Api.Delivery

Headless content delivery REST API for Umbraco CMS. Enables frontend applications to fetch published content, media, and member-protected resources.

1. Architecture Copy Chapter

Type: Class Library (NuGet Package)
Target Framework: .NET 10.0
Purpose: Content Delivery API for headless CMS scenarios

Key Technologies Copy Section

• ASP.NET Core - Web framework
• OpenIddict - Member authentication (OAuth 2.0)
• Asp.Versioning - API versioning (V1, V2)
• Output Caching - Configurable response caching
• Examine/Lucene - Content querying

Dependencies Copy Section

• Umbraco.Cms.Api.Common - Shared API infrastructure (OpenAPI, auth)
• Umbraco.Web.Common - Web functionality

Project Structure (86 files) Copy Section

Umbraco.Cms.Api.Delivery/
├── Controllers/
│   ├── Content/               # Content endpoints (by ID, route, query)
│   ├── Media/                 # Media endpoints (by ID, path, query)
│   └── Security/              # Member auth (authorize, token, signout)
├── Querying/
│   ├── Filters/               # ContentType, Name, CreateDate, UpdateDate
│   ├── Selectors/             # Ancestors, Children, Descendants
│   └── Sorts/                 # Name, CreateDate, UpdateDate, Level, SortOrder
├── Indexing/                  # Lucene index field handlers
├── Services/                  # Business logic and query building
├── Caching/                   # Output cache policies
├── Rendering/                 # Output expansion strategies
├── Configuration/             # OpenAPI configuration
└── Filters/                   # Action filters (access, validation)

Design Patterns Copy Section

1. Strategy Pattern - Query handlers (ISelectorHandler, IFilterHandler, ISortHandler)
2. Factory Pattern - ApiContentQueryFactory builds Examine queries
3. Template Method - ContentApiControllerBase for shared controller logic
4. Options Pattern - DeliveryApiSettings for all configuration

2. Commands Copy Chapter

See "Quick Reference" section at bottom for common commands.

3. Key Patterns Copy Chapter

API Versioning (V1 vs V2) Copy Section

V1 (legacy) and V2 (current) coexist. Key difference is output expansion:

// DependencyInjection/UmbracoBuilderExtensions.cs:49-52
// V1 uses RequestContextOutputExpansionStrategy
// V2+ uses RequestContextOutputExpansionStrategyV2
return apiVersion.MajorVersion == 1
    ? provider.GetRequiredService<RequestContextOutputExpansionStrategy>()
    : provider.GetRequiredService<RequestContextOutputExpansionStrategyV2>();

Why V2: Improved expand and fields query parameter parsing (tree-based).

Query System Architecture Copy Section

Content querying flows through handlers registered in DI:

1. Selectors (fetch parameter): ancestors:id, children:id, descendants:id
2. Filters (filter[] parameter): contentType:alias, name:value, createDate>2024-01-01
3. Sorts (sort[] parameter): name:asc, createDate:desc, level:asc

// Services/ApiContentQueryService.cs:91-96
ISelectorHandler? selectorHandler = _selectorHandlers.FirstOrDefault(h => h.CanHandle(fetch));
return selectorHandler?.BuildSelectorOption(fetch);

Path Decoding Workaround Copy Section

ASP.NET Core doesn't decode forward slashes in route parameters:

// Controllers/DeliveryApiControllerBase.cs:21-31
// OpenAPI clients URL-encode paths, but ASP.NET Core doesn't decode "/"
// See https://github.com/dotnet/aspnetcore/issues/11544
if (path.Contains("%2F", StringComparison.OrdinalIgnoreCase))
{
    path = WebUtility.UrlDecode(path);
}

4. Testing Copy Chapter

Location: No direct tests - tested via integration tests in test projects

dotnet test tests/Umbraco.Tests.Integration/ --filter "FullyQualifiedName~Delivery"

Internals exposed to (csproj lines 28-36):

• Umbraco.Tests.UnitTests
• Umbraco.Tests.Integration
• DynamicProxyGenAssembly2 (for mocking)

Focus areas:

• Query parsing (selectors, filters, sorts)
• Member authentication flows
• Output caching behavior
• Protected content access

5. Security & Access Control Copy Chapter

Three Access Modes Copy Section

// Services/ApiAccessService.cs:21-27
public bool HasPublicAccess() => _deliveryApiSettings.PublicAccess || HasValidApiKey();
public bool HasPreviewAccess() => HasValidApiKey();
public bool HasMediaAccess() => _deliveryApiSettings is { PublicAccess: true, Media.PublicAccess: true } || HasValidApiKey();

Access levels:

1. Public - No authentication required (if enabled)
2. API Key - Via Api-Key header
3. Preview - Always requires API key

Member Authentication Copy Section

OpenIddict-based OAuth 2.0 for member-protected content:

Flows supported (Controllers/Security/MemberController.cs):

• Authorization Code + PKCE (line 53)
• Client Credentials (line 112)
• Refresh Token (line 98)

Endpoints:

• GET /umbraco/delivery/api/v1/security/member/authorize
• POST /umbraco/delivery/api/v1/security/member/token
• GET /umbraco/delivery/api/v1/security/member/signout

Scopes: Only openid and offline_access allowed for members (line 220-222)

Protected Content Copy Section

Member access checked via ProtectedAccess model:

// Controllers/Content/QueryContentApiController.cs:56-57
ProtectedAccess protectedAccess = await _requestMemberAccessService.MemberAccessAsync();
Attempt<PagedModel<Guid>, ApiContentQueryOperationStatus> queryAttempt =
    _apiContentQueryService.ExecuteQuery(fetch, filter, sort, protectedAccess, skip, take);

6. Output Caching Copy Chapter

Cache Policy Configuration Copy Section

// DependencyInjection/UmbracoBuilderExtensions.cs:120-136
// Content and Media have separate cache durations
options.AddPolicy(
    Constants.DeliveryApi.OutputCache.ContentCachePolicy,
    new DeliveryApiOutputCachePolicy(
        outputCacheSettings.ContentDuration,
        new StringValues([AcceptLanguage, AcceptSegment, StartItem])));

Cache invalidation conditions (Caching/DeliveryApiOutputCachePolicy.cs:31):

// Never cache preview or non-public access
context.EnableOutputCaching = requestPreviewService.IsPreview() is false
    && apiAccessService.HasPublicAccess();

Vary by headers: Accept-Language, Accept-Segment, Start-Item

7. Edge Cases & Known Issues Copy Chapter

Technical Debt (TODOs in codebase) Copy Section

1. V1 Removal Pending (2 locations):

   • DependencyInjection/UmbracoBuilderExtensions.cs:98 - FIXME: remove matcher policy
   • Routing/DeliveryApiItemsEndpointsMatcherPolicy.cs:11 - FIXME: remove class

2. Obsolete Reference Warnings (csproj:9-13):

   • ASP0019 - IHeaderDictionary.Append usage
   • CS0618/CS0612 - Obsolete member references

Empty Query Results Copy Section

Query service returns empty results (not errors) for invalid options:

// Services/ApiContentQueryService.cs:54-78
// Invalid selector/filter/sort returns fail status with empty result
return Attempt.FailWithStatus(ApiContentQueryOperationStatus.SelectorOptionNotFound, emptyResult);

Start Item Fallback Copy Section

When no fetch parameter provided, uses start item or all content:

// Services/ApiContentQueryService.cs:99-112
if (_requestStartItemProviderAccessor.TryGetValue(out IRequestStartItemProvider? requestStartItemProvider))
{
    IPublishedContent? startItem = requestStartItemProvider.GetStartItem();
    // Use descendants of start item
}
return _apiContentQueryProvider.AllContentSelectorOption(); // Fallback to all

8. Project-Specific Notes Copy Chapter

V1 vs V2 Differences Copy Section

Migration note: V1 is deprecated; plan removal when V17+ drops V1 support.

JSON Configuration Copy Section

Delivery API has its own JSON options (distinct from Management API):

// DependencyInjection/UmbracoBuilderExtensions.cs:82-88
.AddJsonOptions(Constants.JsonOptionsNames.DeliveryApi, options =>
{
    options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    options.JsonSerializerOptions.TypeInfoResolver = new DeliveryApiJsonTypeResolver();
    options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
});

Member Token Revocation Copy Section

Tokens automatically revoked on member changes:

// DependencyInjection/UmbracoBuilderExtensions.cs:93-96
builder.AddNotificationAsyncHandler<MemberSavedNotification, RevokeMemberAuthenticationTokensNotificationHandler>();
builder.AddNotificationAsyncHandler<MemberDeletedNotification, RevokeMemberAuthenticationTokensNotificationHandler>();
builder.AddNotificationAsyncHandler<AssignedMemberRolesNotification, RevokeMemberAuthenticationTokensNotificationHandler>();
builder.AddNotificationAsyncHandler<RemovedMemberRolesNotification, RevokeMemberAuthenticationTokensNotificationHandler>();

External Dependencies Copy Section

Examine/Lucene (via Core):

• Powers content querying
• Selector/Filter/Sort handlers build Lucene queries

OpenIddict (via Api.Common):

• Member OAuth 2.0 authentication
• Reference tokens (not JWT)

Configuration (appsettings.json) Copy Section

{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": true,
        "ApiKey": "your-api-key",
        "Media": {
          "Enabled": true,
          "PublicAccess": true
        },
        "MemberAuthorization": {
          "AuthorizationCodeFlow": { "Enabled": true },
          "ClientCredentialsFlow": { "Enabled": false }
        },
        "OutputCache": {
          "Enabled": true,
          "ContentDuration": "00:01:00",
          "MediaDuration": "00:01:00"
        }
      }
    }
  }
}

API Endpoints Summary Copy Section

Content (/umbraco/delivery/api/v2/content):

• GET /item/{id} - Single content by GUID
• GET /item/{path} - Single content by route
• GET /items - Multiple by IDs
• GET / - Query with fetch/filter/sort

Media (/umbraco/delivery/api/v2/media):

• GET /item/{id} - Single media by GUID
• GET /item/{path} - Single media by path
• GET /items - Multiple by IDs
• GET / - Query media

Security (/umbraco/delivery/api/v1/security/member):

• GET /authorize - Start OAuth flow
• POST /token - Exchange code for token
• GET /signout - Revoke session

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build project
dotnet build src/Umbraco.Cms.Api.Delivery/Umbraco.Cms.Api.Delivery.csproj

# Pack for NuGet
dotnet pack src/Umbraco.Cms.Api.Delivery/Umbraco.Cms.Api.Delivery.csproj -c Release

# Run integration tests
dotnet test tests/Umbraco.Tests.Integration/ --filter "FullyQualifiedName~Delivery"

# Check packages
dotnet list src/Umbraco.Cms.Api.Delivery/Umbraco.Cms.Api.Delivery.csproj package --outdated

Key Classes Copy Section

Important Files Copy Section

• Umbraco.Cms.Api.Delivery.csproj - Project dependencies
• DependencyInjection/UmbracoBuilderExtensions.cs - DI registration (lines 33-141)
• Configuration/DeliveryApiConfiguration.cs - API constants
• Services/ApiContentQueryService.cs - Query execution

Getting Help Copy Section

• Root documentation: /CLAUDE.md - Repository overview
• API Common patterns: /src/Umbraco.Cms.Api.Common/CLAUDE.md
• Official docs: https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api
• Media docs: https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api

This library exposes Umbraco content and media via REST for headless scenarios. Focus on query handlers, access control, and member authentication when working here.

File: src/Umbraco.Cms.Api.Management/CLAUDE.md Copy Chapter

Umbraco CMS - Management API

RESTful API for Umbraco backoffice operations. Manages content, media, users, and system configuration through OpenAPI-documented endpoints.

Project: Umbraco.Cms.Api.Management
Type: ASP.NET Core Web API Library
Files: 1,317 C# files across 54+ controller domains

1. Architecture Copy Chapter

Target Framework Copy Section

• .NET 10.0 (net10.0)
• C# 12 with nullable reference types enabled
• ASP.NET Core Web API

Application Type Copy Section

REST API Library - Plugged into Umbraco.Web.UI, provides the Management API surface for backoffice operations.

Key Technologies Copy Section

• Web Framework: ASP.NET Core MVC with Asp.Versioning.Mvc (v1.0 and v1.1)
• OpenAPI: Microsoft.AspNetCore.OpenApi with custom transformers, Swagger UI via Swashbuckle
• Authentication: OpenIddict via Umbraco.Cms.Api.Common (reference tokens, not JWT)
• Authorization: Policy-based with IAuthorizationService
• Validation: FluentValidation via base controllers
• Serialization: System.Text.Json with custom converters
• Mapping: Manual presentation factories (no AutoMapper)
• Patching: Custom patch engine for PATCH operations (Umbraco.Cms.Api.Management.Patching)
  • ⚠️ Legacy JsonPatch.Net support (IJsonPatchService) still available but obsolete - scheduled for removal in v19
• Real-time: SignalR hubs (BackofficeHub, ServerEventHub)
• DI: Microsoft.Extensions.DependencyInjection via ManagementApiComposer

Project Structure Copy Section

src/Umbraco.Cms.Api.Management/
├── Controllers/                   # 54+ domain-specific controller folders
│   ├── Document/                  # Document (content) CRUD + publish/unpublish
│   ├── Media/                     # Media CRUD + upload
│   ├── Member/                    # Member management
│   ├── User/                      # User management
│   ├── DataType/                  # Data type configuration
│   ├── DocumentType/              # Content type schemas
│   ├── Template/                  # Razor template management
│   ├── Dictionary/                # Localization dictionary
│   ├── Language/                  # Language/culture config
│   ├── Security/                  # Auth, login, external logins
│   ├── Install/                   # Installation wizard
│   ├── Upgrade/                   # Upgrade operations
│   ├── LogViewer/                 # Log browsing
│   ├── HealthCheck/               # Health check dashboard
│   ├── Webhook/                   # Webhook management
│   └── [48 more domains...]
│
├── ViewModels/                    # Request/response DTOs (one folder per domain)
├── Factories/                     # Domain model → ViewModel converters
├── Services/                      # Business logic (thin layer over Core.Services)
├── Mapping/                       # ViewModel → domain model mappers
├── Security/                      # Auth providers, sign-in manager, external logins
├── OpenApi/                       # OpenAPI transformers (schema, operation, security)
├── Routing/                       # Route configuration, SignalR hubs
├── DependencyInjection/           # Service registration (55+ files)
├── Middleware/                    # Preview, server events
├── Configuration/                 # IOptions configurators
├── Filters/                       # Action filters
├── Serialization/                 # JSON converters
└── OpenApi.json                   # Embedded OpenAPI spec (1.3MB)

Dependencies Copy Section

• Umbraco.Cms.Api.Common - Shared API infrastructure (base controllers, OpenAPI config)
• Umbraco.Infrastructure - Service implementations, data access
• Umbraco.PublishedCache.HybridCache - Published content queries
• Microsoft.AspNetCore.OpenApi - OpenAPI document generation
• Swashbuckle.AspNetCore.SwaggerUI - Swagger UI

Design Patterns Copy Section

1. Controller-per-Operation - Each endpoint is a separate controller class

   • Example: CreateDocumentController, UpdateDocumentController, DeleteDocumentController
   • Enables fine-grained authorization and operation-specific logic
   • Responsibilities: entrypoint/routing, authorization and mapping
   • avoid: business logic directly in controllers (there are a few known violations)

2. Presentation Factory Pattern - Factories convert domain models to ViewModels

   • Example: IDocumentEditingPresentationFactory (src/Umbraco.Cms.Api.Management/Factories/)
   • Separation: Controllers → Factories → ViewModels

3. Attempt Pattern - Operations return Attempt for status-based error handling

   • Controllers map status enums to HTTP status codes via helper methods

4. Authorization Service Pattern - All authorization via IAuthorizationService, not attributes

   • Checked in base controller methods (see ManagementApiControllerBase)

5. Options Pattern - All configuration via IOptions<T> (security, routing, OpenAPI)

6. SignalR Event Broadcasting - Real-time notifications via BackofficeHub and ServerEventHub

API Response & Endpoint Conventions Copy Section

These are firm design rules for this API. Prefer an extra round-trip over bending them.

1. Create/update (and other mutation) endpoints must not return the changed entity.
   A POST/PUT/PATCH that mutates state returns only status (e.g. Ok(), or CreatedAtId
   with the new id/Location) — never the updated entity in the body. Clients that need the
   resulting representation issue a separate GET. This keeps mutation endpoints minimal and
   avoids clients depending on server-computed fields sneaking back through a write.

   • Why it matters: server-computed state can differ from what the client optimistically
     expects (e.g. enabling a never-logged-in user leaves them Inactive, not Active).
     The correct fix is a read-back, not returning state from the mutation.
   • Batch read-back: when a client just mutated N entities and needs their fresh state,
     add/use a bulk retrieval endpoint rather than N single GETs. Pattern:
     GET {resource}/batch?id=...&id=... returning BatchResponseModel
     (see BatchDataTypesController, BatchUsersController). The batch controller lives under
     the resource's normal controller base so it carries the same authorization as the
     single-item GET (section access + per-resource checks).

2. Do not add data to item endpoints (/item/{resource}).
   Item endpoints (Item*Controller, used to hydrate pickers/lists) sit on
   ManagementApiControllerBase with only BackOfficeAccess — deliberately looser
   authorization than the section-scoped, per-resource GETs. Any authenticated backoffice
   user can call them. Never widen an item response model with fields that require stricter
   authorization to see (state, permissions, sensitive/computed data) — that leaks information
   past the resource's real authorization boundary. Put such fields on the properly-authorized
   detail or batch endpoint instead.

3. Versioning an endpoint the backoffice calls: pin the operation ID with a route Name.
   Operation IDs are generated from the route by UmbracoOperationIdTransformer, and a non-default
   [MapToApiVersion] is appended to them — so bumping an endpoint to 1.1 would rename the
   generated client method (putDocumentByIdValidate → putDocumentByIdValidate1_1) and churn every
   call site in the backoffice. The backoffice always calls the latest version, so the version in the
   method name carries no information.

   Give the latest version an explicit name matching what the unversioned route would have
   produced:

   csharp Copy

   [HttpPut("{id:guid}/validate", Name = "PutDocumentByIdValidate")]
   [MapToApiVersion("1.1")]

   Rules:

   • Only the latest version gets the unversioned name. Older versions keep their generated
     (version-suffixed) IDs — except at the default version (1.0), which is never suffixed.
     An older 1.0 action therefore generates the very name you are pinning, so it needs an
     explicit versioned name of its own at the same time:

     csharp Copy

     [HttpPut("{id:guid}/validate", Name = "PutDocumentByIdValidate1_0")]
     [MapToApiVersion("1.0")]

   • Two versions must never carry the same ID — duplicate operation IDs break OpenAPI
     generation, and ASP.NET Core will not catch the clash, since route names are only unique when
     both are explicit. OpenApiDocumentTests guards OpenApi.json against it. When moving the
     name to a new version, remove it from the old one, which deliberately renames the old
     operation.

   • Match the generated convention ({HttpMethod}{Path}By{Param}...) rather than inventing a
     name, or the API surface ends up a mix of styles.

   • Update OpenApi.json and regenerate the backoffice client afterwards.

2. Commands Copy Chapter

Build & Run Copy Section

# Build
dotnet build src/Umbraco.Cms.Api.Management

# Test (tests in ../../tests/Umbraco.Tests.Integration and Umbraco.Tests.UnitTests)
dotnet test --filter "FullyQualifiedName~Management"

# Pack (for NuGet distribution)
dotnet pack src/Umbraco.Cms.Api.Management -c Release

Code Quality Copy Section

# Format code
dotnet format src/Umbraco.Cms.Api.Management

# Build with warnings (note: some warnings suppressed, see .csproj line 23)
dotnet build src/Umbraco.Cms.Api.Management /p:TreatWarningsAsErrors=true

OpenAPI Documentation Copy Section

The project embeds a pre-generated OpenApi.json (1.3MB). To regenerate:

# Run Umbraco.Web.UI, access /umbraco/openapi/
# Download JSON from /umbraco/openapi/management.json

Package Management Copy Section

# Add package (versions centralized in Directory.Packages.props)
dotnet add src/Umbraco.Cms.Api.Management package [PackageName]

# Check for vulnerable packages
dotnet list src/Umbraco.Cms.Api.Management package --vulnerable

Environment Setup Copy Section

1. Prerequisites: .NET 10 SDK
2. IDE: Visual Studio 2022 or Rider (with .editorconfig support)
3. Configuration: Inherits from Umbraco.Web.UI appsettings (no app settings in this library)

3. Style Guide Copy Chapter

Project-Specific Patterns Copy Section

Controller Naming (line examples from CreateDocumentController.cs:16):

[ApiVersion("1.0")]
public class CreateDocumentController : CreateDocumentControllerBase

• Pattern: {Verb}{Entity}Controller (e.g., CreateDocumentController, UpdateMediaController)
• Base class: {Verb}{Entity}ControllerBase for shared logic
• Critical: One operation per controller (not one controller per resource)

Async Naming - All async methods use Async suffix consistently:

await _contentEditingService.CreateAsync(model, CurrentUserKey(_backOfficeSecurityAccessor));

Factory Pattern Usage (line 44):

ContentCreateModel model = _documentEditingPresentationFactory.MapCreateModel(requestModel);

• ViewModels → Domain: Map{Operation}Model(requestModel)
• Domain → ViewModels: Factory classes in Factories/ folder

Key Patterns from Codebase Copy Section

ControllerBase Helper Methods (inherited from ManagementApiControllerBase in Api.Common):

• CreatedAtId<TController>(expression, id) - Returns 201 with Location header
• ContentEditingOperationStatusResult(status) - Maps status enum to ProblemDetails
• CurrentUserKey(accessor) - Gets current user from security context

Authorization Pattern (all controllers):

private readonly IAuthorizationService _authorizationService;
// Check permissions in action, not via [Authorize] attribute

4. Test Bench Copy Chapter

Test Location Copy Section

• Unit Tests: tests/Umbraco.Tests.UnitTests/Umbraco.Cms.Api.Management/
• Integration Tests: tests/Umbraco.Tests.Integration/Umbraco.Cms.Api.Management/

Running Tests Copy Section

# All Management API tests
dotnet test --filter "FullyQualifiedName~Management"

# Specific domain (e.g., Document controllers)
dotnet test --filter "FullyQualifiedName~Management.Controllers.Document"

Testing Focus Copy Section

1. Controller logic - Request validation, authorization checks, status code mapping
2. Factories - ViewModel ↔ Domain model conversion accuracy
3. Authorization - Policy enforcement for each operation
4. OpenAPI schema - Ensure OpenAPI document generation doesn't break

InternalsVisibleTo Copy Section

Tests have access to internal types (see .csproj:44-52):

• Umbraco.Tests.UnitTests
• Umbraco.Tests.Integration
• DynamicProxyGenAssembly2 (for Moq)

5. Error Handling Copy Chapter

Operation Status Pattern Copy Section

Controllers use Attempt with strongly-typed status enums:

Attempt<ContentCreateResult, ContentEditingOperationStatus> result =
    await _contentEditingService.CreateAsync(model, userKey);

return result.Success
    ? CreatedAtId<ByKeyDocumentController>(controller => nameof(controller.ByKey), result.Result.Content!.Key)
    : ContentEditingOperationStatusResult(result.Status); // Maps to ProblemDetails

Status Enums (from Core):

• ContentEditingOperationStatus - InvalidParent, NotFound, NotAllowed, etc.
• UserOperationStatus - UserNameIsNotEmail, DuplicateUserName, etc.
• Each enum value maps to specific HTTP status + ProblemDetails type

ProblemDetails Copy Section

All errors return RFC 7807 ProblemDetails via helper methods in base controllers:

• 400 Bad Request: Validation failures, invalid operations
• 403 Forbidden: Authorization failures
• 404 Not Found: Resource not found
• 409 Conflict: Duplicate operations

Critical Logging Points Copy Section

1. Authorization failures - Logged by AuthorizationService
2. Service operation failures - Logged in Infrastructure layer services
3. External login errors - BackOfficeSignInManager (Security/)

6. Clean Code Copy Chapter

Key Design Decisions Copy Section

Why Controller-per-Operation? (not RESTful resource-based controllers)

• Fine-grained authorization per operation
• Operation-specific request/response models
• Clearer OpenAPI documentation
• Example: 20+ controllers in Controllers/Document/ for different operations

Why Manual Factories instead of AutoMapper?

• Explicit control over mapping logic
• Easier debugging (no magic)
• Better performance (no reflection overhead)
• See Factories/ directory (92 factory classes)

Project-Specific Architectural Decisions Copy Section

Embedded OpenAPI Spec (OpenApi.json - 1.3MB):

• Pre-generated, embedded as resource
• Served for client SDK generation
• Why? Deterministic output, faster startup (no runtime generation)

SignalR for Real-time:

• BackofficeHub (/umbraco/backofficeHub) - Generic payload broadcast
• ServerEventHub (/umbraco/serverEventHub) - Entity change events, filtered per user
• PreviewHub (/umbraco/PreviewHub) - Content refresh notifications for the preview window
• Every hub class carries [Authorize(Policy = AuthorizationPolicies.BackOfficeAccess)]. MapHub copies it onto the negotiate and connection endpoints, so an unattributed hub is reachable anonymously. PreviewRoutesTests and BackOfficeAreaRoutesTests assert this for every mapped hub endpoint.

Code Smells to Watch For Copy Section

1. Large factory classes - Some factories have 1000+ lines (e.g., UserGroupPresentationFactory.cs)

   • Consider splitting by operation

2. Repeated authorization checks - Each controller duplicates auth logic

   • Already abstracted to base classes, but still verbose

3. ViewModel explosion - 1000+ ViewModel classes across ViewModels/ folders

   • Consider shared base models or composition

7. Security Copy Chapter

Authentication & Authorization Copy Section

Method: OpenIddict (OAuth 2.0) via Umbraco.Cms.Api.Common

• Reference tokens (not JWT) stored in database
• Token validation via OpenIddict middleware
• ASP.NET Core Data Protection for token encryption

Authorization:

• Basic authorization is done trough policies and the AuthorizeAttribute

// Example from DocumentTreeControllerBase.cs, the user needs at least access to a section that uses trees
[Authorize(Policy = AuthorizationPolicies.SectionAccessForContentTree)]

• Authorization that needs (parts of) the payload are done manually trough the IAuthorizationService

// Example from CreateDocumentController.cs:22
private readonly IAuthorizationService _authorizationService;

// Authorization checked in base controller methods, not attributes
protected async Task<IActionResult> HandleRequest(request, Func<Task<IActionResult>> handler)
{
    var authResult = await _authorizationService.AuthorizeAsync(User, request, policy);
    // ...
}

Policies (defined in Security/Authorization/):

• ContentPermissionHandler - Document/Media CRUD permissions
• SectionAccessHandler - Backoffice section access
• UserGroupPermissionHandler - Admin operations

Password Requirements (Security/ConfigureBackOfficeIdentityOptions.cs:18):

• See Identity options configuration

External Login Providers Copy Section

Location: Security/BackOfficeExternalLoginProviders.cs

• Google, Microsoft, OpenID Connect providers
• Auto-linking with ExternalSignInAutoLinkOptions
• Critical: Validate external claims before auto-linking users

Input Validation Copy Section

FluentValidation used throughout:

• Request models validated automatically via MVC integration
• Custom validators in each domain folder (e.g., ViewModels/Document/Validators/)

Parameter Validation:

// Controllers validate IDs, keys before service calls
if (requestModel.Parent == null)
    return BadRequest(new ProblemDetailsBuilder()...);

API Security Copy Section

CORS - Configured in Umbraco.Web.UI (not this project)

HTTPS Enforcement - Configured in Umbraco.Web.UI

Request Size Limits - Configured for file uploads in Umbraco.Web.UI

Security Headers - Handled by Umbraco.Web.UI middleware

Secrets Management Copy Section

No secrets in this project - Configuration injected from parent application (Umbraco.Web.UI)

Dependency Security Copy Section

# Check vulnerable packages
dotnet list src/Umbraco.Cms.Api.Management package --vulnerable

Security Anti-Patterns to Avoid Copy Section

1. Never bypass authorization checks - All operations must authorize
2. Never trust client validation - Always validate on server
3. Never expose stack traces - ProblemDetails abstracts errors
4. Never log sensitive data - User passwords, tokens, API keys

8. Teamwork and Workflow Copy Chapter

⚠️ SKIPPED - This is a sub-project. See root /CLAUDE.md for repository-wide teamwork protocols.

9. Edge Cases Copy Chapter

Domain-Specific Edge Cases Copy Section

Document Operations:

1. Publishing with descendants - Can timeout on large trees

   • Use PublishDocumentWithDescendantsController with result polling
   • See Controllers/Document/PublishDocumentWithDescendantsResultController.cs

2. Recycle bin operations - Items in recycle bin can't be published

   • Check IsTrashed before publish operations

3. Public access rules - Affects authorization and routing

   • See Controllers/Document/CreatePublicAccessDocumentController.cs

Media Upload:

1. Large file uploads - Request size limits in parent app

   • Controllers accept multipart/form-data
   • Temporary files cleaned by background job

2. Media picker - Can reference deleted media

   • Validation in Factories/ checks for orphaned references

User Management:

1. External logins - Auto-linking can create duplicate users if email mismatches

   • See Security/ExternalSignInAutoLinkOptions.cs

2. User groups - Deleting user group doesn't delete users

   • Users reassigned to default group

Webhooks:

1. Webhook failures - Failed webhooks retry with exponential backoff
   • See Controllers/Webhook/ for configuration

Known Gotchas (from TODO comments) Copy Section

StyleSheet/Script/PartialView Tree Controllers - All have identical TODO comment:

TODO: [NL] This must return path segments for a query to work
// src/Umbraco.Cms.Api.Management/Controllers/Stylesheet/Tree/StylesheetTreeControllerBase.cs
// src/Umbraco.Cms.Api.Management/Controllers/Script/Tree/ScriptTreeControllerBase.cs
// src/Umbraco.Cms.Api.Management/Controllers/PartialView/Tree/PartialViewTreeControllerBase.cs

BackOfficeController - External login TODO:

// src/Umbraco.Cms.Api.Management/Controllers/Security/BackOfficeController.cs
// TODO: Handle external logins properly

10. Agentic Workflow Copy Chapter

When to Add a New Endpoint Copy Section

Decision Points:

1. Does the operation fit an existing controller domain? (Document, Media, User, etc.)
2. Is this a new CRUD operation or a custom action?
3. Does this require new authorization policies?

Workflow:

1. Create Controller in appropriate Controllers/{Domain}/ folder

   • Follow naming: {Verb}{Entity}Controller
   • Inherit from domain-specific base controller or ManagementApiControllerBase

2. Define ViewModels in ViewModels/{Domain}/

   • Request model (e.g., CreateDocumentRequestModel)
   • Response model (if not reusing existing)

3. Create or Update Factory in Factories/

   • Map request ViewModel → domain model
   • Map domain result → response ViewModel

4. Authorization - Check required permissions in controller action

   • Use IAuthorizationService.AuthorizeAsync()

5. Service Layer - Call Core services (from Umbraco.Core.Services)

   • Handle Attempt<> results
   • Map status to HTTP status codes

6. OpenAPI Annotations:

   • [ApiVersion("1.0")]
   • [MapToApiVersion("1.0")]
   • [ProducesResponseType(...)] for all status codes

7. Testing:

   • Unit test controller logic
   • Integration test end-to-end flow

8. Update OpenApi.json (if needed for client generation)

Quality Gates Before PR Copy Section

1. All tests pass
2. Code formatted (dotnet format)
3. No new warnings (check suppressed warnings list in .csproj:23)
4. OpenAPI schema valid (check at /umbraco/openapi/)
5. Authorization tested (unit + integration tests)

Common Pitfalls Copy Section

1. Forgetting authorization checks - Every operation must authorize
2. Inconsistent status code mapping - Use base controller helpers
3. Large factory classes - Split by operation if >500 lines
4. Missing ProducesResponseType - Breaks OpenAPI client generation
5. Not handling Attempt failures - Always check result.Success
6. Returning the entity from a mutation - Create/update endpoints return status only; the client does a follow-up GET (or {resource}/batch for many). See "API Response & Endpoint Conventions" in §1.
7. Widening item endpoints - Never add authorization-sensitive fields to /item/{resource} responses; they have looser auth. See "API Response & Endpoint Conventions" in §1.

11. Project-Specific Notes Copy Chapter

Key Design Decisions Copy Section

Why 1,317 files for one API?

• Controller-per-operation pattern = many controllers
• 54 domains × average 10-20 operations per domain
• Tradeoff: Verbose but explicit, easier to navigate than megacontrollers

Why manual factories instead of AutoMapper?

• Performance: No reflection overhead
• Debuggability: Step through mapping logic
• Control: Complex mappings (e.g., security trimming) require custom logic

Why embedded OpenApi.json?

• Deterministic OpenAPI spec for client generation
• Faster startup (no runtime generation)
• Easier versioning (commit changes to spec)
• Added OpenAPIContractTest to test that all operations are exported

External Integrations Copy Section

None directly in this project. All integrations handled by:

• Umbraco.Infrastructure - External search, media, email providers
• Umbraco.Core - External data sources, webhooks

Known Limitations Copy Section

1. API Versioning: Currently v1.0 and v1.1

   • Future versions will require new controller classes or action methods

2. Batch Operations: Limited batch endpoint support

   • Most operations are single-entity (create one document at a time)

3. Real-time Limits: SignalR hubs don't scale beyond single-server without Redis backplane

   • Configure Redis for multi-server setups

4. File Upload Size: Controlled by parent app (Umbraco.Web.UI)

   • This project doesn't set limits

Performance Considerations Copy Section

Caching:

• Published content cached via Umbraco.PublishedCache.HybridCache
• Controllers query cache, not database (for published content)

Background Jobs:

• Long-running operations (publish with descendants, export) return job ID
• Poll result endpoint for completion
• See Controllers/Document/PublishDocumentWithDescendantsResultController.cs

OpenAPI Generation:

• Pre-generated (OpenApi.json embedded)
• Runtime generation disabled for performance

Technical Debt (Top Issues from TODO comments) Copy Section

1. Warnings Suppressed (Umbraco.Cms.Api.Management.csproj:9-22):

   text Copy

   TODO: Fix and remove overrides:
   - SA1117: params all on same line
   - SA1401: make fields private
   - SA1134: own line attributes
   - CS0108: hidden inherited member
   - CS0618/CS9042: update obsolete references
   - CS1998: remove async or make method synchronous
   - CS8524: switch statement exhaustiveness
   - IDE0060: removed unused parameter
   - SA1649: file name match type
   - CS0419: ambiguous reference
   - CS1573: param tag for all parameters
   - CS1574: unresolveable cref

2. Tree Controller Path Segments (multiple files):

   • Stylesheet/Script/PartialView tree controllers need path segment support for queries
   • Files: Controllers/Stylesheet/Tree/StylesheetTreeControllerBase.cs
   • Files: Controllers/Script/Tree/ScriptTreeControllerBase.cs
   • Files: Controllers/PartialView/Tree/PartialViewTreeControllerBase.cs

3. External Login Handling (Controllers/Security/BackOfficeController.cs):

   • TODO: Handle external logins properly

4. Large Factory Classes (Factories/UserGroupPresentationFactory.cs):

   • Some factories exceed 1000 lines - consider splitting

5. ViewModel Explosion - 1000+ ViewModel classes

   • Consider shared base models or composition to reduce duplication

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build
dotnet build src/Umbraco.Cms.Api.Management

# Test Management API
dotnet test --filter "FullyQualifiedName~Management"

# Format code
dotnet format src/Umbraco.Cms.Api.Management

# Pack for NuGet
dotnet pack src/Umbraco.Cms.Api.Management -c Release

Key Projects Copy Section

• Umbraco.Cms.Api.Management (this) - Management API controllers and models
• Umbraco.Cms.Api.Common - Shared API infrastructure, base controllers
• Umbraco.Infrastructure - Service implementations, data access
• Umbraco.Core - Domain models, service interfaces

Important Files Copy Section

• Project file: src/Umbraco.Cms.Api.Management/Umbraco.Cms.Api.Management.csproj
• Composer: src/Umbraco.Cms.Api.Management/ManagementApiComposer.cs (DI entry point)
• Routing: src/Umbraco.Cms.Api.Management/Routing/BackOfficeAreaRoutes.cs
• OpenAPI Spec: src/Umbraco.Cms.Api.Management/OpenApi.json (embedded, 1.3MB)
• Base Controllers: See Umbraco.Cms.Api.Common project

Configuration Copy Section

No appsettings in this library - all configuration from parent app (Umbraco.Web.UI):

• OpenIddict settings
• CORS settings
• File upload limits

API Endpoints Copy Section

Base path: /umbraco/management/api/v1/

Examples:

• POST /umbraco/management/api/v1/document - Create document
• GET /umbraco/management/api/v1/document/{id} - Get document by key
• PUT /umbraco/management/api/v1/document/{id} - Update document
• DELETE /umbraco/management/api/v1/document/{id} - Delete document

Full spec: See OpenApi.json or Swagger UI at /umbraco/openapi/

Getting Help Copy Section

• Root Documentation: /CLAUDE.md (repository overview)
• API Common Docs: ../Umbraco.Cms.Api.Common/CLAUDE.md (shared API patterns)
• Core Docs: ../Umbraco.Core/CLAUDE.md (domain architecture)
• Official Docs: https://docs.umbraco.com/umbraco-cms/reference/management-api

File: src/Umbraco.Cms.DevelopmentMode.Backoffice/CLAUDE.md Copy Chapter

Umbraco.Cms.DevelopmentMode.Backoffice

Development-time library enabling InMemoryAuto ModelsBuilder mode with runtime Razor view compilation. Allows content type changes to instantly regenerate strongly-typed models without application restart.

1. Architecture Copy Chapter

Type: Class Library (NuGet Package)
Target Framework: .NET 10.0
Purpose: Enable hot-reload of ModelsBuilder models during development

Key Technologies Copy Section

• Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation - Runtime Razor view compilation
• Microsoft.CodeAnalysis.CSharp (Roslyn) - Runtime C# compilation
• AssemblyLoadContext - Collectible assembly loading/unloading

Dependencies Copy Section

• Umbraco.Web.Common - Umbraco web infrastructure

Project Structure (18 source files) Copy Section

Umbraco.Cms.DevelopmentMode.Backoffice/
├── DependencyInjection/
│   ├── BackofficeDevelopmentComposer.cs   # Auto-registration via IComposer
│   └── UmbracoBuilderExtensions.cs        # DI setup (CRITICAL: contains 80-line design overview)
└── InMemoryAuto/
    ├── InMemoryModelFactory.cs            # Core factory - generates/loads models (876 lines)
    ├── InMemoryAssemblyLoadContextManager.cs  # Manages collectible AssemblyLoadContext
    ├── RoslynCompiler.cs                  # Compiles generated C# to DLL
    ├── CollectibleRuntimeViewCompiler.cs  # Custom IViewCompiler for Razor (489 lines)
    ├── UmbracoViewCompilerProvider.cs     # Provides CollectibleRuntimeViewCompiler
    ├── RuntimeCompilationCacheBuster.cs   # Clears Razor caches on model rebuild
    ├── UmbracoRazorReferenceManager.cs    # Manages Roslyn MetadataReferences
    ├── CompilationOptionsProvider.cs      # Mirrors host app compilation settings
    ├── UmbracoAssemblyLoadContext.cs      # Collectible AssemblyLoadContext wrapper
    ├── ChecksumValidator.cs               # Validates precompiled view checksums
    ├── CompilationExceptionFactory.cs     # Creates detailed compilation errors
    ├── UmbracoCompilationException.cs     # Custom exception with CompilationFailures
    ├── ModelsBuilderAssemblyAttribute.cs  # Marks InMemory assemblies
    ├── ModelsBuilderBindingErrorHandler.cs # Handles model binding version mismatches
    ├── InMemoryModelsBuilderModeValidator.cs # Validates runtime mode configuration
    └── ModelsModeConstants.cs             # "InMemoryAuto" constant

Design Patterns Copy Section

1. Clone-and-Own Pattern - ASP.NET Core's RuntimeViewCompiler and related classes are cloned because internal APIs can't be extended
2. Collectible AssemblyLoadContext - Enables assembly unloading for hot-reload
3. FileSystemWatcher - Monitors ~/umbraco/Data/TEMP/InMemoryAuto/ for changes
4. Lazy Initialization - References resolved on first use, not startup

2. Key Patterns Copy Chapter

Why Clone-and-Own (CRITICAL CONTEXT) Copy Section

The 80-line comment in DependencyInjection/UmbracoBuilderExtensions.cs:13-80 explains why this project exists. Key points:

1. Problem: ASP.NET Core's RuntimeViewCompiler loads assemblies into the default AssemblyLoadContext, which can't reference collectible contexts (breaking change in .NET 7)
2. Failed Solutions:
   • Reflection to clear caches (unstable, internal APIs)
   • Service wrapping via DI (still loads into wrong context)
3. Solution: Clone RuntimeViewCompiler, RazorReferenceManager, ChecksumValidator, and related classes, modifying them to:
   • Load compiled views into the same collectible AssemblyLoadContext as models
   • Explicitly add InMemoryAuto models assembly reference during compilation

InMemoryModelFactory Lifecycle Copy Section

Content Type Changed → Reset() called → _pendingRebuild = true
                                           ↓
Next View Request → EnsureModels() → GetModelsAssembly(forceRebuild: true)
                                           ↓
                    GenerateModelsCode() → RoslynCompiler.CompileToFile()
                                           ↓
                    ReloadAssembly() → InMemoryAssemblyLoadContextManager.RenewAssemblyLoadContext()
                                           ↓
                    RuntimeCompilationCacheBuster.BustCache() → Views recompile with new models

Assembly Caching Strategy Copy Section

Models are cached to disk for faster boot (InMemoryModelFactory.cs:400-585):

1. Hash Check: TypeModelHasher.Hash(typeModels) creates hash of content type definitions

2. Cache Files (in ~/umbraco/Data/TEMP/InMemoryAuto/):

   • models.hash - Current content type hash
   • models.generated.cs - Generated source
   • all.generated.cs - Combined source with assembly attributes
   • all.dll.path - Path to compiled DLL
   • Compiled/generated.cs{hash}.dll - Compiled assembly

3. Boot Sequence:

   • Check if models.hash matches current hash
   • If match, load existing DLL
   • If mismatch or missing, recompile

Collectible AssemblyLoadContext Copy Section

// InMemoryAssemblyLoadContextManager.cs:29-37
internal void RenewAssemblyLoadContext()
{
    _currentAssemblyLoadContext?.Unload();  // Unload previous
    _currentAssemblyLoadContext = new UmbracoAssemblyLoadContext();  // Create new collectible
}

Key constraint: No external references to the AssemblyLoadContext allowed - prevents unloading.

3. Error Handling Copy Chapter

Compilation Failures Copy Section

CompilationExceptionFactory.cs creates UmbracoCompilationException with:

• Source file content
• Generated code
• Diagnostic messages with line/column positions

Errors logged in CollectibleRuntimeViewCompiler.cs:383-396 and InMemoryModelFactory.cs:341-354.

Model Binding Errors Copy Section

ModelsBuilderBindingErrorHandler.cs handles version mismatches between:

• View's model type (from compiled view assembly)
• Content's model type (from InMemoryAuto assembly)

Reports detailed error messages including assembly versions.

4. Security Copy Chapter

Runtime Mode Validation: InMemoryModelsBuilderModeValidator.cs prevents InMemoryAuto mode outside BackofficeDevelopment runtime mode.

Temp File Location: Models compiled to ~/umbraco/Data/TEMP/InMemoryAuto/ - ensure this directory isn't web-accessible.

5. Edge Cases & Known Issues Copy Chapter

Technical Debt (TODOs) Copy Section

1. Circular Reference - InMemoryModelFactory.cs:46:

   csharp Copy

   private readonly Lazy<UmbracoServices> _umbracoServices; // TODO: this is because of circular refs :(

2. DynamicMethod Performance - InMemoryModelFactory.cs:698-701:

   csharp Copy

   // TODO: use Core's ReflectionUtilities.EmitCtor !!
   // Yes .. DynamicMethod is uber slow

Race Conditions Copy Section

InMemoryModelFactory.cs:800-809 - FileSystemWatcher can cause race conditions on slow cloud filesystems. Own file changes are always ignored.

Unused Assembly Cleanup Copy Section

InMemoryModelFactory.cs:587-612 - TryDeleteUnusedAssemblies may fail with UnauthorizedAccessException if files are locked. Cleanup retried on next rebuild.

Reflection for Cache Clearing Copy Section

RuntimeCompilationCacheBuster.cs:50-51 uses reflection to call internal RazorViewEngine.ClearCache():

Action<RazorViewEngine>? clearCacheMethod = ReflectionUtilities.EmitMethod<Action<RazorViewEngine>>("ClearCache");

6. Configuration Copy Chapter

Enable InMemoryAuto mode (appsettings.json):

{
  "Umbraco": {
    "CMS": {
      "Runtime": {
        "Mode": "BackofficeDevelopment"
      },
      "ModelsBuilder": {
        "ModelsMode": "InMemoryAuto"
      }
    }
  }
}

Requirements:

• RuntimeMode must be BackofficeDevelopment
• ModelsMode must be InMemoryAuto

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build
dotnet build src/Umbraco.Cms.DevelopmentMode.Backoffice/Umbraco.Cms.DevelopmentMode.Backoffice.csproj

# Pack for NuGet
dotnet pack src/Umbraco.Cms.DevelopmentMode.Backoffice/Umbraco.Cms.DevelopmentMode.Backoffice.csproj -c Release

# Run integration tests
dotnet test tests/Umbraco.Tests.Integration/ --filter "FullyQualifiedName~ModelsBuilder"

Note: This library has no direct tests - tested via integration tests in Umbraco.Tests.Integration.

Focus areas when modifying:

• Assembly loading/unloading cycles
• Razor view compilation with models
• Cache invalidation timing
• Model binding error scenarios

Essential Classes Copy Section

Important Files Copy Section

• Design Overview: DependencyInjection/UmbracoBuilderExtensions.cs:13-80 - READ THIS FIRST
• Project File: Umbraco.Cms.DevelopmentMode.Backoffice.csproj
• Model Factory: InMemoryAuto/InMemoryModelFactory.cs - Most complex class

Cloned Microsoft Code Copy Section

These files are clones of ASP.NET Core internals - check upstream for updates:

• ChecksumValidator.cs - https://github.com/dotnet/aspnetcore/blob/main/src/Mvc/Mvc.Razor.RuntimeCompilation/src/ChecksumValidator.cs
• UmbracoRazorReferenceManager.cs - https://github.com/dotnet/aspnetcore/blob/main/src/Mvc/Mvc.Razor.RuntimeCompilation/src/RazorReferenceManager.cs
• CompilationOptionsProvider.cs - Partial clone of CSharpCompiler
• CompilationExceptionFactory.cs - Partial clone of CompilationFailedExceptionFactory

Getting Help Copy Section

• Root Documentation: /CLAUDE.md
• Core Patterns: /src/Umbraco.Core/CLAUDE.md
• Official Docs: https://docs.umbraco.com/umbraco-cms/reference/configuration/modelsbuildersettings

This library enables hot-reload of content models during development. The core complexity is working around ASP.NET Core's internal Razor compilation APIs. Always read the design overview in UmbracoBuilderExtensions.cs:13-80 before making changes.

File: src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md Copy Chapter

Umbraco.Cms.Imaging.ImageSharp

Image processing library using ImageSharp 3.x and ImageSharp.Web for on-the-fly image manipulation, resizing, cropping, and caching.

1. Architecture Copy Chapter

Type: Class Library (NuGet Package)
Target Framework: .NET 10.0
Purpose: Provide image manipulation via query string parameters

Key Technologies Copy Section

• SixLabors.ImageSharp - Image processing library
• SixLabors.ImageSharp.Web - ASP.NET Core middleware for query string-based image manipulation

Both packages validate a licence key at build time; the key and its renewal details are in SIXLABORS-LICENSE.md.

Dependencies Copy Section

• Umbraco.Web.Common - Web infrastructure

Project Structure (13 source files) Copy Section

Umbraco.Cms.Imaging.ImageSharp/
├── ImageSharpComposer.cs                    # Auto-registration via IComposer
├── UmbracoBuilderExtensions.cs              # DI setup and middleware configuration
├── ConfigureImageSharpMiddlewareOptions.cs  # Middleware options (caching, HMAC, size limits, decode throttle)
├── ConfigurePhysicalFileSystemCacheOptions.cs # File cache location
├── ImageProcessingThrottleMiddleware.cs     # Bounds concurrent processing; owns the slot lifetime
├── ImageProcessingSlot.cs                   # One request's claim on the concurrency limit
├── ImageProcessingMemory.cs                 # Derives and applies the memory bounds (shared with ImageSharp2)
├── ImageProcessingThrottle.cs               # How long a request waits, and how it is turned away
├── ImageProcessingUnavailableException.cs   # Raised from the decode hook when the wait is given up on
├── ImageProcessors/
│   └── CropWebProcessor.cs                  # Custom crop processor with EXIF awareness
└── Media/
    ├── ImageSharpDimensionExtractor.cs      # Extract image dimensions (EXIF-aware)
    ├── ImageSharpImageUrlGenerator.cs       # Generate query string URLs for processing
    └── ImageSharpImageUrlTokenGenerator.cs  # Re-sign image URLs after an HMAC key rotation

Relationship to ImageSharp2 Copy Section

Two imaging packages exist:

• Umbraco.Cms.Imaging.ImageSharp (this package) - Uses ImageSharp 3.x (default)
• Umbraco.Cms.Imaging.ImageSharp2 - Uses ImageSharp 2.x for backwards compatibility

Key difference: ImageSharp 3.x WebP encoder defaults to Lossless (10x larger files), so this package explicitly sets WebpFileFormatType.Lossy at ConfigureImageSharpMiddlewareOptions.cs:108-115.

2. Key Patterns Copy Chapter

Query String Image Processing Copy Section

Images are processed via URL query parameters handled by ImageSharp.Web middleware:

Pipeline Integration Copy Section

The wiring lives in UmbracoBuilderExtensions.cs, in the pre-pipeline of the ImageSharpComposer
pipeline filter, and its order matters:

1. The memory bounds are applied first, while the pipeline is being built, so nothing can decode
   before they are in force.
2. ImageProcessingThrottleMiddleware is registered ahead of the imaging middleware, because it
   must own the request before the decode hook fires.
3. UseImageSharp() runs before static files, or the query string is ignored and the source is
   served as-is.

EXIF Orientation Handling Copy Section

Both ImageSharpDimensionExtractor and CropWebProcessor account for EXIF rotation:

// ImageSharpDimensionExtractor.cs:42-44 - Swap width/height for rotated images
size = IsExifOrientationRotated(imageInfo)
    ? new Size(imageInfo.Height, imageInfo.Width)
    : new Size(imageInfo.Width, imageInfo.Height);

// CropWebProcessor.cs:64-65 - Transform crop coordinates for EXIF orientation
Vector2 xy1 = ExifOrientationUtilities.Transform(new Vector2(left, top), Vector2.Zero, Vector2.One, orientation);

HMAC Request Authorization Copy Section

When HMACSecretKey is configured, URLs are signed to prevent abuse (ImageSharpImageUrlGenerator.cs:121-131):

if (_options.HMACSecretKey.Length != 0 && _requestAuthorizationUtilities is not null)
{
    var token = _requestAuthorizationUtilities.ComputeHMAC(uri, CommandHandling.Sanitize);
    queryString.Add(RequestAuthorizationUtilities.TokenCommand, token);
}

3. Configuration Copy Chapter

ImagingSettings (appsettings.json) Copy Section

{
  "Umbraco": {
    "CMS": {
      "Imaging": {
        "HMACSecretKey": "",
        "Cache": {
          "BrowserMaxAge": "7.00:00:00",
          "CacheMaxAge": "365.00:00:00",
          "CacheHashLength": 12,
          "CacheFolder": "~/umbraco/Data/TEMP/MediaCache",
          "CacheFolderDepth": 8
        },
        "Resize": {
          "MaxWidth": 5000,
          "MaxHeight": 5000
        },
        "Memory": {
          "Enabled": false,
          "MaximumPoolSizeMegabytes": 0,
          "MaximumConcurrentProcessing": 0,
          "MaximumDecodedImageMegabytes": 0
        }
      }
    }
  }
}

Memory Settings (`ImagingMemorySettings`) Copy Section

Each numeric value defaults to 0, meaning "derive from the memory available to the process"
(GC.GetGCMemoryInfo().TotalAvailableMemoryBytes, which honours a container limit).

ImagingMemorySettings in Umbraco.Core carries only these four values. What each is derived as,
and whether it applies at all, lives in ImageProcessingMemory in this project — the policy only
means anything against ImageSharp's own defaults, which Core knows nothing about.

The feature is off by default in v17/v18 and on from v19 (Enabled), so a minor upgrade
cannot change how an existing site allocates image memory — a site opts in until the major ships it
on. When enabled, each bound is still conditional — it engages only where it earns its keep —
and setting a value explicitly overrides that test, so an operator who names a number gets it.

All three engage on the same flat memory threshold. The pool cap is about retention, and
ImageSharp's default there is an eighth of available memory on any 64-bit host — GetDefaultMaxPoolSizeBytes
returns total / 8 when Environment.Is64BitProcess, and a flat 128 MB otherwise. It is never
disproportionate; it is a problem only in absolute terms, where that eighth competes with the memory
the rest of the site needs. Hence a flat memory threshold rather than a ratio.

Concurrency once engaged on a different test — derived < ProcessorCount, on the reasoning that
decoding is CPU bound so the cores already cap it. But requests in flight are thread-pool bound, not
core bound, so a low-core host still holds many concurrent decodes, and that test left the gate off
on exactly the low-core, memory-limited instances that most needed it — a 1-core B1 App Service SKU
being the case in point (#23556). It now
engages on the shared memory threshold, and ProcessorCount survives only as an upper clamp on
the resolved value (ResolveMaximumConcurrentProcessing), so on a host with cores to spare the bound
simply lands there.

The single-image ceiling exists because the concurrency bound assumes a cost per image
(EstimatedMegabytesPerImage, measured against a 12 megapixel JPEG). Peak is count x size, and
bounding only the count leaves the size trusted — a 100 megapixel source decodes to roughly 400 MB,
so even a derived limit of 3 would exhaust a 512 MB container. This bounds the other factor, and it
maps onto ImageSharp's AllocationLimitMegabytes, whose own default is a flat 1 GB on a 32-bit
process and 4 GB on a 64-bit one.

It applies per allocation, not per image: a decode makes several, so the total can still exceed
the ceiling. What it caps is the dominant one — the pixel buffer, roughly width x height x 3 for a
JPEG — which is enough to catch a source far larger than the host can serve. Over the limit,
ImageSharp throws InvalidMemoryOperationException wrapped in an InvalidImageContentException
blaming "possibly degenerate dimensions", so ImageProcessingThrottleMiddleware logs a warning
naming the setting before letting the failure through. Note this is unrelated to Resize.MaxWidth
and Resize.MaxHeight, which bound the output dimensions, not the source decode.

A request over the limit waits, then after ImageProcessingThrottle.WaitTimeout (30 seconds) is
turned away with 503 and a Retry-After, logged as a warning. It must not be let through
unthrottled on expiry instead — concurrent decodes are the thing being bounded, so that reinstates
the OOM under sustained load.

Enabled: false is the one-setting escape hatch that restores stock ImageSharp behaviour — and,
until v19, the default. Configure reports two independent facts about it, each once at startup:

• On a host a bound would have engaged on (under the 4 GB threshold), it says so at
  Information, naming the available memory, the threshold and the switch
  (Umbraco:CMS:Imaging:Memory:Enabled) — so an operator staring at an exit 137 on a memory-limited
  box is pointed at the setting rather than left to find it. On a host with memory to spare it stays
  quiet (Debug), so an unaffected site says nothing.
• If any bound has been set explicitly while the switch is off, that is a contradiction in the
  configuration rather than a property of the host, so it is reported at Information whatever
  the host, naming the settings being discarded.

Each bound reports itself at startup — Information when it engages, naming the resolved value, and
Debug when it does not, so an unaffected site running at Information says nothing. Those lines are
the first thing to ask for when diagnosing either an exit 137 or an unexplained change in image
throughput.

Why these exist: a source image is decoded at full resolution before any processor runs, and
ImageSharpMiddleware only de-duplicates concurrent requests for the same URL. A page of distinct
thumbnails therefore decodes every source in parallel, so peak memory is
concurrent requests x decoded source size — measured at ~60 MB for one 300x300 thumbnail of a
4000x3000 JPEG. Unbounded, that exhausts a container limit and the process is killed (exit 137).

The concurrency cap is applied in two stages, and requests over it wait rather than being rejected.

1. ImageProcessingThrottleMiddleware, registered ahead of UseImageSharp() in the pre-pipeline,
   decides whether a request could decode: it needs a registered processor command and a format
   that resolves to a configured image format, so an unrelated response like
   /export.csv?format=xlsx is left alone. For those that qualify it publishes an
   ImageProcessingSlot on HttpContext.Items and releases it when the request ends, if nothing
   else has by then.
2. ConfigureImageSharpMiddlewareOptions wires OnBeforeLoadAsync, which ImageSharp invokes on a
   cache miss only, after the source is resolved and immediately before the decode. That is
   where the wait happens, so a cache hit never queues behind a decode.

Splitting it this way keeps the wait precise while leaving a release somewhere it is guaranteed to
run. The place is normally given back from OnProcessedAsync, which ImageSharp invokes once the
decoded image has been disposed and before the result is written to the cache and sent — so the
cache write and the response, which hold only the encoded result, do not occupy a place. The
middleware's finally releases again when the request ends, which is a no-op after the first, and
covers a request that faulted or was turned away before reaching the hook.

ImageSharp 2.x differs on the way in, not the way out. ImageSharp.Web 2.0.2 has no
OnBeforeLoadAsync (its earliest hook, OnParseCommandsAsync, runs before the cache check), so
Umbraco.Cms.Imaging.ImageSharp2 takes the place in the middleware for anything its request filter
matches — cache hits included. It does have OnProcessedAsync, so the release is the same as above.
The two copies of ImageProcessingThrottleMiddleware are therefore not interchangeable; the v2
copy is the coarser fallback.

ImageSharp's own pool default is an eighth of available memory on a 64-bit process, released only on
a gen2 collection and then at most 50% per minute, which leaves a container sitting well above its
working set at rest. This memory is unmanaged, so no DOTNET_GC* setting governs it.

Security: Max Dimension Limits Copy Section

ConfigureImageSharpMiddlewareOptions.cs enforces max dimensions on every request, regardless of whether HMAC is configured:

• Width/height requests exceeding MaxWidth/MaxHeight are stripped from the query
• This prevents DoS via excessive image generation

HMAC and the size limits do two separate jobs: HMAC controls who may request processing, while MaxWidth/MaxHeight control how large the output may be. The dimension ceiling therefore still applies to validly-signed requests — for legitimate (server-generated) URLs it is a no-op, and it remains a useful backstop if the HMAC secret key ever leaks.

Cache Busting Copy Section

Query parameters rnd or v trigger immutable cache headers (ConfigureImageSharpMiddlewareOptions.cs:86-106):

• Disables MustRevalidate
• Adds immutable directive

4. Core Interfaces Implemented Copy Chapter

5. Edge Cases Copy Chapter

WebP Encoding Change (ImageSharp 3.x) Copy Section

ConfigureImageSharpMiddlewareOptions.cs:108-115 - ImageSharp 3.x defaults WebP to Lossless for PNGs, creating ~10x larger files. This is overridden:

options.Configuration.ImageFormatsManager.SetEncoder(
    WebpFormat.Instance,
    new WebpEncoder { FileFormat = WebpFileFormatType.Lossy });

Crop Coordinates Format Copy Section

CropWebProcessor.cs:50-56 - The cc parameter expects 4 values as distances from edges:

• Format: left,top,right,bottom (0-1 range, percentages)
• Right/bottom values are distance from those edges, not coordinates
• Zero values (0,0,0,0) are ignored (no crop)

Supported File Types Copy Section

Dynamically determined from ImageSharp configuration (ImageSharpDimensionExtractor.cs:24):

SupportedImageFileTypes = configuration.ImageFormats.SelectMany(f => f.FileExtensions).ToArray();

Default includes: jpg, jpeg, png, gif, bmp, webp, tiff, etc.

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build
dotnet build src/Umbraco.Cms.Imaging.ImageSharp/Umbraco.Cms.Imaging.ImageSharp.csproj

# Run tests
dotnet test tests/Umbraco.Tests.UnitTests/ --filter "FullyQualifiedName~ImageSharp"

Key Files Copy Section

URL Examples Copy Section

# Basic resize
/media/image.jpg?width=800

# Crop to aspect ratio with focal point
/media/image.jpg?width=800&height=600&mode=crop&rxy=0.5,0.3

# Custom crop coordinates (10% from each edge)
/media/image.jpg?cc=0.1,0.1,0.1,0.1

# Format conversion with quality
/media/image.jpg?format=webp&quality=80

# Cache busted (immutable headers)
/media/image.jpg?width=800&v=abc123

Getting Help Copy Section

• Root Documentation: /CLAUDE.md
• ImageSharp Docs: https://docs.sixlabors.com/
• Umbraco Imaging: https://docs.umbraco.com/umbraco-cms/reference/configuration/imagingsettings

This library provides query string-based image processing. Key concerns are EXIF orientation handling, WebP encoding defaults, and HMAC security for public-facing sites.

File: src/Umbraco.Cms.Imaging.ImageSharp/SIXLABORS-LICENSE.md Copy Chapter

Six Labors licence key

sixlabors.lic is the Six Labors licence key that the SixLabors.ImageSharp and SixLabors.ImageSharp.Web packages validate at build time. Release builds fail without a valid key; Debug builds only warn. The project points at the file through the SixLaborsLicenseFile property in Umbraco.Cms.Imaging.ImageSharp.csproj.

The key is assembly-scoped, so it is valid only for the assembly named above and may be committed to this public repository. Use the file exactly as issued; do not edit its contents. A new project that references a Six Labors package directly must have its assembly name added to the key when it is renewed.

Renewal Copy Chapter

Renew in the final 90 days before expiry (from 12-10-2027) by resubmitting the form at https://licensing.sixlabors.com/ from the same email address used for the original application, selecting OpenSource and listing the exact assembly names. Replace sixlabors.lic with the new file and update the details above.

Background Copy Chapter

See the Six Labors announcement, Security Support and License Enforcement.

File: src/Umbraco.Cms.Imaging.ImageSharp2/CLAUDE.md Copy Chapter

Umbraco.Cms.Imaging.ImageSharp2

Image processing library using ImageSharp 2.x for backwards compatibility with existing deployments. Use this package only when migrating from older Umbraco versions that depend on ImageSharp 2.x behavior.

Namespace Note: Uses Umbraco.Cms.Imaging.ImageSharp (same as v3 package) for drop-in replacement - no code changes needed when switching.

1. Architecture Copy Chapter

Type: Class Library (NuGet Package)
Target Framework: .NET 10.0
Purpose: ImageSharp 2.x compatibility layer

Package Versions (Pinned) Copy Section

<!-- From csproj lines 7-8 -->
<PackageReference Include="SixLabors.ImageSharp" VersionOverride="[2.1.11, 3)" />
<PackageReference Include="SixLabors.ImageSharp.Web" VersionOverride="[2.0.2, 3)" />

Version constraint [2.1.11, 3) means: minimum 2.1.11, below 3.0.

Project Structure (7 source files, plus 5 linked from the 3.x package) Copy Section

Umbraco.Cms.Imaging.ImageSharp2/
├── ImageSharpComposer.cs                    # Auto-registration via IComposer
├── UmbracoBuilderExtensions.cs              # DI setup, memory bounds and middleware configuration
├── ConfigureImageSharpMiddlewareOptions.cs  # Middleware options (caching, size limits, decode slot release)
├── ImageProcessingThrottleMiddleware.cs     # Bounds concurrent processing (2.x variant: waits before the pipeline)
├── ImageProcessors/
│   └── CropWebProcessor.cs                  # Custom crop processor with EXIF awareness
└── Media/
    ├── ImageSharpDimensionExtractor.cs      # Extract image dimensions (EXIF-aware)
    └── ImageSharpImageUrlGenerator.cs       # Generate query string URLs

Five more files are compiled in from the 3.x package as linked sources rather than copied, because
nothing in them touches an API that differs between the two majors. The linked-source group in the
csproj is the list. Edit them in the 3.x project; both packages pick up the change.

2. Key Differences from ImageSharp (3.x) Copy Chapter

API Differences in Code Copy Section

ImageSharpDimensionExtractor (Media/ImageSharpDimensionExtractor.cs:31):

// v2: Direct method call
IImageInfo imageInfo = Image.Identify(_configuration, stream);

// v3: Uses DecoderOptions
ImageInfo imageInfo = Image.Identify(options, stream);

CropWebProcessor (ImageProcessors/CropWebProcessor.cs:67):

// v2: Size is a method
Size size = image.Image.Size();

// v3: Size is a property
Size size = image.Image.Size;

Missing Features (vs ImageSharp 3.x) Copy Section

1. No HMAC request authorization - HMACSecretKey setting is ignored
2. No v cache buster - Only rnd parameter triggers immutable headers
3. No WebP encoder override - Uses default Lossy encoding (no configuration needed)
4. No OnBeforeLoadAsync hook - The decode throttle waits before the pipeline instead (see below)

Image Processing Memory Copy Section

Both packages bound image processing memory the same way, from the linked ImageProcessingMemory:
a pool cap, a single-image ceiling and a concurrency limit, all off by default until v19 and all
governed by Umbraco:CMS:Imaging:Memory. The derivation, the engagement tests and the startup
logging are documented once, in the 3.x package's CLAUDE.md under "Memory Settings".

The one difference is where a gated request waits. ImageSharp.Web 2.0.2 has no
OnBeforeLoadAsync, so this package's ImageProcessingThrottleMiddleware takes its place before
the downstream pipeline runs - a cache hit, or a missing source falling through to a 404, waits as
much as a decode does. The release is shared: OnProcessedAsync exists in 2.x, so
ConfigureImageSharpMiddlewareOptions gives the place back as soon as the decoded image is
disposed, with the end of the request as the backstop.

One consequence of having no decode hook: if ImageSharp.Web retries a request because a freshly
cached result could not be read back, the second decode runs after the place has been released and
nothing takes it again. The 3.x package re-enters its decode hook on a retry and re-acquires.

3. When to Use This Package Copy Chapter

Use ImageSharp2 when:

• Migrating from Umbraco versions that used ImageSharp 2.x
• Third-party packages have hard dependency on ImageSharp 2.x
• Need exact byte-for-byte output compatibility with existing cached images

Use ImageSharp (3.x) when:

• New installations
• Need HMAC URL signing for security
• Want latest performance improvements

4. Configuration Copy Chapter

Same as ImageSharp 3.x. See /src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md → Section 3 for full configuration details.

Key difference: HMACSecretKey setting exists but is ignored in this package (no HMAC support in v2).

Quick Reference Copy Chapter

Essential Commands Copy Section

# Build
dotnet build src/Umbraco.Cms.Imaging.ImageSharp2/Umbraco.Cms.Imaging.ImageSharp2.csproj

# Run tests
dotnet test tests/Umbraco.Tests.UnitTests/ --filter "FullyQualifiedName~ImageSharp"

Key Files Copy Section

Switching Between Packages Copy Section

To switch from ImageSharp2 to ImageSharp (3.x):

1. Remove Umbraco.Cms.Imaging.ImageSharp2 package reference
2. Add Umbraco.Cms.Imaging.ImageSharp package reference
3. Clear media cache folder (~/umbraco/Data/TEMP/MediaCache)
4. No code changes needed (same namespace)

Getting Help Copy Section

• ImageSharp 3.x Documentation: /src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md
• Root Documentation: /CLAUDE.md
• SixLabors ImageSharp 2.x Docs: https://docs.sixlabors.com/

This is a backwards-compatibility package. For new projects, use Umbraco.Cms.Imaging.ImageSharp (3.x) instead.

File: src/Umbraco.Cms.Persistence.EFCore/CLAUDE.md Copy Chapter

Umbraco.Cms.Persistence.EFCore

Entity Framework Core persistence layer for Umbraco CMS. This project provides EF Core integration including scoping, distributed locking, and migration infrastructure.

Project Type: Class Library (NuGet package)
Target Framework: net10.0
Dependencies: Umbraco.Core, Umbraco.Infrastructure

1. Architecture Copy Chapter

Project Purpose Copy Section

This project bridges EF Core with Umbraco's existing persistence infrastructure. It provides:

1. UmbracoDbContext - Base DbContext with automatic table prefix (umbraco) and provider-based configuration
2. EF Core Scoping - Integration with Umbraco's Unit of Work pattern (scopes)
3. Distributed Locking - SQL Server and SQLite locking mechanisms for EF Core contexts
4. Migration Infrastructure - Provider-agnostic migration execution

Folder Structure Copy Section

Umbraco.Cms.Persistence.EFCore/
├── Composition/
│   └── UmbracoEFCoreComposer.cs      # DI registration, OpenIddict setup
├── Extensions/
│   ├── DbContextExtensions.cs         # ExecuteScalarAsync, MigrateDatabaseAsync
│   └── UmbracoEFCoreServiceCollectionExtensions.cs  # AddUmbracoDbContext<T>
├── Locking/
│   ├── SqlServerEFCoreDistributedLockingMechanism.cs
│   └── SqliteEFCoreDistributedLockingMechanism.cs
├── Migrations/
│   ├── IMigrationProvider.cs          # Provider-specific migration execution
│   └── IMigrationProviderSetup.cs     # DbContext options setup per provider
├── Scoping/
│   ├── AmbientEFCoreScopeStack.cs     # AsyncLocal scope stack
│   ├── EFCoreScope.cs                 # Main scope implementation
│   ├── EFCoreDetachableScope.cs       # Detachable scope for Deploy
│   ├── EFCoreScopeProvider.cs         # Scope factory
│   ├── EFCoreScopeAccessor.cs         # Ambient scope accessor
│   └── I*.cs                          # Interfaces
├── Constants-ProviderNames.cs         # SQLite/SQLServer provider constants
├── EFCoreMigrationExecutor.cs         # Migration orchestrator
├── StringExtensions.cs                # Provider name comparison
└── UmbracoDbContext.cs                # Base DbContext

Key Design Decisions Copy Section

1. Generic DbContext Support - All scoping/locking is generic (``) allowing custom contexts
2. Parallel NPoco Coexistence - Designed to work alongside existing NPoco persistence layer
3. Provider Abstraction - IMigrationProvider and IMigrationProviderSetup enable database-agnostic migrations
4. OpenIddict Integration - UmbracoDbContext automatically registers OpenIddict entity sets

Database Providers Copy Section

Provider-specific implementations live in separate projects:

• Umbraco.Cms.Persistence.EFCore.SqlServer - SQL Server provider and migrations
• Umbraco.Cms.Persistence.EFCore.Sqlite - SQLite provider and migrations

Provider names (from Constants.ProviderNames):

• Microsoft.Data.SqlClient - SQL Server
• Microsoft.Data.Sqlite - SQLite

2. Commands Copy Chapter

For Git workflow and standard build commands, see repository root.

EF Core Migrations Copy Section

Important: Run from repository root with valid connection string in src/Umbraco.Web.UI/appsettings.json.

# Add migration (SQL Server)
dotnet ef migrations add %MigrationName% -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.SqlServer -c UmbracoDbContext

# Add migration (SQLite)
dotnet ef migrations add %MigrationName% -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.Sqlite -c UmbracoDbContext

# Remove last migration (SQL Server)
dotnet ef migrations remove -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.SqlServer

# Remove last migration (SQLite)
dotnet ef migrations remove -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.Sqlite

# Generate migration script
dotnet ef migrations script -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.SqlServer

3. Key Patterns Copy Chapter

Adding a Custom DbContext Copy Section

Use AddUmbracoDbContext<T> to register with full scope integration:

services.AddUmbracoDbContext<MyCustomDbContext>((provider, options, connectionString, providerName) =>
{
    options.UseOpenIddict(); // Optional
});

Registers: IDbContextFactory<T>, scope providers, accessors, and distributed locking

Using EF Core Scopes Copy Section

using IEFCoreScope<UmbracoDbContext> scope = _scopeProvider.CreateScope();

await scope.ExecuteWithContextAsync<MyEntity>(async dbContext =>
{
    return await dbContext.MyEntities.FirstOrDefaultAsync(x => x.Id == id);
});

scope.Complete(); // Required to commit

UmbracoDbContext Table Naming Copy Section

All tables auto-prefixed with umbraco (see UmbracoDbContext.cs:85-88).

4. Scoping System Copy Chapter

Scope Hierarchy Copy Section

EFCoreScopeProvider<T>
    ├── Creates EFCoreScope<T> (normal scope)
    └── Creates EFCoreDetachableScope<T> (for Deploy scenarios)

EFCoreScope<T>
    ├── Manages DbContext lifecycle
    ├── Handles transactions (BeginTransaction/Commit/Rollback)
    ├── Integrates with parent NPoco IScope when nested
    └── Manages distributed locks via Locks property

Ambient Scope Stack Copy Section

Uses AsyncLocal<ConcurrentStack<T>> for thread-safe tracking. Scopes must be disposed in LIFO order (child before parent).

Transaction Integration Copy Section

When an EF Core scope is created inside an NPoco scope:

1. The EF Core scope reuses the parent's DbTransaction
2. Transaction commit/rollback is delegated to the parent scope
3. DbContext connects to the same connection as the parent

See EFCoreScope.cs:158-180 for transaction initialization logic.

5. Distributed Locking Copy Chapter

SQL Server Locking Copy Section

Table-level locks with REPEATABLEREAD hint. Timeout via SET LOCK_TIMEOUT. Requires ReadCommitted or higher.

SQLite Locking Copy Section

Database-level locking (SQLite limitation). Read locks use snapshot isolation (WAL mode). Write locks are exclusive. Handles SQLITE_BUSY/LOCKED errors.

Lock Requirements Copy Section

Requires active scope, transaction, and minimum ReadCommitted isolation.

6. Migration System Copy Chapter

How Migrations Execute Copy Section

1. UmbracoEFCoreComposer registers EFCoreMigrationExecutor
2. Notification handler triggers on database creation
3. EFCoreMigrationExecutor finds correct IMigrationProvider by provider name
4. Provider executes via dbContext.Database.Migrate()

Adding New Migrations Copy Section

Create equivalent migrations in both SqlServer and Sqlite provider projects using commands from section 2.

7. Project-Specific Notes Copy Chapter

Known Technical Debt Copy Section

Warning Suppressions (.csproj:9-14): IDE0270 (null checks), CS0108 (hiding members), CS1998 (async/await).

Detachable Scope (EFCoreDetachableScope.cs:93-94): TODO for Deploy integration, limited test coverage.

Circular Dependency Handling Copy Section

SqlServerEFCoreDistributedLockingMechanism uses Lazy> to break circular dependency.

StaticServiceProvider Usage Copy Section

Fallback for design-time EF tooling (migrations) and startup edge cases when DI unavailable.

OpenIddict Integration Copy Section

UmbracoEFCoreComposer configures OpenIddict via options.UseOpenIddict() (see Composition/UmbracoEFCoreComposer.cs:22-36).

Vulnerable Dependency Override Copy Section

Top-level dependency on Microsoft.Extensions.Caching.Memory overrides vulnerable EF Core transitive dependency (.csproj:18-19).

InternalsVisibleTo Copy Section

Umbraco.Tests.Integration has access to internal types.

Quick Reference Copy Chapter

Essential Files Copy Section

Key Interfaces Copy Section

Provider Constants Copy Section

Constants.ProviderNames.SQLServer = "Microsoft.Data.SqlClient"
Constants.ProviderNames.SQLLite = "Microsoft.Data.Sqlite"

Related Projects Copy Section

• Umbraco.Cms.Persistence.EFCore.SqlServer - SQL Server implementation
• Umbraco.Cms.Persistence.EFCore.Sqlite - SQLite implementation
• Umbraco.Infrastructure - Contains NPoco scoping that this integrates with

File: src/Umbraco.Cms.Persistence.EFCore.Sqlite/CLAUDE.md Copy Chapter

Umbraco.Cms.Persistence.EFCore.Sqlite

SQLite-specific EF Core provider for Umbraco CMS. Contains SQLite migrations and provider setup for the EF Core persistence layer.

Project Type: Class Library (NuGet package)
Target Framework: net10.0
Dependencies: Umbraco.Cms.Persistence.EFCore

1. Architecture Copy Chapter

Project Purpose Copy Section

This is a thin provider project that implements SQLite-specific functionality for the EF Core persistence layer:

1. Migration Provider - Executes SQLite-specific migrations
2. Migration Provider Setup - Configures DbContext to use SQLite (incl. transient-error retry)
3. Migrations - SQLite-specific migration files for OpenIddict tables
4. Retrying Execution Strategy - Retries transient SQLite lock errors on EF Core operations

Folder Structure Copy Section

Umbraco.Cms.Persistence.EFCore.Sqlite/
├── Migrations/
│   ├── 20230622183638_InitialCreate.cs          # No-op (NPoco creates tables)
│   ├── 20230807123456_AddOpenIddict.cs          # OpenIddict tables
│   ├── 20240403141051_UpdateOpenIddictToV5.cs   # OpenIddict v5 schema
│   ├── 20251006140958_UpdateOpenIddictToV7.cs   # OpenIddict v7 (no-op for SQLite)
│   └── UmbracoDbContextModelSnapshot.cs         # Current model state
├── EFCoreSqliteComposer.cs                       # DI registration
├── SqliteMigrationProvider.cs                    # IMigrationProvider impl
├── SqliteMigrationProviderSetup.cs               # IMigrationProviderSetup impl
└── SqliteRetryingExecutionStrategy.cs            # IExecutionStrategy for transient lock errors

Relationship with Parent Project Copy Section

This project extends Umbraco.Cms.Persistence.EFCore:

• Implements IMigrationProvider interface defined in parent
• Implements IMigrationProviderSetup interface defined in parent
• Uses UmbracoDbContext from parent project
• Provider name: Microsoft.Data.Sqlite (from Constants.ProviderNames.SQLLite)

2. Commands Copy Chapter

For Git workflow and build commands, see repository root.
For EF Core migration commands, see parent project (substitute -p src/Umbraco.Cms.Persistence.EFCore.Sqlite).

3. Key Components Copy Chapter

EFCoreSqliteComposer (line 10-14) Copy Section

Registers IMigrationProvider and IMigrationProviderSetup for SQLite.

SqliteMigrationProvider Copy Section

• MigrateAsync(EFCoreMigration) - Runs specific named migration
• MigrateAllAsync() - Runs all pending migrations
• Critical: Cannot run MigrateAllAsync when transaction is active (line 26-29)

SqliteMigrationProviderSetup (line 11-14) Copy Section

Configures DbContextOptionsBuilder with UseSqlite, the migrations assembly, and the
SqliteRetryingExecutionStrategy (see below). Invoked from
UmbracoDbContext.ConfigureOptions for every UmbracoDbContext instance, so all EF Core
access to the Umbraco database (including OpenIddict's token store) inherits the retry.

SqliteRetryingExecutionStrategy Copy Section

Custom Microsoft.EntityFrameworkCore.Storage.ExecutionStrategy that retries on transient
SQLite errors (SQLITE_BUSY, SQLITE_LOCKED) using SqliteExceptionExtensions.IsBusyOrLocked
from the parent project. Defaults inherit ExecutionStrategy.DefaultMaxRetryCount (6) and
ExecutionStrategy.DefaultMaxDelay (30s), giving a ~56-second retry budget — see the class's
XML doc for the rationale and the unattended-upgrade escape hatch for very long migrations.
Added to resolve issue #22939 (OpenIddict token reads failing during long migrations).

4. Migrations Copy Chapter

Migration History Copy Section

OpenIddict Tables Created Copy Section

All tables prefixed with umbraco:

• umbracoOpenIddictApplications - OAuth client applications
• umbracoOpenIddictAuthorizations - User authorizations
• umbracoOpenIddictScopes - OAuth scopes
• umbracoOpenIddictTokens - Access/refresh tokens

SQLite-Specific Notes Copy Section

• TEXT column type - SQLite uses TEXT for all strings (no varchar)
• InitialCreate is no-op - NPoco creates base tables, EF Core manages OpenIddict only
• v7 migration is no-op - SQLite didn't require schema changes that SQL Server needed

Adding New Migrations Copy Section

1. Configure SQLite connection string in src/Umbraco.Web.UI/appsettings.json
2. Run migration command from repository root (see parent project docs)
3. Critical: Also add equivalent migration to Umbraco.Cms.Persistence.EFCore.SqlServer
4. Update SqliteMigrationProvider.GetMigrationType() switch (line 34-42) if adding named migrations

5. Project-Specific Notes Copy Chapter

Named Migration Mapping Copy Section

SqliteMigrationProvider.GetMigrationType() (line 34-42) maps EFCoreMigration enum to migration types. When adding named migrations, update both the parent project's enum and this switch.

Auto-Generated Files Copy Section

UmbracoDbContextModelSnapshot.cs is regenerated by EF Core - do not edit manually.

Quick Reference Copy Chapter

Essential Files Copy Section

Provider Name Copy Section

Constants.ProviderNames.SQLLite = "Microsoft.Data.Sqlite"

Related Projects Copy Section

• Parent: Umbraco.Cms.Persistence.EFCore - Interfaces and base DbContext
• Sibling: Umbraco.Cms.Persistence.EFCore.SqlServer - SQL Server equivalent

File: src/Umbraco.Cms.Persistence.EFCore.SqlServer/CLAUDE.md Copy Chapter

Umbraco.Cms.Persistence.EFCore.SqlServer

SQL Server-specific EF Core provider for Umbraco CMS. Contains SQL Server migrations and provider setup for the EF Core persistence layer.

Project Type: Class Library (NuGet package)
Target Framework: net10.0
Dependencies: Umbraco.Cms.Persistence.EFCore

1. Architecture Copy Chapter

Project Purpose Copy Section

This is a thin provider project that implements SQL Server-specific functionality for the EF Core persistence layer:

1. Migration Provider - Executes SQL Server-specific migrations
2. Migration Provider Setup - Configures DbContext to use SQL Server
3. Migrations - SQL Server-specific migration files for OpenIddict tables

Folder Structure Copy Section

Umbraco.Cms.Persistence.EFCore.SqlServer/
├── Migrations/
│   ├── 20230622184303_InitialCreate.cs          # No-op (NPoco creates tables)
│   ├── 20230807654321_AddOpenIddict.cs          # OpenIddict tables
│   ├── 20240403140654_UpdateOpenIddictToV5.cs   # OpenIddict v5 schema changes
│   ├── 20251006140751_UpdateOpenIddictToV7.cs   # Token Type column expansion
│   └── UmbracoDbContextModelSnapshot.cs         # Current model state
├── EFCoreSqlServerComposer.cs                   # DI registration
├── SqlServerMigrationProvider.cs                # IMigrationProvider impl
└── SqlServerMigrationProviderSetup.cs           # IMigrationProviderSetup impl

Relationship with Parent Project Copy Section

This project extends Umbraco.Cms.Persistence.EFCore:

• Implements IMigrationProvider interface defined in parent
• Implements IMigrationProviderSetup interface defined in parent
• Uses UmbracoDbContext from parent project
• Provider name: Microsoft.Data.SqlClient (from Constants.ProviderNames.SQLServer)

2. Commands Copy Chapter

For Git workflow and build commands, see repository root.
For EF Core migration commands, see parent project (substitute -p src/Umbraco.Cms.Persistence.EFCore.SqlServer).

3. Key Components Copy Chapter

EFCoreSqlServerComposer (line 10-14) Copy Section

Registers SQL Server implementations of IMigrationProvider and IMigrationProviderSetup.

SqlServerMigrationProvider Copy Section

Executes migrations via MigrateAsync(EFCoreMigration) or MigrateAllAsync(). Unlike SQLite sibling, no transaction check needed (SQL Server handles concurrent migrations natively).

SqlServerMigrationProviderSetup (line 11-14) Copy Section

Configures DbContextOptionsBuilder with UseSqlServer and migrations assembly.

4. Migrations Copy Chapter

Migration History Copy Section

OpenIddict Tables Created Copy Section

Prefixed with umbraco: Applications, Authorizations, Scopes, Tokens (see SQLite sibling for details).

SQL Server-Specific Differences from SQLite Copy Section

1. nvarchar types - Uses nvarchar(n) and nvarchar(max) instead of TEXT
2. v5 migration has actual changes - Column rename and additions (SQLite handled differently)
3. v7 migration has schema change - Token.Type column expanded (SQLite didn't need this)

Adding New Migrations Copy Section

1. Configure SQL Server connection string in src/Umbraco.Web.UI/appsettings.json
2. Run migration command from repository root (see parent project docs)
3. Critical: Also add equivalent migration to Umbraco.Cms.Persistence.EFCore.Sqlite
4. Update SqlServerMigrationProvider.GetMigrationType() switch (line 27-35) if adding named migrations

5. Project-Specific Notes Copy Chapter

Named Migration Mapping Copy Section

SqlServerMigrationProvider.GetMigrationType() (line 27-35) maps EFCoreMigration enum to migration types. Update both parent enum and this switch when adding named migrations.

Transaction Handling Copy Section

SQL Server handles concurrent migrations natively - no transaction check needed (unlike SQLite).

Auto-Generated Files Copy Section

UmbracoDbContextModelSnapshot.cs is regenerated by EF Core - do not edit manually.

Quick Reference Copy Chapter

Essential Files Copy Section

Provider Name Copy Section

Constants.ProviderNames.SQLServer = "Microsoft.Data.SqlClient"

Related Projects Copy Section

• Parent: Umbraco.Cms.Persistence.EFCore - Interfaces and base DbContext
• Sibling: Umbraco.Cms.Persistence.EFCore.Sqlite - SQLite equivalent

File: src/Umbraco.Cms.Persistence.Sqlite/CLAUDE.md Copy Chapter

Umbraco.Cms.Persistence.Sqlite

SQLite database provider for Umbraco CMS using NPoco ORM. Provides SQLite-specific SQL syntax, type mappers, distributed locking, and connection interceptors.

Project Type: Class Library (NuGet package)
Target Framework: net10.0
Dependencies: Umbraco.Infrastructure, Microsoft.Data.Sqlite

Note: This is the legacy NPoco-based SQLite provider. For EF Core SQLite support, see Umbraco.Cms.Persistence.EFCore.Sqlite.

1. Architecture Copy Chapter

Project Purpose Copy Section

This project provides complete SQLite support for Umbraco's NPoco-based persistence layer:

1. SQL Syntax Provider - SQLite-specific SQL generation and schema operations
2. Type Mappers - GUID, decimal, date/time mapping for SQLite's type system
3. Distributed Locking - SQLite-specific locking using WAL mode
4. Connection Interceptors - Deferred transactions, MiniProfiler, retry policies
5. Bulk Insert - SQLite-optimized record insertion

Folder Structure Copy Section

Umbraco.Cms.Persistence.Sqlite/
├── Interceptors/
│   ├── SqliteAddMiniProfilerInterceptor.cs     # MiniProfiler integration
│   ├── SqliteAddPreferDeferredInterceptor.cs   # Deferred transaction wrapper
│   ├── SqliteAddRetryPolicyInterceptor.cs      # Transient error retry
│   └── SqliteConnectionInterceptor.cs          # Base interceptor
├── Mappers/
│   ├── SqliteGuidScalarMapper.cs               # GUID as TEXT mapping
│   ├── SqlitePocoDateAndTimeOnlyMapper.cs      # Date/Time as TEXT
│   ├── SqlitePocoDecimalMapper.cs              # Decimal as TEXT (lossless)
│   └── SqlitePocoGuidMapper.cs                 # GUID for NPoco
├── Services/
│   ├── SqliteBulkSqlInsertProvider.cs          # Bulk insert via transactions
│   ├── SqliteDatabaseCreator.cs                # Database initialization
│   ├── SqliteDatabaseProviderMetadata.cs       # Provider info
│   ├── SqliteDistributedLockingMechanism.cs    # WAL-based locking
│   ├── SqliteExceptionExtensions.cs            # Error code helpers
│   ├── SqlitePreferDeferredTransactionsConnection.cs  # Deferred tx wrapper
│   ├── SqliteSpecificMapperFactory.cs          # Type mapper factory
│   ├── SqliteSyntaxProvider.cs                 # SQL syntax (481 lines)
│   └── SqliteTransientErrorDetectionStrategy.cs # BUSY/LOCKED detection
├── Constants.cs                                 # Provider name constant
├── SqliteComposer.cs                           # DI auto-registration
└── UmbracoBuilderExtensions.cs                 # AddUmbracoSqliteSupport()

Auto-Registration Copy Section

When this assembly is referenced, SqliteComposer automatically registers all SQLite services via the AddUmbracoSqliteSupport() extension method.

2. Commands Copy Chapter

For Git workflow and build commands, see repository root.

3. Key Components Copy Chapter

SqliteSyntaxProvider (Services/SqliteSyntaxProvider.cs) Copy Section

The core SQL syntax provider implementing ISqlSyntaxProvider. Key characteristics:

• All strings stored as TEXT with COLLATE NOCASE (case-insensitive)
• GUIDs stored as TEXT (no native GUID support)
• Decimals stored as TEXT to avoid REAL precision loss (line 51)
• Default isolation level: IsolationLevel.Serializable (line 66-67)
• No identity insert support (line 73)
• No clustered index support (line 76)
• LIMIT instead of TOP for pagination (line 273-278)
• AUTOINCREMENT required to prevent magic ID issues with negative IDs (line 224-228)

SqliteDistributedLockingMechanism (Services/SqliteDistributedLockingMechanism.cs) Copy Section

Database-level locking using SQLite WAL mode:

• Read locks: Snapshot isolation via WAL (mostly no-op, just validates transaction exists)
• Write locks: Only one writer at a time (entire database locked)
• Timeout handling: Uses CommandTimeout for busy-wait (line 163)
• Error handling: Catches SQLITE_BUSY and SQLITE_LOCKED errors

SqlitePreferDeferredTransactionsConnection (Services/SqlitePreferDeferredTransactionsConnection.cs) Copy Section

Wraps SqliteConnection to force deferred transactions:

// Line 33-34: The critical behavior
protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel)
    => _inner.BeginTransaction(isolationLevel, true); // <-- The important bit

This prevents immediate write locks when beginning transactions, allowing multiple readers.

Connection Interceptors Copy Section

• SqliteAddPreferDeferredInterceptor - Wraps connections with deferred transaction support
• SqliteAddMiniProfilerInterceptor - Adds profiling for development
• SqliteAddRetryPolicyInterceptor - Retries on transient SQLite errors

4. SQLite Type Mapping Copy Chapter

SQLite has limited types. Umbraco maps .NET types as follows:

5. Project-Specific Notes Copy Chapter

Database Creation Prevention Copy Section

UmbracoBuilderExtensions.cs (line 49-64) prevents accidental database file creation:

// Changes ReadWriteCreate mode to ReadWrite only
if (connectionStringBuilder.Mode == SqliteOpenMode.ReadWriteCreate)
{
    connectionStringBuilder.Mode = SqliteOpenMode.ReadWrite;
}

This ensures the database must exist before Umbraco connects.

WAL Mode Locking Copy Section

SQLite with WAL (Write-Ahead Logging) journal mode:

• Multiple readers can access snapshots concurrently
• Only one writer at a time (database-level lock)
• Write lock uses umbracoLock table with UPDATE to acquire

Bulk Insert Implementation Copy Section

SqliteBulkSqlInsertProvider (line 38-60) doesn't use true bulk copy (SQLite doesn't support it). Instead:

1. Wraps inserts in a transaction if not already in one
2. Inserts records one-by-one with database.Insert()
3. Completes transaction

This is slower than SQL Server's SqlBulkCopy but safe for SQLite.

Known Technical Debt Copy Section

1. Warning Suppression (.csproj:8-12): CS0114 - hiding inherited members needs fixing
2. TODO in SqliteSyntaxProvider (line 178): TryGetDefaultConstraint not implemented for SQLite

Differences from SQL Server Provider Copy Section

Quick Reference Copy Chapter

Essential Files Copy Section

Provider Name Copy Section

Constants.ProviderName = "Microsoft.Data.Sqlite"

Registered Services Copy Section

All registered via TryAddEnumerable (allowing multiple providers):

• ISqlSyntaxProvider → SqliteSyntaxProvider
• IBulkSqlInsertProvider → SqliteBulkSqlInsertProvider
• IDatabaseCreator → SqliteDatabaseCreator
• IProviderSpecificMapperFactory → SqliteSpecificMapperFactory
• IDatabaseProviderMetadata → SqliteDatabaseProviderMetadata
• IDistributedLockingMechanism → SqliteDistributedLockingMechanism
• IProviderSpecificInterceptor → Three interceptors

Related Projects Copy Section

• Sibling: Umbraco.Cms.Persistence.SqlServer - SQL Server NPoco provider
• EF Core: Umbraco.Cms.Persistence.EFCore.Sqlite - EF Core SQLite provider

File: src/Umbraco.Cms.Persistence.SqlServer/CLAUDE.md Copy Chapter

Umbraco.Cms.Persistence.SqlServer

SQL Server database provider for Umbraco CMS using NPoco ORM. Provides SQL Server-specific SQL syntax, bulk copy operations, distributed locking, and Azure SQL transient fault handling.

Project Type: Class Library (NuGet package)
Target Framework: net10.0
Dependencies: Umbraco.Infrastructure, NPoco.SqlServer, Microsoft.Data.SqlClient

Note: This is the legacy NPoco-based SQL Server provider. For EF Core SQL Server support, see Umbraco.Cms.Persistence.EFCore.SqlServer.

1. Architecture Copy Chapter

Project Purpose Copy Section

This project provides complete SQL Server support for Umbraco's NPoco-based persistence layer:

1. SQL Syntax Provider - SQL Server-specific SQL generation and schema operations
2. Bulk Insert - True SqlBulkCopy for high-performance batch inserts
3. Distributed Locking - Row-level locking with REPEATABLEREAD hints
4. Fault Handling - Azure SQL and network transient error retry policies
5. LocalDB Support - SQL Server LocalDB for development

Folder Structure Copy Section

Umbraco.Cms.Persistence.SqlServer/
├── Dtos/
│   ├── ColumnInSchemaDto.cs              # Schema query results
│   ├── ConstraintPerColumnDto.cs
│   ├── ConstraintPerTableDto.cs
│   ├── DefaultConstraintPerColumnDto.cs
│   └── DefinedIndexDto.cs
├── FaultHandling/
│   ├── RetryPolicyFactory.cs             # Creates retry policies
│   └── Strategies/
│       ├── NetworkConnectivityErrorDetectionStrategy.cs
│       ├── SqlAzureTransientErrorDetectionStrategy.cs  # Azure SQL error codes
│       └── ThrottlingCondition.cs        # Azure throttling decode
├── Interceptors/
│   ├── SqlServerAddMiniProfilerInterceptor.cs
│   ├── SqlServerAddRetryPolicyInterceptor.cs
│   └── SqlServerConnectionInterceptor.cs  # Base interceptor
├── Services/
│   ├── BulkDataReader.cs                 # Base bulk reader
│   ├── MicrosoftSqlSyntaxProviderBase.cs # Shared SQL syntax
│   ├── PocoDataDataReader.cs             # NPoco bulk reader
│   ├── SqlServerBulkSqlInsertProvider.cs # SqlBulkCopy wrapper
│   ├── SqlServerDatabaseCreator.cs
│   ├── SqlServerDistributedLockingMechanism.cs
│   ├── SqlServerSpecificMapperFactory.cs
│   ├── SqlServerSyntaxProvider.cs        # Main syntax provider
│   ├── SqlAzureDatabaseProviderMetadata.cs
│   ├── SqlLocalDbDatabaseProviderMetadata.cs
│   └── SqlServerDatabaseProviderMetadata.cs
├── Constants.cs                          # Provider name
├── LocalDb.cs                            # LocalDB management (~1,100 lines)
├── NPocoSqlServerDatabaseExtensions.cs   # NPoco bulk extensions config
├── SqlServerComposer.cs                  # DI auto-registration
└── UmbracoBuilderExtensions.cs           # AddUmbracoSqlServerSupport()

Auto-Registration Copy Section

When this assembly is referenced, SqlServerComposer automatically registers all SQL Server services via AddUmbracoSqlServerSupport().

Provider Name Migration Copy Section

Auto-migrates legacy System.Data.SqlClient to Microsoft.Data.SqlClient:

Line 53-59: UmbracoBuilderExtensions.cs updates connection string provider name

if (options.ProviderName == "System.Data.SqlClient")
{
    options.ProviderName = Constants.ProviderName; // Microsoft.Data.SqlClient
}

2. Commands Copy Chapter

For Git workflow and build commands, see repository root.

3. Key Components Copy Chapter

SqlServerDistributedLockingMechanism (Services/SqlServerDistributedLockingMechanism.cs) Copy Section

Row-level locking using REPEATABLEREAD table hints:

• Read locks (line 147): SELECT value FROM umbracoLock WITH (REPEATABLEREAD) WHERE id=@id
• Write locks (line 182-183): UPDATE umbracoLock WITH (REPEATABLEREAD) SET value = ... WHERE id=@id
• Timeout: Uses SET LOCK_TIMEOUT {milliseconds} (lines 149, 185)
• Error handling: Catches SQL error 1222 (lock timeout) → throws DistributedReadLockTimeoutException or DistributedWriteLockTimeoutException
• Minimum isolation: Requires ReadCommitted or higher (lines 141-145, 176-180)

SqlServerBulkSqlInsertProvider (Services/SqlServerBulkSqlInsertProvider.cs) Copy Section

True bulk insert using SqlBulkCopy:

// Line 61-68: SqlBulkCopy configuration
new SqlBulkCopy(tConnection, SqlBulkCopyOptions.Default, tTransaction)
{
    BulkCopyTimeout = 0,           // No timeout (uses connection timeout)
    DestinationTableName = tableName,
    BatchSize = 4096,              // Consistent with NPoco
}

Key features:

• Streams data via PocoDataDataReader<T> (line 69) - avoids in-memory DataTable
• Explicit column mappings by name (lines 74-77) - prevents column order mismatches
• Returns actual count inserted (line 80) - NPoco's InsertBulk doesn't provide this

SqlAzureTransientErrorDetectionStrategy (FaultHandling/Strategies/) Copy Section

Detects transient Azure SQL errors for retry:

SqlServerSyntaxProvider (Services/SqlServerSyntaxProvider.cs) Copy Section

SQL Server version detection and syntax generation:

• Engine editions: Desktop, Standard, Enterprise, Express, Azure (lines 23-31)
• SQL Server versions: V7 through V2019, plus Azure (lines 33-47)
• Default isolation: ReadCommitted (line 69)
• Azure detection: ServerVersion?.IsAzure determines DbProvider (line 67)
• Version detection: Populated via GetDbProviderManifest() by querying SQL Server metadata

4. LocalDB Support Copy Chapter

LocalDb.cs (~1,100 lines) provides comprehensive SQL Server LocalDB management:

• Database creation/deletion
• Instance management
• File path handling
• Connection string generation

Known issues (from TODO comments):

• Line 358: Stale database handling not implemented
• Line 359: File name assumptions may not always be correct

5. Differences from SQLite Provider Copy Chapter

6. Project-Specific Notes Copy Chapter

InternalsVisibleTo Copy Section

Test projects have access to internal types:

<InternalsVisibleTo>Umbraco.Tests.Integration</InternalsVisibleTo>
<InternalsVisibleTo>Umbraco.Tests.UnitTests</InternalsVisibleTo>

Known Technical Debt Copy Section

1. Warning Suppressions (.csproj:8-22): Multiple analyzer warnings suppressed

   • StyleCop: SA1405, SA1121, SA1117
   • IDE: 1006 (naming), 0270/0057/0054/0048 (simplification)
   • CS0618 (obsolete usage), CS1574 (XML comments)

2. BulkInsert TODO (SqlServerBulkSqlInsertProvider.cs:44-46): Custom SqlBulkCopy implementation used because NPoco's InsertBulk doesn't return record count. Performance comparison vs NPoco's DataTable approach pending.

3. LocalDB TODOs (LocalDb.cs:358-359): Stale database cleanup and file name assumption handling incomplete.

NPoco Bulk Extensions Copy Section

NPocoSqlServerDatabaseExtensions.ConfigureNPocoBulkExtensions() is called during registration (line 50) to configure NPoco's SQL Server bulk operations.

Three Provider Metadata Types Copy Section

Different metadata for different SQL Server variants:

• SqlServerDatabaseProviderMetadata - Standard SQL Server
• SqlLocalDbDatabaseProviderMetadata - LocalDB
• SqlAzureDatabaseProviderMetadata - Azure SQL

Quick Reference Copy Chapter

Essential Files Copy Section

Provider Name Copy Section

Constants.ProviderName = "Microsoft.Data.SqlClient"

Registered Services Copy Section

All registered via TryAddEnumerable:

• ISqlSyntaxProvider → SqlServerSyntaxProvider
• IBulkSqlInsertProvider → SqlServerBulkSqlInsertProvider
• IDatabaseCreator → SqlServerDatabaseCreator
• IProviderSpecificMapperFactory → SqlServerSpecificMapperFactory
• IDatabaseProviderMetadata → Three variants (SqlServer, LocalDb, Azure)
• IDistributedLockingMechanism → SqlServerDistributedLockingMechanism
• IProviderSpecificInterceptor → MiniProfiler and RetryPolicy interceptors

Related Projects Copy Section

• Sibling: Umbraco.Cms.Persistence.Sqlite - SQLite NPoco provider
• EF Core: Umbraco.Cms.Persistence.EFCore.SqlServer - EF Core SQL Server provider

File: src/Umbraco.Cms.StaticAssets/CLAUDE.md Copy Chapter

Umbraco.Cms.StaticAssets

Static assets and Razor views for Umbraco CMS. This is a Razor Class Library (RCL) that packages all backoffice, login, and website assets for deployment.

Project Type: Razor Class Library (NuGet package)
Target Framework: net10.0
SDK: Microsoft.NET.Sdk.Razor

1. Architecture Copy Chapter

Project Purpose Copy Section

This project packages all static assets required for Umbraco CMS at runtime:

1. Razor Views - Server-rendered pages for backoffice, login, and error pages
2. Static Web Assets - JavaScript, CSS, fonts, images served at runtime
3. Build Integration - MSBuild targets that compile TypeScript/frontend projects on demand

Key Characteristic Copy Section

No C# Source Code - This is a pure asset packaging project. All functionality comes from referenced projects (Umbraco.Cms.Api.Management, Umbraco.Web.Website).

Folder Structure Copy Section

Umbraco.Cms.StaticAssets/
├── umbraco/                                # Razor Views (server-rendered)
│   ├── UmbracoBackOffice/
│   │   └── Index.cshtml                    # Backoffice SPA shell
│   ├── UmbracoLogin/
│   │   └── Index.cshtml                    # Login page
│   └── UmbracoWebsite/
│       ├── NoNodes.cshtml                  # "No published content" page
│       ├── NotFound.cshtml                 # 404 error page
│       └── Maintenance.cshtml              # Maintenance mode page
│
├── wwwroot/                                # Static Web Assets
│   ├── App_Plugins/
│   │   └── Umbraco.BlockGridEditor.DefaultCustomViews/  # Block grid demo templates
│   └── umbraco/
│       ├── assets/                         # Logos and branding (see README.md)
│       ├── backoffice/                     # Built backoffice SPA (from Umbraco.Web.UI.Client)
│       │   ├── apps/                       # Application modules
│       │   ├── assets/                     # Fonts, language files
│       │   ├── css/                        # Themes and stylesheets
│       │   └── monaco-editor/              # Code editor assets
│       ├── login/                          # Built login SPA (from Umbraco.Web.UI.Login)
│       └── website/                        # Frontend website assets (fonts, CSS)
│
└── Umbraco.Cms.StaticAssets.csproj         # Build configuration

Project Dependencies Copy Section

<ProjectReference Include="..\Umbraco.Cms.Api.Management\Umbraco.Cms.Api.Management.csproj" />
<ProjectReference Include="..\Umbraco.Web.Website\Umbraco.Web.Website.csproj" />

2. Commands Copy Chapter

For Git workflow and build commands, see repository root.

3. Key Components Copy Chapter

Razor Views Copy Section

Backoffice Index View (umbraco/UmbracoBackOffice/Index.cshtml) Copy Section

Key injected services:

• IBackOfficePathGenerator - Generates backoffice URL paths
• IPackageManifestService - Package manifest discovery
• IJsonSerializer - JSON serialization for import maps
• IProfilerHtml - MiniProfiler integration

Key features:

• Import Maps (line 35): Html.BackOfficeImportMapScriptAsync() generates JavaScript module import maps
• Debug Mode (line 16, 63-66): ?umbDebug=true query param enables profiler
• NoScript Fallback (lines 40-60): Displays message if JavaScript disabled

Login View (umbraco/UmbracoLogin/Index.cshtml) Copy Section

Configures `` web component with attributes:

• return-url - Redirect after login
• logo-image / background-image - Branding URLs from BackOfficeGraphicsController
• username-is-email - From SecuritySettings
• allow-user-invite / allow-password-reset - Email capability check
• disable-local-login - External login provider configuration

4. Build System Copy Chapter

Frontend Build Integration (csproj lines 36-90) Copy Section

The .csproj contains MSBuild targets that automatically build frontend projects when assets are missing.

Backoffice Build (lines 36-90):

BackofficeProjectDirectory = ../Umbraco.Web.UI.Client/
BackofficeAssetsPath = wwwroot/umbraco/backoffice

Login Build (lines 102-148):

LoginProjectDirectory = ../Umbraco.Web.UI.Login/
LoginAssetsPath = wwwroot/umbraco/login

Build Targets Copy Section

Build Conditions Copy Section

• UmbracoBuild Variable: When set (CI/CD), skips frontend builds (pre-built assets expected)
• Visual Studio Detection: '$(UmbracoBuild)' == '' indicates VS build
• preserve.backoffice Marker: Skip clean if preserve.backoffice file exists in solution root

5. Static Web Assets Copy Chapter

Asset Categories Copy Section

Logo Assets (wwwroot/umbraco/assets/) Copy Section

Documented in wwwroot/umbraco/assets/README.md (16 lines):

Block Grid Demo Views (wwwroot/App_Plugins/Umbraco.BlockGridEditor.DefaultCustomViews/) Copy Section

Pre-built AngularJS templates for block grid editor demos:

• umbBlockGridDemoHeadlineBlock.html
• umbBlockGridDemoImageBlock.html
• umbBlockGridDemoRichTextBlock.html
• umbBlockGridDemoTwoColumnLayoutBlock.html

6. Project-Specific Notes Copy Chapter

Static Web Asset Base Path Copy Section

<StaticWebAssetBasePath>/</StaticWebAssetBasePath>

Assets are served from root path, not under assembly name.

Compression Disabled Copy Section

<CompressionEnabled>false</CompressionEnabled>

Comment notes MapStaticAssets() is not used (yet).

Known Technical Debt Copy Section

1. Warning Suppression (.csproj:14-16): NU5123 - File paths too long for NuGet package. TODO indicates files should be renamed.

2. Excluded Content (.csproj:31): wwwroot/umbraco/assets/README.md explicitly excluded from package.

Backoffice Localization Copy Section

The backoffice includes language files for 25+ languages in wwwroot/umbraco/backoffice/assets/lang/:

• ar, bs, cs, cy, da, de, en, en-us, es, fr, he, hr, it, ja, ko, nb, nl, pl, pt, pt-br, ro, ru, sv, tr, uk, zh, zh-tw

Monaco Editor Copy Section

Full Monaco code editor included at wwwroot/umbraco/backoffice/monaco-editor/ for rich code editing in backoffice.

Theming Copy Section

CSS themes in wwwroot/umbraco/backoffice/css/:

• umb-css.css - Main styles
• light.css - UI library styles default styles (Light theme)
• dark.css - UUI Dark theme
• high-contrast.css - UUI Accessibility theme
• umbraco-blockgridlayout.css - Block grid styles
• rte-content.css - Rich text editor content styles

The UUI theme files (light.css, dark.css, high-contrast.css) are copied from @umbraco-ui/uui during the backoffice build; see Umbraco.Web.UI.Client/src/packages/core/themes/manifests.ts.

Quick Reference Copy Chapter

Essential Files Copy Section

Related Projects Copy Section

Build Commands (Manual) Copy Section

# Build backoffice assets (from Umbraco.Web.UI.Client)
cd src/Umbraco.Web.UI.Client
npm install
npm run build:for:cms

# Build login assets (from Umbraco.Web.UI.Login)
cd src/Umbraco.Web.UI.Login
npm install
npm run build

Preserve Assets During Clean Copy Section

Create marker file to prevent asset deletion:

touch preserve.backoffice  # In solution root
touch preserve.login       # In solution root

File: src/Umbraco.Cms.StaticAssets/wwwroot/umbraco/assets/README.md Copy Chapter

Umbraco static assets

The files in this directory are static assets that are used by the Umbraco backoffice, installer, public-facing sites, and login screen. These files are served by the Umbraco backend and are not intended to be used by the front-end of your website.

Structure Copy Chapter

The assets are structured in the following way:

All assets are linked up through the BackOfficeGraphicsController which uses the constants defined in ContentSettings.

File: src/Umbraco.Core/CLAUDE.md Copy Chapter

Umbraco.Core Project Guide

Project Overview Copy Chapter

Umbraco.Core is the foundational layer of Umbraco CMS, containing the core domain models, services interfaces, events/notifications system, and essential abstractions. This project has NO database implementation and minimal external dependencies - it focuses on defining contracts and business logic.

Package ID: Umbraco.Cms.Core
Namespace: Umbraco.Cms.Core

What Lives Here vs. Other Projects Copy Section

• Umbraco.Core: Interfaces, models, notifications, service contracts, core business logic, configuration models
• Umbraco.Infrastructure: Concrete implementations (repositories, database access, file systems, concrete services)
• Umbraco.Web.Common: Web-specific functionality (controllers, middleware, routing)
• Umbraco.Cms.Api.Common: API endpoints and DTOs

Key Directory Structure Copy Chapter

Core Domain Areas Copy Section

/Models                     - Domain models and DTOs
├── /Entities              - Base entity interfaces (IEntity, IUmbracoEntity, ITreeEntity)
├── /ContentEditing        - Content editing models and DTOs
├── /ContentPublishing     - Publishing-related models
├── /Membership            - User, member, and group models
├── /PublishedContent      - Published content abstractions
├── /DeliveryApi          - Delivery API models
└── /Blocks               - Block List/Grid models

/Services                   - Service interfaces (~237 files!)
├── /OperationStatus       - Enums for service operation results (48 status types)
├── /ContentTypeEditing    - Content type editing services
├── /Navigation            - Navigation services
└── /ImportExport          - Import/export services

/Notifications              - Event notification system (100+ notification types)
/Events                     - Event infrastructure and handlers

Infrastructure & Patterns Copy Section

/Composing                  - Composer pattern for DI registration
/DependencyInjection        - IUmbracoBuilder and DI extensions
/Scoping                    - Unit of work pattern (ICoreScopeProvider)
/Cache                      - Caching abstractions and refreshers
├── /Refreshers            - Cache invalidation for distributed systems
└── /NotificationHandlers  - Cache invalidation via notifications

/PropertyEditors            - Property editor abstractions
├── /ValueConverters       - Convert stored values to typed values
├── /Validation            - Property validation infrastructure
└── /DeliveryApi          - Delivery API property converters

/Persistence                - Repository interfaces (no implementations!)
├── /Repositories          - Repository contracts
└── /Querying              - Query abstractions

Supporting Functionality Copy Section

/Configuration              - Configuration models and settings
├── /Models                - Strongly-typed settings (50+ configuration classes)
└── /UmbracoSettings       - Legacy Umbraco settings

/Extensions                 - Extension methods (100+ extension files)
/Mapping                    - Object mapping abstractions (IUmbracoMapper)
/Serialization              - JSON serialization configuration
/Security                   - Security abstractions and authorization
/Routing                    - URL routing abstractions
/Templates                  - Template/view abstractions
/Webhooks                   - Webhook event system
/HealthChecks               - Health check abstractions
/Telemetry                  - Telemetry/analytics
/Install & /Installer       - Installation infrastructure

Core Patterns and Conventions Copy Chapter

1. Service Layer Pattern Copy Section

Services follow a consistent structure:

// Interface defines contract (in Umbraco.Core)
public interface IContentService
{
    IContent? GetById(Guid key);
    Task<Attempt<IContent?, ContentEditingOperationStatus>> CreateAsync(...);
}

// Implementation lives in Umbraco.Core/Services/ (see root CLAUDE.md §5)
// Service operations return Attempt<T, TStatus> for typed results

Key conventions:

• Interfaces in Umbraco.Core; most service implementations live in Umbraco.Core/Services/ too, moving to Umbraco.Infrastructure only when a concrete dependency requires it (see root CLAUDE.md §5)
• Use Attempt for operations that can fail with specific reasons
• OperationStatus enums provide detailed failure reasons
• Services are registered via DI in builder extensions

2. Notification System (Event Handling) Copy Section

Umbraco uses a notification pattern instead of traditional events:

// 1. Define notification (implements INotification)
public class ContentSavedNotification : INotification
{
    public IEnumerable<IContent> SavedEntities { get; }
}

// 2. Create handler
public class MyNotificationHandler : INotificationHandler<ContentSavedNotification>
{
    public void Handle(ContentSavedNotification notification)
    {
        // React to content being saved
    }
}

// 3. Add to appropriate builder extensions
builder.AddNotificationHandler<ContentSavedNotification, MyNotificationHandler>();

Notification types:

• *SavingNotification - Before save (cancellable via ICancelableNotification)
• *SavedNotification - After save
• *DeletingNotification / *DeletedNotification
• *MovingNotification / *MovedNotification

Key interface: IEventAggregator - publishes notifications to handlers

Durable handlers vs. distributed-cache-only publishers

A handler that only implements INotificationHandler<T> / INotificationAsyncHandler<T>
is silently skipped when the notification is dispatched through a publisher restricted to
distributed-cache handlers — i.e. ScopedNotificationPublisher.
Umbraco Deploy installs exactly such a publisher on its restore/import scopes, and EventAggregator
filters handlers with .Where(x => x is TNotificationHandler).

If a handler must run for every change — especially durable database writes that back the
in-memory cache — implement IDistributedCacheNotificationHandler (sync) or
IDistributedCacheAsyncNotificationHandler<T> (async) instead. These derive from the plain handler
interfaces, so the handler still fires on normal publishes and survives the distributed-cache-only
filter. No DI change is needed — filtering is by resolved instance type.

When you do this, ensure the handler is safe in the extra scopes it now runs in. Do not gate a write that
follows a local content commit on server role: the elected Subscriber role can be held by any instance,
including one serving the backoffice (see DocumentUrlService.SkipDatabaseWrites() for the split).

3. Composer Pattern (DI Registration) Copy Section

Composers register services and configure the application, this is to make the system easily extendible by package developers and implementors.
Internally we only use this for temporary service registration for use in short lived code, for example migrations:

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        // Register services
        builder.Services.AddSingleton<IMyService, MyService>();

        // Add to collections
        builder.PropertyEditors().Add<MyPropertyEditor>();

        // Register notification handlers
        builder.AddNotificationHandler<ContentSavedNotification, MyHandler>();
    }
}

Composer ordering:

• [ComposeBefore(typeof(OtherComposer))]
• [ComposeAfter(typeof(OtherComposer))]
• [Weight(100)] - lower runs first

4. Entity and Content Model Hierarchy Copy Section

IEntity                     - Base: Id, Key, CreateDate, UpdateDate
  └─ IUmbracoEntity        - Adds: Name, CreatorId, ParentId, Path, Level, SortOrder
      └─ ITreeEntity       - Tree structure support
          └─ IContentBase  - Adds: Properties, ContentType, CultureInfos
              ├─ IContent  - Documents (publishable)
              ├─ IMedia    - Media items
              └─ IMember   - Members

Key interfaces:

• IContentBase - Common base for all content items (properties, cultures)
• IContent - Documents with publishing workflow
• IContentType, IMediaType, IMemberType - Define structure
• IProperty - Individual property on content
• IPropertyType - Property definition on content type

5. Scoping Pattern (Unit of Work) Copy Section

public class MyService
{
    private readonly ICoreScopeProvider _scopeProvider;

    public void DoWork()
    {
        using ICoreScope scope = _scopeProvider.CreateCoreScope();

        // Do database work
        // Access repositories

        scope.Complete(); // Commit transaction
    }
}

Key points:

• Scopes manage transactions and cache lifetime
• Must call scope.Complete() to commit
• Scopes can be nested (innermost controls transaction)
• RepositoryCacheMode controls caching behavior

6. Property Editors Copy Section

Property editors define how data is edited and stored:

public class MyPropertyEditor : IDataEditor
{
    public string Alias => "My.PropertyEditor";

    public IDataValueEditor GetValueEditor()
    {
        return new MyDataValueEditor();
    }

    public IConfigurationEditor GetConfigurationEditor()
    {
        return new MyConfigurationEditor();
    }
}

Key interfaces:

• IDataEditor - Property editor registration
• IDataValueEditor - Value editing and conversion
• IPropertyIndexValueFactory - Search indexing
• IPropertyValueConverter - Convert stored values to typed values

7. Cache Refreshers (Distributed Cache) Copy Section

For multi-server deployments, cache refreshers synchronize cache:

public class MyEntityCacheRefresher : CacheRefresherBase<MyEntityCacheRefresher>
{
    public override Guid RefresherUniqueId => new Guid("...");
    public override string Name => "My Entity Cache Refresher";

    public override void RefreshAll()
    {
        // Clear all cache
    }

    public override void Refresh(int id)
    {
        // Clear cache for specific entity
    }
}

Important Base Classes and Interfaces Copy Chapter

Must-Know Abstractions Copy Section

Service Layer

• IContentService - Content CRUD operations
• IContentTypeService - Content type management
• IMediaService - Media operations
• IDataTypeService - Data type configuration
• IUserService - User management
• ILanguageService - Languages
• IDictionaryItemService - Dictionary items
• IRelationService - Entity relationships

Content Models

• IContent / IContentBase - Document entities
• IContentType - Document type definition
• IProperty / IPropertyType - Property definitions
• IPublishedContent - Read-only published content

Infrastructure

• ICoreScopeProvider - Unit of work / transactions
• IEventAggregator - Notification publishing
• IUmbracoMapper - Object mapping
• IComposer / IUmbracoBuilder - DI registration

Entity Base Classes

• EntityBase - Basic entity with Id, Key, dates
• TreeEntityBase - Adds Name, hierarchy
• BeingDirty / ICanBeDirty - Change tracking

Key Files and Constants Copy Chapter

Essential Files Copy Section

1. Constants.cs (and 40 Constants-*.cs files)

   • Constants.System.* - System-level constants
   • Constants.Security.* - Security and authorization
   • Constants.Conventions.* - Naming conventions
   • Constants.PropertyEditors.* - Built-in property editor aliases
   • Constants.ObjectTypes.* - Entity type GUIDs
   • Use these instead of magic strings!

2. Udi.cs / GuidUdi.cs / StringUdi.cs

   • Umbraco Identifiers (like URIs): umb://document/{guid}
   • Used throughout for entity references
   • UdiParser.Parse("umb://document/...") to parse

3. Attempt.cs and Attempt.cs

   • Result pattern for operations that can fail
   • Attempt.Succeed(value) / Attempt.Fail<T>()
   • Attempt<Content, ContentEditingOperationStatus> - typed result with status

Writing or reviewing a query with a WHERE IN on a runtime-sized collection? See "Avoiding the SQL Server 2100-parameter limit" in /src/Umbraco.Infrastructure/CLAUDE.md — that's where the full helper list (Constants.Sql.MaxParameterCount, InGroupsOf, NPoco's FetchByGroups) and the decision rules live.

Configuration Copy Section

Configuration models in /Configuration/Models:

• ContentSettings - Content-related settings
• GlobalSettings - Global Umbraco settings
• SecuritySettings - Security configuration
• DeliveryApiSettings - Delivery API configuration
• Access via IOptionsMonitor<TSettings>

Only top-level settings are bound as options. A settings class is bound to configuration only when it has an explicit AddUmbracoOptions<T>() registration in UmbracoBuilder.Configuration.cs (the [UmbracoOptions] attribute alone does nothing — nothing scans for it). A nested settings class exposed as a property of another settings class (e.g. ContentSettings.Imaging, SecuritySettings.UserPassword) is populated as part of binding its parent — it is not independently bound. Do not inject a nested settings type directly as IOptions<TNested>/IOptionsSnapshot<TNested>: with no registration the options system silently hands back a default-constructed instance and all user configuration is ignored. Instead inject the parent and read the nested property (_contentSettings.Imaging). The UserPassword/MemberPassword settings that are separately registered are a legacy exception slated for removal (see the TODO (V18) in UmbracoBuilder.Configuration.cs); don't copy that pattern for new nested settings.

Dependencies Copy Chapter

What Umbraco.Core Depends On Copy Section

• Microsoft.Extensions.* - DI, Configuration, Logging, Caching, Options
• Microsoft.Extensions.Identity.Core - Identity infrastructure
• NO database dependencies
• NO web dependencies

What Depends on Umbraco.Core Copy Section

• Umbraco.Infrastructure - Implements all Core interfaces
• Umbraco.PublishedCache.HybridCache - Published content caching
• Umbraco.Cms.Persistence.EFCore - EF Core persistence
• Umbraco.Cms.Api.Common - API infrastructure
• All higher-level Umbraco projects

Common Development Tasks Copy Chapter

1. Creating a New Service Copy Section

// 1. Define interface in Umbraco.Core/Services/IMyService.cs
public interface IMyService
{
    Task<Attempt<MyResult, MyOperationStatus>> CreateAsync(...);
}

// 2. Define operation status in Services/OperationStatus/
public enum MyOperationStatus
{
    Success,
    NotFound,
    ValidationFailed
}

// 3. Implement in Umbraco.Core/Services/ (or Umbraco.Infrastructure if it needs Infrastructure concerns)
// 4. Register in a Composer
builder.Services.AddScoped<IMyService, MyService>();

2. Adding a Notification Handler Copy Section

// 1. Identify notification (e.g., ContentSavingNotification)
// 2. Create handler
public class MyContentHandler : INotificationHandler<ContentSavingNotification>
{
    public void Handle(ContentSavingNotification notification)
    {
        foreach (var content in notification.SavedEntities)
        {
            // Validate, modify, or react
        }

        // Cancel if needed (for cancellable notifications)
        // notification.Cancel = true;
    }
}

// 3. Register in Composer
builder.AddNotificationHandler<ContentSavingNotification, MyContentHandler>();

3. Creating a Property Editor Copy Section

// 1. Define in Umbraco.Core/PropertyEditors/
[DataEditor("My.Alias", "My Editor", "view")]
public class MyPropertyEditor : DataEditor
{
    public MyPropertyEditor(IDataValueEditorFactory dataValueEditorFactory)
        : base(dataValueEditorFactory)
    { }

    protected override IDataValueEditor CreateValueEditor()
    {
        return DataValueEditorFactory.Create<MyValueEditor>(Attribute!);
    }
}

// 2. Register in Composer
builder.PropertyEditors().Add<MyPropertyEditor>();

4. Working with Content Copy Section

public class MyService
{
    private readonly IContentService _contentService;
    private readonly ICoreScopeProvider _scopeProvider;

    public async Task UpdateContentAsync(Guid key)
    {
        using var scope = _scopeProvider.CreateCoreScope();

        IContent? content = _contentService.GetById(key);
        if (content == null)
            return;

        // Modify content
        content.SetValue("propertyAlias", "new value");

        // Save (triggers notifications)
        var result = _contentService.Save(content);

        scope.Complete();
    }
}

5. Extending Content Types Copy Section

public class ContentTypeCustomizationComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddNotificationHandler<ContentTypeSavedNotification, MyHandler>();
    }
}

public class MyHandler : INotificationHandler<ContentTypeSavedNotification>
{
    public void Handle(ContentTypeSavedNotification notification)
    {
        foreach (var contentType in notification.SavedEntities)
        {
            // React to content type changes
        }
    }
}

6. Defining Configuration Copy Section

// 1. Create settings class in Configuration/Models/
public class MySettings
{
    public string ApiKey { get; set; } = string.Empty;
    public int MaxItems { get; set; } = 10;
}

// 2. Bind in Composer
builder.Services.Configure<MySettings>(
    builder.Config.GetSection("Umbraco:MySettings"));

// 3. Inject via IOptionsMonitor<MySettings>

Testing Considerations Copy Chapter

The project has InternalsVisibleTo attributes for:

• Umbraco.Tests
• Umbraco.Tests.Common
• Umbraco.Tests.UnitTests
• Umbraco.Tests.Integration
• Umbraco.Tests.Benchmarks

Internal types are accessible in test projects for more thorough testing.

Architecture Principles Copy Chapter

1. Separation of Concerns: Core defines contracts, Infrastructure implements them
2. Interface-First: Always define interfaces before implementations
3. Notification Pattern: Use notifications instead of events for extensibility
4. Attempt Pattern: Return typed results with operation status
5. Composer Pattern: Use composers for DI registration and configuration
6. Scoping: Use scopes for unit of work and transaction management
7. No Direct Database Access: Core has no repositories implementations
8. Culture Variance: Full support for multi-language content
9. Extensibility: Everything is designed to be extended or replaced

Common Gotchas Copy Chapter

1. Don't implement repositories in Core - They belong in Infrastructure
2. Always use scopes - Database operations require a scope
3. Complete scopes - Forgot scope.Complete()? Changes won't save
4. Notification timing - *Saving notifications are cancellable, *Saved are not
5. Service locator - Don't use IServiceProvider directly, use DI
6. Culture handling - Many operations require explicit culture parameter
7. Published vs Draft - IContent is draft, IPublishedContent is published
8. Constants - Use constants instead of magic strings (property editor aliases, etc.)
9. Distributed-cache-only publishers skip plain handlers - handlers doing durable work (e.g. DB writes) must implement IDistributedCacheNotificationHandler / IDistributedCacheAsyncNotificationHandler<T>, or they won't fire under Umbraco Deploy and similar restricted scopes.
10. Outbound HTTP - new code injects IHttpClientFactory and uses a named client from AddHttpClients(); SharedHttpClient is only a shim for call sites that can't take that dependency without a breaking change. Never publish an HttpClient before configuring it, or mutate a shared one's DefaultRequestHeaders after first use - HttpHeaders isn't thread safe.