In the past when I've built web based applications Automapper was always one of those libraries that I both loved and hated at the same time. In the Dynamics CRM world it can often be a bit of a dangerous tool to unleash on a website, especially when utilised by developers that don't know CRM very well. Let me explain why.
Attribute Collections
Most CRM Developers will already know what I'm talking about here, but for those of you not privy to this - the properties of an entity from a CRM database table are not actually surfaced quite like EntityFramework or nHibernate, they are surfaced using a dictionary. This is subsequently wrapped in an Attribute Collection. One of the main advantages of this is you can control partial updates/retrieves without worrying about the state of the entire entity. On the negative side this plays havoc when libraries like Automapper are used to populate the entities, especially when using early bound objects.
Here's a sample to give you and idea of what I'm getting at. Firstly, let's presume our domain models are Early Bound objects exported from dynamics. (self plug! Personally I use this open source tool : https://github.com/conorjgallagher/Dynamics.ExtendedSvcUtil).
Now, let's say we have an REST service and we want to utilise it to update an account. So we build a view model like this:
public class AccountViewModel
{
public Guid Id { get; set; }
public string Name { get; set; }
public string Address1_Line1 { get; set; }
}
And we wire up automapper to map that across to our domain entity. In the latest version I believe that would look like this:
CreateMap<Account, AccountViewModel>().ReverseMap()
In this example we can create a new account via the this REST service with the following JSON:
{
Id: "aef7b4c1-98f6-4f53-9be3-2fa72d1e319d",
Name: "Hello",
Address1_Line1: "Home!"
}
Within our controller we will receive an AccountViewModel populated with all the relevant data. We can then use Automapper to push this View Model into an early bound Account entity using the same method as above. As long as all the field names match we're good to go. Even though you are mapping to strongly typed fields what you end up with under the hood is an dictionary like this:
"accountid"="aef7b4c1-98f6-4f53-9be3-2fa72d1e319d"
"name"="Hello"
"address1_line1"="Home!"
Null vs Unset
A really nice feature of CRM is it differentiates between null and unset. If you exclude a field from the attribute collection it will also be excluded from the update statement that hits SQL. This is very useful for performance and limiting what plugins / workflows fire.
Back to Automapper and our view models above - a problem arises when you exclude fields from the JSON. For example, if you subsequently send the following after the previous update:
{
Id: "aef7b4c1-98f6-4f53-9be3-2fa72d1e319d",
Address1_Line1: "Home line 1!"
}
This will hit our view model as this:
{
Id = "aef7b4c1-98f6-4f53-9be3-2fa72d1e319d",
Name = null,
Address1_Line1 = "Home line 1!"
}
Which I guess is expected, because how else can you represent an excluded value in the view model? If we don't deal with this we hit a more fundamental issue further down the chain in that our attribute collection will end up like this:
"accountid"="aef7b4c1-98f6-4f53-9be3-2fa72d1e319d"
"name"=null
"address1_line1"="Home line 1!"
And we'll blank our account name in CRM. Not good!
Excludable
This takes me on to a pattern I would like to propose for this type of issue: the concept of an excludable property. Looking at how nullable value types work surely we can come up with a similar concept! I won't take you through the entire evolution, but here is the interface and struct I now propose:
public interface IExcludable
{
bool Include { get; set; }
}
public struct Excludable<T> : IExcludable
{
private bool hasValue;
internal T value;
private bool include;
public Excludable(T value)
{
this.value = value;
if (value != null)
{
this.hasValue = true;
}
else
{
this.hasValue = false;
}
this.include = true;
}
public bool HasValue
{
get
{
return hasValue;
}
}
public bool Include
{
get { return include; }
set { include = value; }
}
public T Value
{
get
{
return value;
}
}
public T GetValueOrDefault()
{
return value;
}
public T GetValueOrDefault(T defaultValue)
{
return hasValue ? value : defaultValue;
}
public override bool Equals(object other)
{
if (!include || !hasValue) return other == null;
if (other == null) return false;
return value.Equals(other);
}
public override int GetHashCode()
{
return hasValue ? value.GetHashCode() : 0;
}
public override string ToString()
{
return hasValue ? value.ToString() : "";
}
public static implicit operator Excludable<T>(T value)
{
return new Excludable<T>(value);
}
public static explicit operator T(Excludable<T> value)
{
return value.Value;
}
public static bool operator ==(Excludable<T> x, T y)
{
return x.Equals(y);
}
public static bool operator !=(Excludable<T> x, T y)
{
return !x.Equals(y);
}
}
Overriding all the comparisons were required to get it to perform both value and null comparisons correctly. Finally, we can change our view model to use this instead:
public class AccountViewModel
{
public Excludable<Guid> Id { get; set; }
public Excludable<string> Name { get; set; }
public Excludable<string> Address1_Line1 { get; set; }
}
Json Converter gotcha
There's 1 final problem we need to solve that I'll highlight now. If we run our object without the address in it all seems to work just fine. Our property comes through as excluded as expected. But, if we instead try set it to null it is marked as included=false! The reason is down to how the JSON formatter deserializes the data into the given object. It doesn't actually call your constructor but does something dirty under the hood. How do we fix this? Create a custom json converter
public sealed class ExcludableConverter : JsonConverter
{
public override bool CanConvert(Type objectType)
{
return objectType.IsGenericType && objectType.GetGenericTypeDefinition() == typeof(Excludable<>);
}
public override bool CanWrite { get { return false; } }
public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
{
return Activator.CreateInstance(objectType, reader.Value);
}
public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
{
throw new NotImplementedException();
}
}
And set this up on application start within your global.asax:
var formatters = GlobalConfiguration.Configuration.Formatters;
var jsonFormatter = formatters.JsonFormatter;
var settings = jsonFormatter.SerializerSettings;
jsonFormatter.SerializerSettings.Converters.Add(new ExcludableConverter());
Now, when a null comes in we explicitly tell the converter to create a new object for us.
Wiring up Automapper
The final step is getting automapper to utilise this new way of excluding items. In automapper you can set a condition when mapping so that you can do conditional ignores. I found the simplest way to add this rule was write an extension method:
public static void AddExcludableRule<S, D>(this IMappingExpression<S, D> m)
{
m.ForAllMembers(opt => opt.Condition(
s =>
!(s.SourceValue is IExcludable) || ((IExcludable)s.SourceValue).Include
));
}
Now, whenever I want to wire up an object that has excludables I just add that call to the end:
CreateMap<Account, AccountViewModel>().ReverseMap().AddExcludableRule();
