[Breaking change]: Services refactoring from Umbraco 18

[AndyButland]

Description

The Umbraco service layer, like all the code in Umbraco, has evolved over time, and we currently have a mix of patterns in place.

Taking for example a "modern" service, implemented in the last year or so like the IWebhookService, you'll see we have:

• Asynchronous methods.
• Use of the Attempt pattern for all write operations.
• All identifiers are represented as GUIDs.

Services that have been in use for a longer period of time tend to show:

• Synchronous methods
• Write operations that use null responses or exceptions for returning status information.
• Identifiers represented as integers.

We would like to standardize this, refactoring the services to use the modern approaches.

When it comes to refactorings, our usual aim is to do them in a backward compatible way, keeping older and obsolete methods and services around for a couple of major versions before removing them. On this scale though, it becomes a significant challenge - both for the effort in implementation, and the confusion that can result for consumers of these services, from making available different approaches for the same task.

As such we plan to introduce this as an anticipated breaking change at some point in the 18 to 21 cycle of Umbraco major releases. As these major releases are planned we'll update this announcement with more precision.

Version

Other (please put exact version in description textbox)

Previous behavior

Service interfaces are as of today.

New behavior

Service interfaces will be updated to follow a consistent pattern of using GUIDs for identifiers, asynchronous methods and an Attempt pattern around write operations.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

Alignment for consistency, potentially improved performance.

Recommended action

There is no action needed or possible at the current stage. We are announcing this purely to raise awareness of this change, when we get to a new cycle of short-term releases for Umbraco in 2026.

At that point, if you are using Umbraco's services in your own code, you should expect some breaking changes. They should be straightforward to resolve as they will be thrown up as compile errors, and we expect that:

• All services that exist today will exist in the updated version, with the same interface name.
• All services will follow a consistent pattern when it comes to naming and method signatures. As such if you are using one service it should be more straightforward to apply similar code patterns to other ones.
• Methods that read or write data and were previously synchronous will be asynchronous, returning an awaitable Task and be identified with an Async suffix.
• Where previously you were providing integer IDs for Umbraco entities, you'll need to use the GUID Key.
• If this isn't easily accessible Umbraco's IIdKeyMap can be used to derive them.
• If you use write operations, you will need to expect to retrieve an Attempt that you can unpack to verify the success of the operation, the specific status in case of an error, and the result itself.
• If you use an existing Save method, you will need to change to use CreateAsync or UpdateAsync.

Affected APIs

Umbraco service interfaces.

[ronaldbarendse]

• If you use an existing Save method, you will need to change to use CreateAsync or UpdateAsync

Determining whether an entity needs to be created or updated currently depends heavily on checking whether the integer ID is not 0 (see e.g. EntitySlim.HasIdentity). Will the integer ID still be exposed on the entity (just not usable on the service methods) or will we have a different way to determine this (e.g. using NPoco's Database.IsNew())?