Introduced new GetTopicByUniqueKey() extension method

Originally, the `OnTopic.Querying` class was focused on querying the current `Topic` and its descendants. Increasingly, however, we're identifying needs to work with the entire in-memory topic graph starting from an arbitrary position within the tree. This is particularly useful when it's difficult or inappropriate to inject an `ITopicRepository` such that we have access from the root.

As part of this, we're introducing the new `GetTopicByUniqueKey()` extension method, which allows any topic to be retrieved based on its absolute (or root relative) path in the topic graph, starting from any arbitrary position. This is useful for e.g. populating strongly typed topic references for `Relationships`, `IncomingRelationships`, and `DerivedTopic` , as well as metadata references for e.g. the associated `ContentTypeDescriptor`, even though it may not otherwise be appropriate to maintain a dependency on `ITopicRepository`.

Includes unit tests for validating the functionality.

Author: JeremyCaney

OnTopic.Tests/TopicQueryingTest.cs

@@ -64,5 +64,47 @@ public void GetRootTopic_ReturnsRootTopic() {
 
     }
 
+    /*==========================================================================================================================
+    | TEST: GET BY UNIQUE KEY: VALID KEY: RETURNS TOPIC
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Given a deeply nested <see cref="Topic"/>, returns the expected <see cref="Topic"/>.
+    /// </summary>
+    [TestMethod]
+    public void GetByUniqueKey_ValidKey_ReturnsTopic() {
+
+      var parentTopic           = TopicFactory.Create("ParentTopic", "Page", 1);
+      var childTopic            = TopicFactory.Create("ChildTopic", "Page", 5, parentTopic);
+      var grandChildTopic       = TopicFactory.Create("GrandChildTopic", "Page", 20, childTopic);
+      var greatGrandChildTopic1 = TopicFactory.Create("GreatGrandChildTopic1", "Page", 7, grandChildTopic);
+      var greatGrandChildTopic2 = TopicFactory.Create("GreatGrandChildTopic2", "Page", 7, grandChildTopic);
+
+      var foundTopic = greatGrandChildTopic1.GetByUniqueKey("ParentTopic:ChildTopic:GrandChildTopic:GreatGrandChildTopic2");
+
+      Assert.ReferenceEquals(greatGrandChildTopic2, foundTopic);
+
+    }
+
+    /*==========================================================================================================================
+    | TEST: GET BY UNIQUE KEY: INVALID KEY: RETURNS NULL
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Given an invalid <c>UniqueKey</c>, the <see cref="TopicExtensions.GetByUniqueKey(Topic, String)"/> returns
+    ///   <c>null</c>.
+    /// </summary>
+    [TestMethod]
+    public void GetByUniqueKey_InvalidKey_ReturnsNull() {
+
+      var parentTopic           = TopicFactory.Create("ParentTopic", "Page", 1);
+      var childTopic            = TopicFactory.Create("ChildTopic", "Page", 5, parentTopic);
+      var grandChildTopic       = TopicFactory.Create("GrandChildTopic", "Page", 20, childTopic);
+      var greatGrandChildTopic  = TopicFactory.Create("GreatGrandChildTopic", "Page", 7, grandChildTopic);
+
+      var foundTopic = greatGrandChildTopic.GetByUniqueKey("ParentTopic:ChildTopic:GrandChildTopic:GreatGrandChildTopic2");
+
+      Assert.IsNull(foundTopic);
+
+    }
+
   } //Class
 } //Namespace

OnTopic/Querying/TopicExtensions.cs

@@ -171,5 +171,49 @@ public static Topic GetRootTopic(this Topic topic) {
 
     }
 
+    /*==========================================================================================================================
+    | METHOD: GET BY UNIQUE KEY
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Retrieves a <see cref="Topic"/> with the specified <paramref name="uniqueKey"/>, if available.
+    /// </summary>
+    /// <param name="topic">The instance of the <see cref="Topic"/> to operate against; populated automatically by .NET.</param>
+    /// <param name="uniqueKey">The <see cref="Topic.GetUniqueKey()"/> of the <see cref="Topic"/> to return.</param>
+    /// <returns>A <see cref="Topic"/> with the specified <paramref name="uniqueKey"/>, if found.</returns>
+    public static Topic? GetByUniqueKey(this Topic topic, string uniqueKey) {
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Validate contracts
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      Contract.Requires(topic, "The topic parameter must be specified.");
+      Contract.Requires<ArgumentNullException>(!String.IsNullOrWhiteSpace(uniqueKey), "The unique key must be specified.");
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Find lowest common root
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      var currentTopic          = (Topic?)topic.GetRootTopic();
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Process keys
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      if (uniqueKey.StartsWith(currentTopic!.Key + ":", StringComparison.InvariantCultureIgnoreCase)) {
+        uniqueKey = uniqueKey.Substring(currentTopic!.Key.Length + 1);
+      }
+      var keys                  = uniqueKey.Split(new char[] {':'}, StringSplitOptions.RemoveEmptyEntries);
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Navigate to the specific path
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      foreach (var key in keys) {
+        currentTopic = currentTopic?.Children?.GetTopic(key);
+      }
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Return topic
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      return currentTopic;
+
+    }
+
   } //Class
 } //Namespace