Added (optional) version parameter to SetValue()

In order to allow an attribute's `LastModified` property to be stored as metadata, the `SetValue()` method needs to (optionally) accept this. Arguably, this _might_ make more sense being placed after `value`; since mapped properties will be calling `enforceBusinessLogic`, however, but _not_ supplying `lastModified`, we're placing it last. Regardless, as ancillary metdata on an internal overload, the order isn't too critical here. Since this is an advanced infrastructure requirement for tooling (e.g., loading, importing topics) this is _not_ being added to convenience extensions like `SetBooleanValue()`.

Author: JeremyCaney

OnTopic/Attributes/AttributeSetterAttribute.cs

@@ -13,14 +13,14 @@ namespace OnTopic.Attributes {
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
   ///   Flags that a property should be used when setting an attribute via
-  ///   <see cref="AttributeValueCollection.SetValue(String, String, Boolean?)"/>.
+  ///   <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?)"/>.
   /// </summary>
   /// <remarks>
   ///   <para>
-  ///     When a call is made to <see cref="AttributeValueCollection.SetValue(String, String, Boolean?)"/>, the code will check
-  ///     to see if a property with the same name as the attribute key exists, and whether that property is decorated with the
-  ///     <see cref="AttributeSetterAttribute"/> (i.e., <code>[AttributeSetter]</code>). If it is, then the update will be
-  ///     routed through that property. This ensures that business logic is enforced by local properties, instead of allowing
+  ///     When a call is made to <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?)"/>, the code
+  ///     will check to see if a property with the same name as the attribute key exists, and whether that property is decorated
+  ///     with the <see cref="AttributeSetterAttribute"/> (i.e., <code>[AttributeSetter]</code>). If it is, then the update will
+  ///     be routed through that property. This ensures that business logic is enforced by local properties, instead of allowing
   ///     business logic to be potentially bypassed by writing directly to the <see cref="Topic.Attributes"/> collection.
   ///   </para>
   ///   <para>
@@ -33,10 +33,10 @@ namespace OnTopic.Attributes {
   ///   </para>
   ///   <para>
   ///     To ensure this logic, it is critical that implementers of <see cref="AttributeSetterAttribute"/> ensure that the
-  ///     property setters call <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, Boolean)"/> overload with
-  ///     the final parameter set to false to disable the enforcement of business logic. Otherwise, an infinite loop will occur.
-  ///     Calling that overload tells <see cref="AttributeValueCollection"/> that the business logic has already been enforced
-  ///     by the caller. As this is an internal overload, implementers should use the local proxy at
+  ///     property setters call <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, Boolean, DateTime?)"/>
+  ///     overload with the final parameter set to false to disable the enforcement of business logic. Otherwise, an infinite
+  ///     loop will occur. Calling that overload tells <see cref="AttributeValueCollection"/> that the business logic has
+  ///     already been enforced by the caller. As this is an internal overload, implementers should use the local proxy at
   ///     <see cref="Topic.SetAttributeValue(String, String, Boolean?)"/>, which ensures that final parameter is set to false.
   ///   </para>
   /// </remarks>

OnTopic/Attributes/AttributeValue.cs

@@ -33,7 +33,8 @@ namespace OnTopic.Attributes {
   ///   <para>
   ///     This class is immutable: once it is constructed, the values cannot be changed. To change a value, callers must either
   ///     create a new instance of the <see cref="AttributeValue"/> class or, preferably, call the
-  ///     <see cref="Topic.Attributes"/>'s <see cref="AttributeValueCollection.SetValue(String, String, Boolean?)"/> method.
+  ///     <see cref="Topic.Attributes"/>'s <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?)"/>
+  ///     method.
   ///   </para>
   /// </remarks>
   public class AttributeValue {
@@ -163,12 +164,12 @@ internal AttributeValue(
     ///   <see cref="AttributeValueCollection"/>.
     /// </summary>
     /// <remarks>
-    ///   By default, when a user attempts to update an attribute's value by calling
-    ///   <see cref="AttributeValueCollection.SetValue(String, String, Boolean?)"/>, or when an <see cref="AttributeValue"/> is
-    ///   added to the <see cref="AttributeValueCollection"/>, the <see cref="AttributeValueCollection"/> will automatically
-    ///   attempt to call any corresponding setters on <see cref="Topic"/> (or a derived instance) to ensure that the business
-    ///   logic is enforced. To avoid an infinite loop, however, this is disabled when properties on <see cref="Topic"/> call
-    ///   <see cref="Topic.SetAttributeValue(String, String, Boolean?)"/>. When that happens, the
+    ///   By default, when a user attempts to update an attribute's value by calling <see
+    ///   cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?)"/>, or when an <see cref="AttributeValue"
+    ///   /> is added to the <see cref="AttributeValueCollection"/>, the <see cref="AttributeValueCollection"/> will
+    ///   automatically attempt to call any corresponding setters on <see cref="Topic"/> (or a derived instance) to ensure that
+    ///   the business logic is enforced. To avoid an infinite loop, however, this is disabled when properties on <see
+    ///   cref="Topic"/> call <see cref="Topic.SetAttributeValue(String, String, Boolean?)"/>. When that happens, the
     ///   <see cref="EnforceBusinessLogic"/> value is set to false to communicate to the <see cref="AttributeValueCollection"/>
     ///   that it should not call the local property. This value is only intended for internal use.
     /// </remarks>

OnTopic/Collections/AttributeValueCollection.cs

@@ -204,6 +204,11 @@ public bool IsDirty(string name) {
     ///   overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update from being
     ///   persisted to the data store on <see cref="Repositories.ITopicRepository.Save(Topic, Boolean, Boolean)"/>.
     /// </param>
+    /// <param name="version">
+    ///   The <see cref="DateTime"/> value that the attribute was last modified. This is intended exclusively for use when
+    ///   populating the topic graph from a persistent data store as a means of indicating the current version for each
+    ///   attribute. This is used when e.g. importing values to determine if the existing value is newer than the source value.
+    /// </param>
     /// <requires
     ///   description="The key must be specified for the AttributeValue key/value pair."
     ///   exception="T:System.ArgumentNullException">
@@ -219,7 +224,8 @@ public bool IsDirty(string name) {
     ///   exception="T:System.ArgumentException">
     ///   !value.Contains(" ")
     /// </requires>
-    public void SetValue(string key, string? value, bool? isDirty = null) => SetValue(key, value, isDirty, true);
+    public void SetValue(string key, string? value, bool? isDirty = null, DateTime? version = null)
+      => SetValue(key, value, isDirty, true, version);
 
     /// <summary>
     ///   Protected helper method that either adds a new <see cref="AttributeValue"/> object or updates the value of an existing
@@ -242,6 +248,11 @@ public bool IsDirty(string name) {
     ///   Instructs the underlying code to call corresponding properties, if available, to ensure business logic is enforced.
     ///   This should be set to false if setting attributes from internal properties in order to avoid an infinite loop.
     /// </param>
+    /// <param name="version">
+    ///   The <see cref="DateTime"/> value that the attribute was last modified. This is intended exclusively for use when
+    ///   populating the topic graph from a persistent data store as a means of indicating the current version for each
+    ///   attribute. This is used when e.g. importing values to determine if the existing value is newer than the source value.
+    /// </param>
     /// <requires
     ///   description="The key must be specified for the AttributeValue key/value pair."
     ///   exception="T:System.ArgumentNullException">
@@ -257,7 +268,7 @@ public bool IsDirty(string name) {
     ///   exception="T:System.ArgumentException">
     ///   !value.Contains(" ")
     /// </requires>
-    internal void SetValue(string key, string? value, bool? isDirty, bool enforceBusinessLogic) {
+    internal void SetValue(string key, string? value, bool? isDirty, bool enforceBusinessLogic, DateTime? version = null) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Validate input
@@ -292,15 +303,15 @@ internal void SetValue(string key, string? value, bool? isDirty, bool enforceBus
         else if (originalAttribute.Value != value) {
           markAsDirty = true;
         }
-        var newAttribute = new AttributeValue(key, value, markAsDirty, enforceBusinessLogic);
+        var newAttribute = new AttributeValue(key, value, markAsDirty, enforceBusinessLogic, version);
         this[IndexOf(originalAttribute)] = newAttribute;
       }
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Create new attribute value
       \-----------------------------------------------------------------------------------------------------------------------*/
       else {
-        Add(new AttributeValue(key, value, isDirty ?? true, enforceBusinessLogic));
+        Add(new AttributeValue(key, value, isDirty ?? true, enforceBusinessLogic, version));
       }
 
     }
@@ -316,8 +327,8 @@ internal void SetValue(string key, string? value, bool? isDirty, bool enforceBus
     ///   <para>
     ///     If a settable property is available corresponding to the <see cref="AttributeValue.Key"/>, the call should be routed
     ///     through that to ensure local business logic is enforced. This is determined by looking for the "__" prefix, which is
-    ///     set by the <see cref="SetValue(String, String, Boolean?, Boolean)"/>'s enforceBusinessLogic parameter. To avoid an
-    ///     infinite loop, internal setters _must_ call this overload.
+    ///     set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?)"/>'s enforceBusinessLogic parameter. To
+    ///     avoid an infinite loop, internal setters _must_ call this overload.
     ///   </para>
     ///   <para>
     ///     Compared to the base implementation, will throw a specific <see cref="ArgumentException"/> error if a duplicate key
@@ -357,8 +368,8 @@ protected override void InsertItem(int index, AttributeValue item) {
     /// <remarks>
     ///   If a settable property is available corresponding to the <see cref="AttributeValue.Key"/>, the call should be routed
     ///   through that to ensure local business logic is enforced. This is determined by looking for the "__" prefix, which is
-    ///   set by the <see cref="SetValue(String, String, Boolean?, Boolean)"/>'s enforceBusinessLogic parameter. To avoid an
-    ///   infinite loop, internal setters _must_ call this overload.
+    ///   set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?)"/>'s enforceBusinessLogic parameter. To
+    ///   avoid an infinite loop, internal setters _must_ call this overload.
     /// </remarks>
     /// <param name="index">The location that the <see cref="AttributeValue"/> should be set.</param>
     /// <param name="item">The <see cref="AttributeValue"/> object which is being inserted.</param>
@@ -379,8 +390,8 @@ protected override void SetItem(int index, AttributeValue item) {
     /// <remarks>
     ///   If a settable property is available corresponding to the <see cref="AttributeValue.Key"/>, the call should be routed
     ///   through that to ensure local business logic is enforced. This is determined by looking for the "__" prefix, which is
-    ///   set by the <see cref="SetValue(String, String, Boolean?, Boolean)"/>'s enforceBusinessLogic parameter. To avoid an
-    ///   infinite loop, internal setters _must_ call this overload.
+    ///   set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?)"/>'s enforceBusinessLogic parameter. To
+    ///   avoid an infinite loop, internal setters _must_ call this overload.
     /// </remarks>
     /// <param name="originalAttribute">The <see cref="AttributeValue"/> object which is being inserted.</param>
     /// <param name="settableAttribute">

OnTopic/Topic.cs

@@ -635,7 +635,7 @@ public Topic? DerivedTopic {
     ///   called by the <see cref="AttributeValueCollection"/>. This is intended to enforce local business logic, and prevent
     ///   callers from introducing invalid data.To prevent a redirect loop, however, local properties need to inform the
     ///   <see cref="AttributeValueCollection"/> that the business logic has already been enforced. To do that, they must either
-    ///   call <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, Boolean)"/> with the
+    ///   call <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, Boolean, DateTime?)"/> with the
     ///   <c>enforceBusinessLogic</c> flag set to <c>false</c>, or, if they're in a separate assembly, call this overload.
     /// </remarks>
     /// <param name="key">The string identifier for the AttributeValue.</param>