Service registration: Allow running Umbraco with different combinations of backoffice, website and delivery API (closes #21622)

[AndyButland]

Description

This PR addresses the issue raised #21622 where it's not possible to configure Umbraco to run without a backoffice (which could be useful if you want a differently configured build running on front-end servers, to lower any potential attack service or unnecessary processing).

I've checked various combinations of backoffice, website and delivery API setups and adjusted service registrations such that they can be supported.

Change Summary

• Added new AddCore() extension method as an alternative entry point to AddBackOffice() for delivery-only scenarios.
• AddBackOffice() now calls AddCore() internally, then adds backoffice-specific services.
• Introduces IBackOfficeEnabledMarker interface to conditionally register Management API services.
• Adds integration tests for all supported configuration scenarios.

Supported Scenarios

// Full Umbraco with backoffice (default)
builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseBackOffice();
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
    });

// Delivery-only (no backoffice)
builder.CreateUmbracoBuilder()
    .AddCore()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseWebsiteEndpoints();
        u.UseDeliveryApiEndpoints();
    });

// Website only
builder.CreateUmbracoBuilder()
    .AddCore()
    .AddWebsite()
    .AddComposers()
    .Build();

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseWebsiteEndpoints();
    });

// Delivery API only
builder.CreateUmbracoBuilder()
    .AddCore()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        // No middleware needed for Delivery API only
    })
    .WithEndpoints(u =>
    {
        u.UseDeliveryApiEndpoints();
    });

Key Changes

File	Change
IBackOfficeEnabledMarker.cs	New marker interface for conditional backoffice registration
UmbracoBuilderExtensions.cs (Web.Common)	New AddCore() method with idempotency
UmbracoBuilder.BackOffice.cs	Refactored to call AddCore() internally
ManagementApiComposer.cs	Conditional registration based on marker
ControllersAsServicesComposer.cs	Skip Management API controllers when backoffice disabled
NoopLocalLoginSettingProvider.cs	Fallback for when backoffice identity not configured
NoopConflictingRouteService.cs	Fallback for when backoffice not configured
CoreConfigurationTests.cs	DI-level tests for service registration
CoreConfigurationHttpTests.cs	HTTP boot tests with ValidateOnBuild=true

Testing

• All existing tests pass
• New integration tests verify all 4 supported scenarios boot successfully
• Tests verified to fail when configuration is broken (reversion test)
• ValidateOnBuild=true catches missing dependencies at startup
• Manual testing of scenarios
  • All components - backoffice, website and delivery API should function
  • Backoffice only - backoffice should function, website and delivery API should be unavailable
  • Website only - website should function, backoffice and delivery API should be unavailable
  • Delivery API only - delivery API should function, backoffice and website should be unavailable
  • Combinations of any two services should function

[Copilot]

Pull request overview

Enables “delivery-only” Umbraco setups by introducing a core-only DI entry point and conditioning backoffice/Management API registration on an explicit backoffice marker.

Changes:

• Add new AddCore() builder extension to register core services without the backoffice, and refactor AddBackOffice() to build on top of AddCore().
• Introduce IBackOfficeEnabledMarker and use it to conditionally wire Management API services/controllers and backoffice-specific middleware behavior.
• Add new integration tests covering DI build and HTTP boot across supported configuration combinations.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Umbraco.Tests.Integration/TestServerTest/CoreConfigurationTests.cs	Adds DI-container-level integration tests for supported builder combinations and idempotency.
tests/Umbraco.Tests.Integration/TestServerTest/CoreConfigurationHttpTests.cs	Adds HTTP boot tests for supported configurations with ValidateOnBuild=true.
src/Umbraco.Web.Website/DependencyInjection/UmbracoBuilderExtensions.cs	Updates AddWebsite() expectations (assumes AddCore()/AddBackOffice()) and adjusts registrations accordingly.
src/Umbraco.Web.UI/Composers/ControllersAsServicesComposer.cs	Skips registering Management API controllers as services when backoffice is disabled.
src/Umbraco.Web.Common/DependencyInjection/UmbracoBuilderExtensions.cs	Introduces AddCore() and associated core registration + idempotency marker.
src/Umbraco.Web.Common/ApplicationBuilder/UmbracoApplicationBuilder.cs	Avoids applying backoffice rewrite middleware when backoffice is disabled.
src/Umbraco.Infrastructure/DependencyInjection/UmbracoBuilder.CoreServices.cs	Registers no-op fallbacks for backoffice-dependent services when running without backoffice.
src/Umbraco.Core/Services/NoopConflictingRouteService.cs	Adds fallback IConflictingRouteService implementation for non-backoffice scenarios.
src/Umbraco.Core/Security/NoopLocalLoginSettingProvider.cs	Adds fallback ILocalLoginSettingProvider implementation for non-backoffice scenarios.
src/Umbraco.Core/DependencyInjection/IBackOfficeEnabledMarker.cs	Adds marker interface + implementation indicating backoffice is enabled.
src/Umbraco.Cms.Api.Management/ManagementApiComposer.cs	Conditionally registers Management API only when backoffice marker is present.
src/Umbraco.Cms.Api.Management/DependencyInjection/UmbracoBuilder.BackOfficeIdentity.cs	Ensures backoffice implementation replaces the core default local-login provider.
src/Umbraco.Cms.Api.Management/DependencyInjection/UmbracoBuilder.BackOffice.cs	Refactors AddBackOffice() to call AddCore() and registers the backoffice marker.
src/Umbraco.Cms.Api.Delivery/DependencyInjection/UmbracoBuilderExtensions.cs	Ensures Delivery API can run without backoffice by adding required member/auth pieces.
src/Umbraco.Cms.Api.Delivery/DependencyInjection/UmbracoApplicationBuilderExtensions.cs	Adds UseDeliveryApiEndpoints() to map controller endpoints when backoffice isn’t present.

[Zeegaan]

Just one small thing.

Overall this looks okay, and would be useful. But I would really like some extensive testing on this, I don't trust myself to catch all potential scenarios 😁

[AndyButland]

But I would really like some extensive testing on this, I don't trust myself to catch all potential scenarios

Understood. I've added some integration tests as you likely saw, that at least confirms Umbraco will boot under the various scenarios. Will see if we can get some focussed QA on this before it's merged though.

[Zeegaan]

Agreed, lets get som QA eyes too, I'll approve 😁

[andr317c]

I tested a bit, and I get this

Failed to build models.                                                                                                                                                                                                                                                             
  System.InvalidOperationException: No service for type 'Umbraco.Cms.Infrastructure.ModelsBuilder.UmbracoServices' has been registered.                                                                                                                                                                         
     at Microsoft.Extensions.DependencyInjection.ServiceProviderServiceExtensions.GetRequiredService(IServiceProvider provider, Type serviceType)                                                                                                                                                                   
     at Microsoft.Extensions.DependencyInjection.ServiceProviderServiceExtensions.GetRequiredService[T](IServiceProvider provider)                                                                                                                                                                                  
     at System.Lazy`1.ViaFactory(LazyThreadSafetyMode mode)                                                                                                                                                                                                                                                     
     at System.Lazy`1.ExecutionAndPublication(LazyHelper executionAndPublication, Boolean useDefaultConstructor)                                                                                                                                                                                                
     at System.Lazy`1.CreateValue()                                                                                                                                                                                                                                                                                 
     at Umbraco.Cms.DevelopmentMode.Backoffice.InMemoryAuto.InMemoryModelFactory.get_UmbracoServices() in C:\Users\andr3\Desktop\Diffenret\src\Umbraco.Cms.DevelopmentMode.Backoffice\InMemoryAuto\InMemoryModelFactory.cs:line 125                                                                                 
     at Umbraco.Cms.DevelopmentMode.Backoffice.InMemoryAuto.InMemoryModelFactory.GetModelsAssembly(Boolean forceRebuild) in C:\Users\andr3\Desktop\Diffenret\src\Umbraco.Cms.DevelopmentMode.Backoffice\InMemoryAuto\InMemoryModelFactory.cs:line 408                                                               
     at Umbraco.Cms.DevelopmentMode.Backoffice.InMemoryAuto.InMemoryModelFactory.EnsureModels() in C:\Users\andr3\Desktop\Diffenret\src\Umbraco.Cms.DevelopmentMode.Backoffice\InMemoryAuto\InMemoryModelFactory.cs:line 318  

When I fetch content through the delivery api, it only occurs for the "Delivery API Only" setup

[AndyButland]

Thanks for looking at this @andr317c. Can I just check a couple of things, as it seems OK for me (but maybe I'm missing something).

My Program.cs file looks like this:

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.CreateUmbracoBuilder()
    .AddCore()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

WebApplication app = builder.Build();

await app.BootUmbracoAsync();

app.UseUmbraco()
    .WithMiddleware(u =>
    {
    })
    .WithEndpoints(u =>
    {
        u.UseDeliveryApiEndpoints();
    });

await app.RunAsync();

I don't have the Umbraco.Cms.DevelopmentMode.Backoffice referenced.

And my models builder configuration is set to:

  "ModelsBuilder": {
    "ModelsMode": "None"
  }

Both of which would make sense I think for a delivery API only setup.

Can you see what may be different for you to get that error please?

---

As I say, I couldn't replicate the problem, but Claude gave me an idea what it could be, which sounded feasible, so I've pushed that change. Please let me know if that now works for you.

[andr317c]

The "issue" is fixed for me now 💪 The only difference is that I had "ModelsBuilder": { "ModelsMode": "InMemoryAuto" }

[AndyButland]

Docs PR is here: umbraco/UmbracoDocs#7861

[simonech]

@AndyButland is this also addressing the issue of having login and backoffice endpoints as separate "registrations"?
#22144

[AndyButland]

I hadn't considered this for that scenario @simonech, no. So think that will be something to tackle as a follow-up.