Introduced [DisableMapping] functionality to TopicMappingService

The `[DisableMapping]` capability was originally introduced as part of the `ReverseTopicMappingService`, to instruct it not to map particular properties back the target `Topic` entity. There's no reason the opposite shouldn't also be supported on the `TopicMappingService`—nor is it all that difficult to add this feature. That said, while this feature was a necessity on the `ReverseTopicMappingService` (since it will throw an exception if a corresponding `AttributeDescriptor` can't be found) it provides less necessity on the `TopicMappingService` (since a missing attribute will simply skip over the property). Still, this may be useful for cases where a property should be provided which maps to a valid attribute, but the value should be set separately—perhaps as part of a hard-coded default. While a rare edge case, it's just a few lines of code to support this, and it eliminates the attributes supported on the `ReverseTopicMappingService` but not also the `TopicMappingService`, thus simplifying the documentation.

Author: JeremyCaney

OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs

@@ -39,6 +39,7 @@ public FakeViewModelLookupService() : base(null, typeof(object)) {
       Add(typeof(DefaultValueTopicViewModel));
       Add(typeof(DescendentSpecializedTopicViewModel));
       Add(typeof(DescendentTopicViewModel));
+      Add(typeof(DisableMappingTopicViewModel));
       Add(typeof(FilteredTopicViewModel));
       Add(typeof(FlattenChildrenTopicViewModel));
       Add(typeof(InheritedPropertyTopicViewModel));

OnTopic.Tests/TopicMappingServiceTest.cs

@@ -103,6 +103,25 @@ public async Task Map_Dynamic_ReturnsNewModel() {
 
     }
 
+    /*==========================================================================================================================
+    | TEST: MAP: DISABLED PROPERTY: RETURNS NULL
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Establishes a <see cref="TopicMappingService"/> and tests whether it maps a property decorated with the <see
+    ///   cref="DisableMappingAttribute"/>.
+    /// </summary>
+    [TestMethod]
+    public async Task Map_DisabledProperty_ReturnsNull() {
+
+      var topic                 = TopicFactory.Create("Test", "DisableMapping");
+
+      var viewModel             = await _mappingService.MapAsync<DisableMappingTopicViewModel>(topic).ConfigureAwait(false);
+
+      Assert.IsNotNull(viewModel);
+      Assert.IsNull(viewModel.Key);
+
+    }
+
     /*==========================================================================================================================
     | TEST: MAP: PARENTS: RETURNS ASCENDENTS
     \-------------------------------------------------------------------------------------------------------------------------*/

OnTopic.Tests/ViewModels/DisableMappingTopicViewModel.cs

@@ -0,0 +1,26 @@
+/*==============================================================================================================================
+| Author        Ignia, LLC
+| Client        Ignia, LLC
+| Project       Topics Library
+\=============================================================================================================================*/
+using OnTopic.Mapping.Annotations;
+
+namespace OnTopic.Tests.ViewModels {
+
+  /*============================================================================================================================
+  | VIEW MODEL: DISABLE MAPPING
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   Provides a simple view model with a single property (<see cref="Key") which is annotated with the <see
+  ///   cref="DisableMappingAttribute"/>.
+  /// </summary>
+  /// <remarks>
+  ///   This is a sample class intended for test purposes only; it is not designed for use in a production environment.
+  /// </remarks>
+  public class DisableMappingTopicViewModel {
+
+    [DisableMapping]
+    public string? Key { get; set; }
+
+  } //Class
+} //Namespace

OnTopic/Mapping/README.md

@@ -104,9 +104,7 @@ To support the mapping, a variety of `Attribute` classes are provided for decora
 - **`[Follow(relationships)]`**: Instructs the code to populate the specified relationships on any view models within a collection.
 - **`[Flatten]`**: Includes all descendants for every item in the collection. If the collection enforces uniqueness, duplicates will be removed.
 - **`[MapToParent]`**: Allows the attributes of a topic to be applied to a child complex object, optionally including a prefix.
-
-### `ReverseTopicMappingService`
-- **`[DisableMapping]`**: Prevents the `ReverseTopicMappingService` from attempting to map the property back to the target `Topic`.
+- **`[DisableMapping]`**: Prevents the mapping service from attempting to map the property to an attribute.
 
 ### Example
 The following is an example of a data transfer object that implements the above attributes:

OnTopic/Mapping/TopicMappingService.cs

@@ -264,7 +264,10 @@ protected async Task SetPropertyAsync(
       /*------------------------------------------------------------------------------------------------------------------------
       | Handle by type, attribute
       \-----------------------------------------------------------------------------------------------------------------------*/
-      if (SetCompatibleProperty(source, target, configuration)) {
+      if (configuration.DisableMapping) {
+        return;
+      }
+      else if (SetCompatibleProperty(source, target, configuration)) {
         //Performed 1:1 mapping between source and target
       }
       else if (_typeCache.HasSettableProperty(target.GetType(), property.Name)) {