Allow multiple URL segments per document (#18603)

* Code tidy - XML header comments, method ordering, warning resolution.

* Add extension method for retrieving all URL segments for a document.

* Cache and persist multiple URL segments per document.

* Allowed segment providers to terminate or allow additional segments.
Set up currently failing integration test for expected routes.

* Resolved cache issue to ensure passing new integration tests.

* Fixed failing integration test.

* Test class naming tidy up.

* Added resolution and persistance of a primary segment, to retain previous behaviour when a single segment is retrieved.

* Further integration tests.

* Resolved backward compatibility of interface.

* Supress amends made to integration tests.

* Aligned naming of integration tests.

* Removed unused using, added XML header comment.

* Throw on missing table in migration.

* Code clean-up.

* Fix multiple enumeration

* Used default on migrated column.

* Use 1 over true for default value.

* Remove unused logger

---------

Co-authored-by: mole <[email protected]>

Author: AndyButland

src/Umbraco.Core/Models/ContentBaseExtensions.cs

@@ -11,37 +11,81 @@ public static class ContentBaseExtensions
     private static DefaultUrlSegmentProvider? _defaultUrlSegmentProvider;
 
     /// <summary>
-    ///     Gets the URL segment for a specified content and culture.
+    /// Gets a single URL segment for a specified content and culture.
     /// </summary>
     /// <param name="content">The content.</param>
     /// <param name="shortStringHelper"></param>
     /// <param name="urlSegmentProviders"></param>
     /// <param name="culture">The culture.</param>
     /// <param name="published">Whether to get the published or draft.</param>
     /// <returns>The URL segment.</returns>
+    /// <remarks>
+    /// If more than one URL segment provider is available, the first one that returns a non-null value will be returned.
+    /// </remarks>
     public static string? GetUrlSegment(this IContentBase content, IShortStringHelper shortStringHelper, IEnumerable<IUrlSegmentProvider> urlSegmentProviders, string? culture = null, bool published = true)
     {
-        if (content == null)
-        {
-            throw new ArgumentNullException(nameof(content));
-        }
+        var urlSegment = GetUrlSegments(content, urlSegmentProviders, culture, published).FirstOrDefault();
+
+        // Ensure we have at least the segment from the default URL provider returned.
+        urlSegment ??= GetDefaultUrlSegment(shortStringHelper, content, culture, published);
 
-        if (urlSegmentProviders == null)
+        return urlSegment;
+    }
+
+    /// <summary>
+    /// Gets all URL segments for a specified content and culture.
+    /// </summary>
+    /// <param name="content">The content.</param>
+    /// <param name="shortStringHelper"></param>
+    /// <param name="urlSegmentProviders"></param>
+    /// <param name="culture">The culture.</param>
+    /// <param name="published">Whether to get the published or draft.</param>
+    /// <returns>The collection of URL segments.</returns>
+    public static IEnumerable<string> GetUrlSegments(this IContentBase content, IShortStringHelper shortStringHelper, IEnumerable<IUrlSegmentProvider> urlSegmentProviders, string? culture = null, bool published = true)
+    {
+        var urlSegments = GetUrlSegments(content, urlSegmentProviders, culture, published).Distinct().ToList();
+
+        // Ensure we have at least the segment from the default URL provider returned.
+        if (urlSegments.Count == 0)
         {
-            throw new ArgumentNullException(nameof(urlSegmentProviders));
+            var defaultUrlSegment = GetDefaultUrlSegment(shortStringHelper, content, culture, published);
+            if (defaultUrlSegment is not null)
+            {
+                urlSegments.Add(defaultUrlSegment);
+            }
         }
 
-        var url = urlSegmentProviders.Select(p => p.GetUrlSegment(content, published, culture)).FirstOrDefault(u => u != null);
-        if (url == null)
+        return urlSegments;
+    }
+
+    private static IEnumerable<string> GetUrlSegments(
+        IContentBase content,
+        IEnumerable<IUrlSegmentProvider> urlSegmentProviders,
+        string? culture,
+        bool published)
+    {
+        foreach (IUrlSegmentProvider urlSegmentProvider in urlSegmentProviders)
         {
-            if (_defaultUrlSegmentProvider == null)
+            var segment = urlSegmentProvider.GetUrlSegment(content, published, culture);
+            if (string.IsNullOrEmpty(segment) == false)
             {
-                _defaultUrlSegmentProvider = new DefaultUrlSegmentProvider(shortStringHelper);
-            }
+                yield return segment;
 
-            url = _defaultUrlSegmentProvider.GetUrlSegment(content, culture); // be safe
+                if (urlSegmentProvider.AllowAdditionalSegments is false)
+                {
+                    yield break;
+                }
+            }
         }
+    }
 
-        return url;
+    private static string? GetDefaultUrlSegment(
+        IShortStringHelper shortStringHelper,
+        IContentBase content,
+        string? culture,
+        bool published)
+    {
+        _defaultUrlSegmentProvider ??= new DefaultUrlSegmentProvider(shortStringHelper);
+        return _defaultUrlSegmentProvider.GetUrlSegment(content, published, culture);
     }
 }

src/Umbraco.Core/Models/PublishedDocumentUrlSegment.cs

@@ -1,9 +1,32 @@
 namespace Umbraco.Cms.Core.Models;
 
+/// <summary>
+/// Represents a URL segment for a published document.
+/// </summary>
 public class PublishedDocumentUrlSegment
 {
+    /// <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 URL segment string.
+    /// </summary>
     public required string UrlSegment { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the URL segment is for a draft.
+    /// </summary>
     public required bool IsDraft { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the URL segment is the primary one (first resolved from the collection of URL providers).
+    /// </summary>
+    public required bool IsPrimary { get; set; }
 }