Merge branch 'feature/TrackedCollection' into develop

Introduced a new `TrackedCollection<>` type (e77d6e9) which centralizes the logic for both `AttributeValueCollection` (beb3d1f) and `TopicReferenceCollection` (previously `TopicReferenceDictionary`) (74d5907). This allows the two classes to share the following features:
- Lookup of actual values by `key` via `GetValue()`, with inheritance from `BaseTopic` and, optionally, `Parent`.
- Tracking of state via `IsDirty` and `Version` on a unified `TrackedItem<T>` metadata container.
- Enforcement of business logic by calling appropriate properties on `Topic` via `SetValue()`.

This also unifies the semantics and the syntax for working with these two collections, thus acknowledging that topic references are, ultimately, just topic-valued attributes, and should thus otherwise operate the same. This changes the semantics and syntax from the initial design of `TopicReferenceDictionary` which was, instead, modeled more off of `TopicRelationshipMultiMap`. Outside of returning `Topic` types, though, `TopicReferenceCollection` has more in common with `AttributeValueCollection`.

As a result of this, the `TopicPropertyDispatcher` is now _exclusively_ used by the new `TrackedCollection<>`, which exclusively operates off of `TrackedItem<T>`. As such, I updated `TopicPropertyDispatcher` to operate off of that assumption, which thus eliminated the one-off hacks for both `AttributeValueCollection` and `TopicReferenceCollection` (11506c3). This also necessitated some bug fixes in the underlying `MemberDispatcher` to better handle generic type parameters (13d43d1, edc9f4b).

Because of the change from `IDictionary<>` to `KeyedCollection<>`, the `TopicReferenceCollection` has some breaking changes. As it was first developed for OnTopic 5.x, which hasn't yet released, this won't impact any customers. It will require updating the OnTopic Editor, however, which has been developing its 5.x release in parallel based on pre-release packages. These changes are mostly trivial, pertaining to slight differences in interface. The most notable changes, however, include:
1. The `GetTopic()` and `SetTopic()` methods have been replaced with the more generically named `GetValue()` and `SetValue()` (0544353).
2. The `TryGetValue()` (4b00642) and `Add(string, Topic)` (956c9f4) methods no longer exist, and should be replaced with `GetValue()` and `SetValue()` respectively.
3. The `Value` is now nullable, which can be an issue when iterating over the collection (e7a5520).

In exchange, the `TopicReferenceCollection` now enjoys nearly identical semantics and syntax as `AttributeValueCollection`, including some new features such as `inheritFromParent`, which it didn't previously support.

Author: JeremyCaney

OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs

@@ -282,7 +282,7 @@ topic.References.Count is 0?
               from reference in topic.References
               select new XElement(_pagemapNamespace + "Attribute",
                 new XAttribute("name", reference.Key),
-                new XText(reference.Value.GetUniqueKey().Replace("Root:", "", StringComparison.OrdinalIgnoreCase))
+                new XText(reference.Value?.GetUniqueKey().Replace("Root:", "", StringComparison.OrdinalIgnoreCase))
               )
             );
 

OnTopic.Data.Sql/SqlDataReaderExtensions.cs

@@ -434,7 +434,7 @@ private static void SetReferences(this IDataReader reader, TopicIndex topics, bo
       /*------------------------------------------------------------------------------------------------------------------------
       | Set relationship on object
       \-----------------------------------------------------------------------------------------------------------------------*/
-      current.References.SetTopic(relationshipKey, referenced, markDirty);
+      current.References.SetValue(relationshipKey, referenced, markDirty);
 
     }
 

OnTopic.Data.Sql/SqlTopicRepository.cs

@@ -710,8 +710,8 @@ private static void PersistReferences(Topic topic, DateTime version, SqlConnecti
           CommandType           = CommandType.StoredProcedure
         };
 
-        foreach (var relatedTopic in topic.References.Where(t => !t.Value.IsNew)) {
-          references.AddRow(relatedTopic.Key, relatedTopic.Value.Id);
+        foreach (var relatedTopic in topic.References.Where(t => !t.Value?.IsNew?? false)) {
+          references.AddRow(relatedTopic.Key, relatedTopic.Value!.Id);
         }
 
         // Add Parameters

OnTopic.Tests/AttributeValueCollectionTest.cs

@@ -8,6 +8,7 @@
 using System.Globalization;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 using OnTopic.Attributes;
+using OnTopic.Collections.Specialized;
 using OnTopic.Tests.Entities;
 
 namespace OnTopic.Tests {
@@ -308,7 +309,7 @@ public void Clear_ExistingValues_IsDirty() {
       topic.Attributes.Clear();
 
       Assert.IsTrue(topic.Attributes.IsDirty());
-      Assert.IsTrue(topic.Attributes.DeletedAttributes.Contains("Foo"));
+      Assert.IsTrue(topic.Attributes.DeletedItems.Contains("Foo"));
 
     }
 
@@ -317,7 +318,7 @@ public void Clear_ExistingValues_IsDirty() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Sets the value of a custom <see cref="AttributeValue"/> to the existing value and ensures it is <i>not</i> marked as
-    ///   <see cref="AttributeValue.IsDirty"/>.
+    ///   <see cref="TrackedItem{T}.IsDirty"/>.
     /// </summary>
     [TestMethod]
     public void SetValue_ValueUnchanged_IsNotDirty() {
@@ -336,7 +337,7 @@ public void SetValue_ValueUnchanged_IsNotDirty() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> that is marked as <see
-    ///   cref="AttributeValue.IsDirty"/>. Confirms that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns
+    ///   cref="TrackedItem{T}.IsDirty"/>. Confirms that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns
     ///   <c>true</c>.
     /// </summary>
     [TestMethod]
@@ -374,7 +375,7 @@ public void IsDirty_DeletedValues_ReturnsTrue() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> that is <i>not</i> marked as
-    ///   <see cref="AttributeValue.IsDirty"/>. Confirms that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns
+    ///   <see cref="TrackedItem{T}.IsDirty"/>. Confirms that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns
     ///   <c>false</c>/
     /// </summary>
     [TestMethod]
@@ -393,7 +394,7 @@ public void IsDirty_NoDirtyValues_ReturnsFalse() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> that is <i>not</i> marked as
-    ///   <see cref="AttributeValue.IsDirty"/> as well as a <c>LastModified</c> <see cref="AttributeValue"/> that is. Confirms
+    ///   <see cref="TrackedItem{T}.IsDirty"/> as well as a <c>LastModified</c> <see cref="AttributeValue"/> that is. Confirms
     ///   that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns <c>false</c>.
     /// </summary>
     [TestMethod]
@@ -414,8 +415,8 @@ public void IsDirty_ExcludeLastModified_ReturnsFalse() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> and then deletes it. Confirms
-    ///   that the <see cref="AttributeValue.LastModified"/> returns the new <c>version</c> after calling <see cref="
-    ///   AttributeValueCollection.MarkClean(DateTime?)"/>.
+    ///   that the <see cref="TrackedItem{T}.LastModified"/> returns the new <c>version</c> after calling <see cref="
+    ///   TrackedCollection{TItem, TValue, TAttribute}.MarkClean(DateTime?)"/>.
     /// </summary>
     [TestMethod]
     public void IsDirty_MarkClean_UpdatesLastModified() {
@@ -437,7 +438,7 @@ public void IsDirty_MarkClean_UpdatesLastModified() {
     /// <summary>
     ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> and then deletes it. Confirms
     ///   that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns <c>false</c> after calling <see cref="
-    ///   AttributeValueCollection.MarkClean(DateTime?)"/>.
+    ///   TrackedCollection{TItem, TValue, TAttribute}.MarkClean(DateTime?)"/>.
     /// </summary>
     [TestMethod]
     public void IsDirty_MarkClean_ReturnsFalse() {
@@ -460,8 +461,8 @@ public void IsDirty_MarkClean_ReturnsFalse() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> and then confirms that <see
-    ///   cref="AttributeValueCollection.IsDirty(String)"/> returns <c>false</c> for that attribute after calling <see cref="
-    ///   AttributeValueCollection.MarkClean(String, DateTime?)"/>.
+    ///   cref="TrackedCollection{TItem, TValue, TAttribute}.IsDirty(String)"/> returns <c>false</c> for that attribute after
+    ///   calling <see cref="TrackedCollection{TItem, TValue, TAttribute}.MarkClean(String, DateTime?)"/>.
     /// </summary>
     [TestMethod]
     public void IsDirty_MarkAttributeClean_ReturnsFalse() {
@@ -623,8 +624,8 @@ public void Add_InvalidAttributeValue_ThrowsException() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Adds a new <see cref="AttributeValue"/> which maps to <see cref="Topic.Key"/> directly to a <see cref=
-    ///   "AttributeValueCollection"/> and confirms that the original <see cref="AttributeValue.IsDirty"/> is replaced if the
-    ///   <see cref="AttributeValue.Value"/> changes.
+    ///   "AttributeValueCollection"/> and confirms that the original <see cref="TrackedItem{T}.IsDirty"/> is replaced if the
+    ///   <see cref="TrackedItem{T}.Value"/> changes.
     /// </summary>
     [TestMethod]
     public void Add_WithBusinessLogic_MaintainsIsDirty() {

OnTopic.Tests/Entities/CustomTopic.cs

@@ -34,7 +34,7 @@ public CustomTopic(string key, string contentType, Topic? parent = null, int id
     ///   Provides a text property which is intended to be mapped to a text attribute.
     /// </summary>
     [AttributeSetter]
-    public string TextAttribute {
+    public string? TextAttribute {
       get => Attributes.GetValue("TextAttribute");
       set => SetAttributeValue("TextAttribute", value);
     }
@@ -95,13 +95,13 @@ public DateTime DateTimeAttribute {
     /// </summary>
     [ReferenceSetter]
     public Topic? TopicReference {
-      get => References.GetTopic("TopicReference");
+      get => References.GetValue("TopicReference");
       set {
         Contract.Requires<ArgumentOutOfRangeException>(
           value.ContentType == ContentType,
           $"{nameof(TopicReference)} expects a topic with the same content type as the parent: {ContentType}."
         );
-        References.SetTopic("TopicReference", value);
+        References.SetValue("TopicReference", value);
       }
     }
 

OnTopic.Tests/SqlTopicRepositoryTest.cs

@@ -124,7 +124,7 @@ public void LoadTopicGraph_WithReference_ReturnsReference() {
 
       Assert.IsNotNull(topic);
       Assert.AreEqual<int>(1, topic.Id);
-      Assert.AreEqual<int?>(2, topic.References.GetTopic("Test")?.Id);
+      Assert.AreEqual<int?>(2, topic.References.GetValue("Test")?.Id);
       Assert.IsTrue(topic.References.IsDirty());
 
     }
@@ -154,7 +154,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() {
 
       Assert.IsNotNull(topic);
       Assert.AreEqual<int>(1, topic.Id);
-      Assert.AreEqual<int?>(2, topic.References.GetTopic("Test")?.Id);
+      Assert.AreEqual<int?>(2, topic.References.GetValue("Test")?.Id);
       Assert.IsTrue(topic.References.IsFullyLoaded);
       Assert.IsFalse(topic.References.IsDirty());
 

OnTopic.Tests/TopicMappingServiceTest.cs

@@ -593,7 +593,7 @@ public async Task Map_TopicReferences_ReturnsMappedModel() {
 
       var topic                 = TopicFactory.Create("Test", "TopicReference");
 
-      topic.References.SetTopic("TopicReference", topicReference);
+      topic.References.SetValue("TopicReference", topicReference);
 
       var target                = (TopicReferenceTopicViewModel?)await mappingService.MapAsync(topic).ConfigureAwait(false);
 
@@ -618,7 +618,7 @@ public async Task Map_TopicReferences_SkipsDisabled() {
 
       topicReference.IsDisabled = true;
 
-      topic.References.SetTopic("TopicReference", topicReference);
+      topic.References.SetValue("TopicReference", topicReference);
 
       var target                = (TopicReferenceTopicViewModel?)await mappingService.MapAsync(topic).ConfigureAwait(false);