Routing: Add DocumentUrlAliasService for optimized URL alias lookups (closes #21383) (#21396)

* Implement document alias cache and service to optimize content finder by alias.

* Renamed to DocumentUrlAlias. Fixed issues on start-up.

* Remove tracking of root ancestor.

* Optimize cache key, tidy up tests, move domain matching to content finder.

* Handle language and document deletes.

* Align further with document URL service.

* Code tidy.

* Fixed comment.

* Refactor scope handling to avoid nested scopes

Extract CreateOrUpdateAliasesInternalAsync to process documents without
creating their own scope. Both CreateOrUpdateAliasesAsync and
CreateOrUpdateAliasesWithDescendantsAsync now create a single scope
and call the internal method, avoiding unnecessary nested scope creation.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Extract CreateOrUpdateAliasesInternalAsync to process documents without
creating their own scope.

* Only return a document for a match under a domain if the document is found under the domain of the current request.

* Fix failing integration tests.

* Apply suggestions from code review.

* Ensured language to culture code map is updated when a language isn't found in the cached map.

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: AndyButland

src/Umbraco.Core/Cache/Refreshers/Implement/ContentCacheRefresher.cs

@@ -1,3 +1,5 @@
+using Microsoft.Extensions.DependencyInjection;
+using Umbraco.Cms.Core.DependencyInjection;
 using Umbraco.Cms.Core.Events;
 using Umbraco.Cms.Core.Models;
 using Umbraco.Cms.Core.Notifications;
@@ -28,6 +30,7 @@ public sealed class ContentCacheRefresher : PayloadCacheRefresherBase<ContentCac
     private readonly IDomainService _domainService;
     private readonly IDomainCacheService _domainCacheService;
     private readonly IDocumentUrlService _documentUrlService;
+    private readonly IDocumentUrlAliasService _documentUrlAliasService;
     private readonly IDocumentNavigationQueryService _documentNavigationQueryService;
     private readonly IDocumentNavigationManagementService _documentNavigationManagementService;
     private readonly IContentService _contentService;
@@ -39,6 +42,7 @@ public sealed class ContentCacheRefresher : PayloadCacheRefresherBase<ContentCac
     /// <summary>
     /// Initializes a new instance of the <see cref="ContentCacheRefresher"/> class.
     /// </summary>
+    [Obsolete("Please use the constructor taking all parameters. Scheduled for removal in Umbraco 19.")]
     public ContentCacheRefresher(
         AppCaches appCaches,
         IJsonSerializer serializer,
@@ -54,12 +58,51 @@ public ContentCacheRefresher(
         IPublishStatusManagementService publishStatusManagementService,
         IDocumentCacheService documentCacheService,
         ICacheManager cacheManager)
+        : this(
+            appCaches,
+            serializer,
+            idKeyMap,
+            domainService,
+            eventAggregator,
+            factory,
+            documentUrlService,
+            StaticServiceProvider.Instance.GetRequiredService<IDocumentUrlAliasService>(),
+            domainCacheService,
+            documentNavigationQueryService,
+            documentNavigationManagementService,
+            contentService,
+            publishStatusManagementService,
+            documentCacheService,
+            cacheManager)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContentCacheRefresher"/> class.
+    /// </summary>
+    public ContentCacheRefresher(
+        AppCaches appCaches,
+        IJsonSerializer serializer,
+        IIdKeyMap idKeyMap,
+        IDomainService domainService,
+        IEventAggregator eventAggregator,
+        ICacheRefresherNotificationFactory factory,
+        IDocumentUrlService documentUrlService,
+        IDocumentUrlAliasService documentUrlAliasService,
+        IDomainCacheService domainCacheService,
+        IDocumentNavigationQueryService documentNavigationQueryService,
+        IDocumentNavigationManagementService documentNavigationManagementService,
+        IContentService contentService,
+        IPublishStatusManagementService publishStatusManagementService,
+        IDocumentCacheService documentCacheService,
+        ICacheManager cacheManager)
         : base(appCaches, serializer, eventAggregator, factory)
     {
         _idKeyMap = idKeyMap;
         _domainService = domainService;
         _domainCacheService = domainCacheService;
         _documentUrlService = documentUrlService;
+        _documentUrlAliasService = documentUrlAliasService;
         _documentNavigationQueryService = documentNavigationQueryService;
         _documentNavigationManagementService = documentNavigationManagementService;
         _contentService = contentService;
@@ -270,28 +313,33 @@ private void HandleRouting(JsonPayload payload)
             if (_documentNavigationQueryService.TryGetDescendantsKeysOrSelfKeys(key, out IEnumerable<Guid>? descendantsOrSelfKeys))
             {
                 _documentUrlService.DeleteUrlsFromCacheAsync(descendantsOrSelfKeys).GetAwaiter().GetResult();
+                _documentUrlAliasService.DeleteAliasesFromCacheAsync(descendantsOrSelfKeys).GetAwaiter().GetResult();
             }
             else if (_documentNavigationQueryService.TryGetDescendantsKeysOrSelfKeysInBin(key, out IEnumerable<Guid>? descendantsOrSelfKeysInBin))
             {
                 _documentUrlService.DeleteUrlsFromCacheAsync(descendantsOrSelfKeysInBin).GetAwaiter().GetResult();
+                _documentUrlAliasService.DeleteAliasesFromCacheAsync(descendantsOrSelfKeysInBin).GetAwaiter().GetResult();
             }
         }
 
         if (payload.ChangeTypes.HasType(TreeChangeTypes.RefreshAll))
         {
             _documentUrlService.InitAsync(false, CancellationToken.None).GetAwaiter().GetResult(); // TODO: make async
+            _documentUrlAliasService.InitAsync(false, CancellationToken.None).GetAwaiter().GetResult();
         }
 
         if (payload.ChangeTypes.HasType(TreeChangeTypes.RefreshNode))
         {
             Guid key = payload.Key ?? _idKeyMap.GetKeyForId(payload.Id, UmbracoObjectTypes.Document).Result;
             _documentUrlService.CreateOrUpdateUrlSegmentsAsync(key).GetAwaiter().GetResult();
+            _documentUrlAliasService.CreateOrUpdateAliasesAsync(key).GetAwaiter().GetResult();
         }
 
         if (payload.ChangeTypes.HasType(TreeChangeTypes.RefreshBranch))
         {
             Guid key = payload.Key ?? _idKeyMap.GetKeyForId(payload.Id, UmbracoObjectTypes.Document).Result;
             _documentUrlService.CreateOrUpdateUrlSegmentsWithDescendantsAsync(key).GetAwaiter().GetResult();
+            _documentUrlAliasService.CreateOrUpdateAliasesWithDescendantsAsync(key).GetAwaiter().GetResult();
         }
     }
 

src/Umbraco.Core/DependencyInjection/UmbracoBuilder.cs

@@ -439,6 +439,8 @@ private void AddCoreServices()
             // Routing
             Services.AddUnique<IDocumentUrlService, DocumentUrlService>();
             Services.AddNotificationAsyncHandler<UmbracoApplicationStartingNotification, DocumentUrlServiceInitializerNotificationHandler>();
+            Services.AddUnique<IDocumentUrlAliasService, DocumentUrlAliasService>();
+            Services.AddNotificationAsyncHandler<UmbracoApplicationStartingNotification, DocumentUrlAliasServiceInitializerNotificationHandler>();
         }
     }
 }

src/Umbraco.Core/Extensions/DocumentUrlAliasServiceExtensions.cs

@@ -0,0 +1,22 @@
+using Umbraco.Cms.Core.Services;
+
+namespace Umbraco.Cms.Core.Extensions;
+
+/// <summary>
+/// Provides extension methods for <see cref="IDocumentUrlAliasService"/>.
+/// </summary>
+internal static class DocumentUrlAliasServiceExtensions
+{
+    /// <summary>
+    /// Normalizes a URL alias by trimming whitespace, removing leading/trailing slashes, and converting to lowercase.
+    /// </summary>
+    /// <param name="service">The <see cref="IDocumentUrlAliasService"/>.</param>
+    /// <param name="alias">The alias to normalize.</param>
+    /// <returns>The normalized alias.</returns>
+    public static string NormalizeAlias(this IDocumentUrlAliasService service, string alias) =>
+        alias
+            .Trim()
+            .TrimStart('/')
+            .TrimEnd('/')
+            .ToLowerInvariant();
+}

src/Umbraco.Core/Models/PublishedDocumentUrlAlias.cs

@@ -0,0 +1,22 @@
+namespace Umbraco.Cms.Core.Models;
+
+/// <summary>
+/// Represents a URL alias for a published document.
+/// </summary>
+public class PublishedDocumentUrlAlias
+{
+    /// <summary>
+    /// Gets or sets the document key.
+    /// </summary>
+    public required Guid DocumentKey { get; set; }
+
+    /// <summary>
+    /// Gets or sets the language Id.
+    /// </summary>
+    public required int LanguageId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the normalized URL alias (lowercase, no leading slash).
+    /// </summary>
+    public required string Alias { get; set; }
+}

src/Umbraco.Core/Persistence/Constants-DatabaseSchema.cs

@@ -50,6 +50,7 @@ public static class Tables
             public const string DocumentCultureVariation = TableNamePrefix + "DocumentCultureVariation";
             public const string DocumentVersion = TableNamePrefix + "DocumentVersion";
             public const string DocumentUrl = TableNamePrefix + "DocumentUrl";
+            public const string DocumentUrlAlias = TableNamePrefix + "DocumentUrlAlias";
             public const string MediaVersion = TableNamePrefix + "MediaVersion";
             public const string ContentSchedule = TableNamePrefix + "ContentSchedule";
 

src/Umbraco.Core/Persistence/Constants-Locks.cs

@@ -100,5 +100,10 @@ public static class Locks
         ///     All distributed jobs.
         /// </summary>
         public const int DistributedJobs = -347;
+
+        /// <summary>
+        ///     All document URL aliases.
+        /// </summary>
+        public const int DocumentUrlAliases = -348;
     }
 }

src/Umbraco.Core/Persistence/Repositories/IDocumentUrlAliasRepository.cs

@@ -0,0 +1,55 @@
+using Umbraco.Cms.Core.Models;
+
+namespace Umbraco.Cms.Core.Persistence.Repositories;
+
+/// <summary>
+/// Repository for document URL aliases.
+/// </summary>
+public interface IDocumentUrlAliasRepository
+{
+    /// <summary>
+    /// Saves the specified aliases to the database.
+    /// Handles insert/update/delete via diff - existing aliases not in the new set are deleted.
+    /// </summary>
+    /// <param name="aliases">The aliases to save.</param>
+    void Save(IEnumerable<PublishedDocumentUrlAlias> aliases);
+
+    /// <summary>
+    /// Gets all persisted aliases from the database.
+    /// </summary>
+    /// <returns>All persisted aliases.</returns>
+    IEnumerable<PublishedDocumentUrlAlias> GetAll();
+
+    /// <summary>
+    /// Deletes all aliases for the specified document keys.
+    /// </summary>
+    /// <param name="documentKeys">The document keys to delete aliases for.</param>
+    void DeleteByDocumentKey(IEnumerable<Guid> documentKeys);
+
+    /// <summary>
+    /// Gets all document aliases.
+    /// </summary>
+    /// <returns>Raw alias data from documents with umbracoUrlAlias property.</returns>
+    IEnumerable<DocumentUrlAliasRaw> GetAllDocumentUrlAliases();
+}
+
+/// <summary>
+/// Raw alias data from a direct SQL query.
+/// </summary>
+public class DocumentUrlAliasRaw
+{
+    /// <summary>
+    /// Gets or sets the document key.
+    /// </summary>
+    public Guid DocumentKey { get; set; }
+
+    /// <summary>
+    /// Gets or sets the language ID (null for invariant).
+    /// </summary>
+    public int? LanguageId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the raw alias value (may be comma-separated).
+    /// </summary>
+    public string AliasValue { get; set; } = string.Empty;
+}