The goal of LINQ is to provide a set of tools that improve code implementation by adapting to several different architectures, rather than changing application architectures.

Today, data managed by a program can originate from many and varied data sources, such as an array, an object graph, an XML document, a database, a text file, a registry key, an e-mail message, Simple Object Access Protocol (SOAP) message content, a Microsoft Office Excel file, and so forth. The list is extensive. LINQ makes it easier to access all these various kinds of data, providing a unified programming model. In fact, each data source has its own specific data-access model. When you need to query a database, you typically use SQL. You navigate XML data by using the Document Object Model (DOM) or XPath/XQuery. You iterate an array and build algorithms to navigate an object graph. You use specific application programming interfaces (APIs) to access other data sources, such as an Excel file, an e-mail message, or the Windows registry. Put briefly, you use different programming models to access different data sources.

The unification of data access techniques into a single comprehensive model has been attempted in many ways. For example, Open Database Connectivity (ODBC) providers allow you to query an Excel file as you would a Windows Management Instrumentation (WMI) repository. With ODBC, you use an SQL-like language to access data represented through a relational model. Sometimes, however, data is represented more effectively in a hierarchical or network model instead of a relational one. Moreover, if a data model is not tied to a specific language, you probably need to manage different type systems. All these differences create an “impedance mismatch” between data and code.

LINQ addresses these issues by offering a uniform method to access and manage data without forcing the adoption of a “one size fits all” model. LINQ makes use of common capabilities in the operations in different data models instead of flattening the different structures between them. In other words, by using LINQ, you keep existing heterogeneous data structures, such as classes or tables, but you gain a uniform syntax to query all these data types, regardless of their physical representation. Think about the differences between a graph of in-memory objects and relational tables with proper relationships. With LINQ, you can use the same query syntax on both models.

Here is a simple LINQ query for a typical software solution that returns the names of customers in Italy:

var query =
    from   c in Customers
    where  c.Country == "Italy"
    select c.CompanyName;

The result of this query is a list of strings. You can enumerate these values with a foreach loop in C#:

foreach ( string name in query ) {
    Console.WriteLine( name );
}

Both the query definition and the foreach loop are regular C# statements, valid for C# 3.0 or higher, but what is Customers? At this point, you might be wondering what it is we are querying. Is this query a new form of Embedded SQL? Not at all. You can apply the same query (and the foreach loop) to the following:

In fact, you can apply the query to many other kinds of data, as well, so long as you use each kind’s specific LINQ provider. For example, Customers could be a collection of objects:

Customer[] Customers;

Customers also could be an entity class that describes a physical table in a relational database:

DataContext db = new DataContext( ConnectionString );
Table<Customer> Customers = db.GetTable<Customer>();

Or, Customers could be an entity class that describes a conceptual model mapped to a relational database:

NorthwindModel dataModel = new NorthwindModel();
ObjectSet<Customer> Customers = dataModel.Customers;

And in SharePoint 2013, Customers could be an entity class that describes a collection of SPListItem types retrieved from an SPList of customers stored in SharePoint:

MySiteContext sp = new MySiteContext ( siteUri );
EntityList<Customer> Customers = sp.GetList<Customer>("Customers");

These examples highlight that the main goal of LINQ is to provide a unified querying and programming model—fully integrated with programming languages—that abstracts code from the underlying infrastructure.

Now you know that a LINQ query can target any kind of data source supported by a LINQ provider. But how does LINQ work? This section gives you a tour of what’s under its hood.

Suppose you write the following code that uses LINQ:

Customer[] Customers = GetCustomers();
var query =
    from   c in Customers
    where  c.Country == "Italy"
    select c;

From that query, the compiler generates this code:

Customer[] Customers = GetCustomers();
IEnumerable<Customer> query =
        Customers
        .Where( c => c.Country == "Italy" );

When the query becomes more complex, as you can see in the next example…

var query =
    from    c in Customers
    where   c.Country == "Italy"
    orderby c.Name
    select  new { c.Name, c.City };

The generated code is more complex, too:

var query =
        Customers
        .Where( c => c.Country == "Italy" )
        .OrderBy( c => c.Name )
        .Select( c => new { c.Name, c.City } );

The code calls instance members on the object returned from the previous call. It calls Where on Customers; OrderBy on the object returned by Where; and finally, Select on the object returned by OrderBy. This behavior is regulated by what are known as extension methods in the host language (C# in this case). The implementation of the Where, OrderBy, and Select methods—called by the sample query—depends on the type of Customers and on namespaces specified in relevant using statements. Extension methods are a fundamental syntax feature used by LINQ so that it can maintain the same syntax across different data sources.

The basic concept behind LINQ is that queries target objects that implement either the IEnumerable<T> interface for in-memory data or the IQueryable<T> interface for data retrieved from an external store. Here’s the definition of the IEnumerable<T> interface:

public interface IEnumerable<T> : IEnumerable {
    IEnumerator<T> GetEnumerator();
}

And here’s the definition of the IQueryable<T> interface, together with its base interface, IQueryable:

public interface IQueryable<T> : IEnumerable<T>, IQueryable, IEnumerable {
}
public interface IQueryable : IEnumerable {
    Type ElementType { get; }
    Expression Expression { get; }
    IQueryProvider Provider { get; }
}

Whenever you browse for (enumerate) the results of a query—for example, by using a foreach statement—the compiler invokes the GetEnumerator method of the IEnumerable<T> interface, and at that point the query is effectively executed.

When the target object of your query implements only the IEnumerable<T> interface, the extension methods targeting that type will work against in-memory objects. For example, LINQ to Objects and LINQ to XML both work in this way.

However, when the query target object implements IQueryable<T>, the extension methods construct an expression tree, which describes the query from a provider-independent point of view. The expression tree is then processed by the IQueryable implementation of the query target object, invoking the IQueryProvider object published by the IQueryable.Provider property. The query provider visits the expression tree, using an expression visitor, and produces a query syntax that targets the concrete persistence storage.

For example, as shown in Figure 6-2, for a LINQ to SQL query engine, the query provider will generate a T-SQL query that corresponds to the LINQ query you defined in your .NET code. Similarly, when using LINQ to SharePoint, the query provider generates a CAML (Collaborative Application Markup Language) query that will be executed against the target SPList using the standard Server Object Model querying syntax.

Figure 6-2. A graphical representation of how LINQ providers work.

To insert a new item into a list, you first create the item instance, just as you would with any .NET object. Next, you need to configure its properties, and finally, you need to add the new item to its parent list and submit changes to the content database. The code in Inserting a new item in a list using LINQ to SharePoint illustrates this process.

 using (DevbookDataContext spContext = new
   DevbookDataContext("http://devbook.sp2013.local/")) {
    DevLeapCustomer newCustomer = new DevLeapCustomer {
        Title = "Andrea Pialorsi",
        ContactID = "AP001",
        CompanyName = "DevLeap",
        Country = Country.Italy,
        CustomerLevel = CustomerLevel.LevelA,
    };
    spContext.DevLeapContacts.InsertOnSubmit(newCustomer);
    spContext.SubmitChanges();
}

The key point of this example, aside from the SubmitChanges method invocation that you have already seen, is the call to the InsertOnSubmit method of the EntityList<T> class that lies behind the DevLeapContacts property of the DataContext. The InsertOnSubmit method accepts an item to be inserted into the target list as soon as you invoke SubmitChanges. The entity passed to the method will acquire a state of ToBeInserted. Note that the InsertOnSubmit method is fully typed according to the generic type T of the EntityList<T> class. Thus, in Inserting a new item in a list using LINQ to SharePoint you can invoke this method by providing a class of type DevLeapContact or any type inherited from DevLeapContact, such as DevLeapCustomer or DevLeapSupplier.

The EntityList<T> class also provides an InsertAllOnSubmit method, which lets you insert a group of entities instead of a single entity. This last method requires an argument of type IEnumerable<T>, representing the collection of items to insert.

Deleting an item is much like inserting a new item. The EntityList<T> class provides a DeleteOnSubmit method, as well as a DeleteAllOnSubmit method, similar to the methods presented in the preceding section. The former accepts a single item to delete, whereas the latter accepts a collection of type IEnumerable<T>, representing the items to delete. Both of these methods permanently delete the target items from the content database when you confirm the action by invoking SubmitChanges. SharePoint provides a Recycle Bin feature, so the EntityList<T> class also provides a couple of methods specifically intended to move items into the Recycle Bin, instead of permanently deleting them. These methods are RecycleOnSubmit and RecycleAllOnSubmit. Deleting or recycling an item from a list using LINQ to SharePoint shows a code excerpt that illustrates how to delete or recycle an item.

 using (DevbookDataContext spContext = new DevbookDataContext(
    "http://devbook.sp2013.local/")) {
    var contact = (from c in spContext.DevLeapContacts
                    where c.ContactID == "AP001"
                    select c).FirstOrDefault();
    // Let's see if we found the target contact
    if (contact != null) {
        if (recycle) {
            spContext.DevLeapContacts.RecycleOnSubmit(contact);
        }
        else {
            spContext.DevLeapContacts.DeleteOnSubmit(contact);
        }
        spContext.SubmitChanges();
    }
}

Whenever you have a data management infrastructure that works when disconnected from the source repository, you will inevitably face concurrency conflicts. In fact, every single time you insert, update, or delete/recycle any data, you are working with an in-memory copy of the content; therefore, you have no guarantee that your changes will be effectively confirmed by the back-end store when you invoke SubmitChanges. For example, when you retrieve an item from a list to change its properties, someone else might change that same item concurrently. Moreover, your code can be executed multiple times concurrently when you are in a high-traffic solution. Thus, when you try to apply your changes to the back-end repository, it will throw a concurrency conflict exception.

Fortunately, LINQ to SharePoint has established and complete support for concurrency conflicts. In fact, the SubmitChanges method has three overloads:

public void SubmitChanges();
public void SubmitChanges(ConflictMode failureMode);
public void SubmitChanges(ConflictMode failureMode, bool systemUpdate);

At this point, the first overload should be familiar (you have seen it in many of the previous code listings). Both the second and the third overloads accept an argument of type ConflictMode, which is an enum defined in the following excerpt:

public enum ConflictMode {
    ContinueOnConflict,
    FailOnFirstConflict
}

The names of the available values reveal their purposes:

When you submit changes to the content database and a change conflict occurs, you can catch a ChangeConflictException, which contains a description tightly bound to SharePoint’s typical web scenario. As an example, here’s the Message property for a concurrency conflict exception:

Database values have been updated since the client last read them.

To solve conflicts, you can browse the ChangeConflicts property of the DataContext class instance. This property is a collection of objects of type ObjectChangeConflict, which you can enumerate to inspect all conflicting items. Every ObjectChangeConflict instance exposes a property named Object, of type System.Object, that references the current conflicting item. You can cast that property to the real target entity instance. In addition, you can inspect the conflicting members of the current conflicting item by enumerating the MemberConflicts property of every ObjectChangeConflict instance. Finally, each element of the MemberConflicts collection is of type MemberChangeConflict and provides you with some detailed information about the member conflict. For example, you can see the member name and type, the original value of the member when you retrieved the entity from the SharePoint content database, the current value in memory, and the actual value in the content database.

With that information, to solve concurrency issues, you need to invoke the Resolve method, which has several overloads for both ObjectChangeConflict and MemberChangeConflict values. In essence, the Resolve method lets you determine which values win—those of the current user or those in the content database (the other concurrent user).

Here are the overloads for the Resolve method of the ObjectChangeConflict class:

public void Resolve();
public void Resolve(RefreshMode refreshMode);
public void Resolve(RefreshMode refreshMode, bool autoResolveDeletes);

The RefreshMode argument is the most interesting part of these method overloads because it determines how to resolve conflicts. RefreshMode is an enum type, defined as follows:

public enum RefreshMode {
    KeepChanges,
    KeepCurrentValues,
    OverwriteCurrentValues
}

The ObjectChangeConflict.Resolve method changes its behavior depending on the RefreshMode value you provide:

The first overload of ObjectChangeConflict.Resolve internally assumes a value of KeepChanges for its RefreshMode argument. The third overload accepts a Boolean argument named autoResolveDeletes, which when false, instructs the entity tracking engine to throw an InvalidOperationException if a target item has been deleted.

Table 6-3 contains a matrix of possible values, which helps to explain the behavior of the ObjectChangeConflict.Resolve method.

The MemberChangeConflict.Resolve method works almost the same as the one provided by the ObjectChangeConflict class. However, it affects only one member at time, instead of the whole entity. It also has a couple of overloads:

public void Resolve(RefreshMode refreshMode);
public void Resolve(object value);

The first overload works exactly the same as the ObjectChangeConflict method, but affects only the current member. The second overload lets you provide a custom value to force onto the content database. Thus, in this last case, you can completely change the final value of the member, providing a new value that’s different from the current, original, or database values.

Lastly, there is also a ResolveAll method provided by the ChangeConflictCollection class. It is useful when you want to solve all conflicts in one shot by applying the same conflict resolution logic to all the conflicts.

Concurrency conflict management using LINQ to SharePoint shows a complete code example of managing concurrency conflicts in LINQ to SharePoint.

 using (DevbookDataContext spContext = new
   DevbookDataContext("http://devbook.sp2013.local/")) {
    var contacts = from c in spContext.DevLeapContacts
                    where c.Country == Country.Italy
                    select c;
    String conflictingItemID = contacts.FirstOrDefault().ContactID;
    foreach (var item in contacts) {
        item.CompanyName += String.Format(" - Changed on {0}", DateTime.Now);
    }
    // Before submitting changes, the code simulates concurrency
    // changing one of the items from another DataContext
    using (DevbookDataContext spContextOther =
        new DevbookDataContext("http://devbook.sp2013.local/")) {
        var conflictingItem = (from c in spContextOther.DevLeapContacts
                                where c.ContactID == conflictingItemID
                                select c).FirstOrDefault();
        conflictingItem.Country = Country.USA;
        spContextOther.SubmitChanges();
    }
    try {
        spContext.SubmitChanges(ConflictMode.ContinueOnConflict)
    }    catch (ChangeConflictException ex) {
        Console.WriteLine(ex.Message);
        // Browse for conflicting items
        foreach (var conflict in spContext.ChangeConflicts) {
            // Check if the item has been deleted by
            // someone else
            if (conflict.IsDeleted) {
                Console.WriteLine("Unfortunately the item has been deleted, " +
                   "so your changes cannot be submitted!");
            }
            else {
                // Retrieve a typed reference to the conflicting item
                DevLeapContact contact = conflict.Object as DevLeapContact;
                // If the item is a DevLeapContact
                if (contact != null) {
                    Console.WriteLine("Contact with ID {0} is in conflict!",
                       contact.ContactID);
                    // Browse for conflicting members
                    foreach (var member in conflict.MemberConflicts) {
                        Console.WriteLine("Member {0} is in conflict.
	" +
                        "Current Value: {1}
	Original Value: " +
                        "{2}
	Database Value: {3}",
                            member.Member.Name,
                            member.CurrentValue,
                            member.OriginalValue,
                            member.DatabaseValue);
                    }
                    Console.WriteLine("Make your choice: Override Database " +
                      "Value (Y) or Skip your Current Values (N)?");
                    String choice = Console.ReadLine().ToLower();
                    switch (choice) {
                        case "y":
                        case "yes":
                            conflict.Resolve(RefreshMode.KeepChanges, true);
                            break;
                        case "n":
                        case "no":
                            conflict.Resolve(RefreshMode.OverwriteCurrentValues,
                               true);
                            break;
                        default:
                            break;
                    }
                }
            }
        }
        spContext.SubmitChanges();
    }
}

Concurrency conflict management using LINQ to SharePoint uses a couple of DataContext instances to simulate a concurrency conflict. It asks the end user, via a console-based UI, how to solve the generated conflict. It also demonstrates that LINQ to SharePoint provides a rich set of capabilities for resolving concurrency conflicts, making it a mature technology suitable for real-world business solutions.

At the base of every O/RM framework, there is an engine—generally called an identity management service—that avoids having duplicate in-memory instances of the same entity. LINQ to SharePoint also provides such a service. Consider the sample code in Code excerpt that illustrates identity management service behavior.

 using (DevbookDataContext spContext = new DevbookDataContext(
    "http://devbook.sp2013.local/")) {
    var contacts = from c in spContext.DevLeapContacts
                   where c.CompanyName.Contains("DevLeap")
                   select c;
    // Change the Country property of the first contact
    contacts.FirstOrDefault().Country = Country.USA;
    // Show all the retrieved contacts
    foreach (var c in contacts) {
        Console.WriteLine("Customer with ID {0} has a Country value of {1}",
            c.ContactID, c.Country);
    }
    Console.WriteLine("------------------");
    // Retrieve the same contacts with another LINQ query
    var otherContacts = from c in spContext.DevLeapContacts
                        where c.CompanyName.Contains("DevLeap")
                        select c;
    // Show all the newly retrieved contacts
    foreach (var c in otherContacts) {
        Console.WriteLine("Customer with ID {0} has a Country value of {1}",
            c.ContactID, c.Country);
    }
    // Check if the two first contacts instances are the same contact
    Console.WriteLine("Do the contacts have the same HashCode? {0}",
        contacts.FirstOrDefault().GetHashCode() ==
            otherContacts.FirstOrDefault().GetHashCode());
}

The code retrieves the contacts whose CompanyName field contains “DevLeap” from the DevLeap Contacts list, and changes the Country property of the first contact to USA. A second LINQ query retrieves the same list of contacts to check whether the result comes from the content database or from existing in-memory instances. To determine which, the code writes the Country value of every retrieved contact and compares the HashCode values of the first two instances of the retrieved contacts.

The following code is the output generated by Code excerpt that illustrates identity management service behavior at the console window:

Customer with ID PP001 has a Country value of USA
Customer with ID AP001 has a Country value of Italy
------------------
Customer with ID PP001 has a Country value of USA
Customer with ID AP001 has a Country value of Italy
Do the contacts have the same HashCode? True

Not surprisingly, the entities are the same; in other words, the modified contact instance takes precedence over the instance retrieved from the content database. In fact, under the covers, LINQ to SharePoint queries the content database twice, the first time executing the former query, and the second time the latter. However, because the entities requested by the second query are already in memory, the identity management service skips the data from the content database and uses the data of the existing in-memory instances instead. You might be wondering why it still executes the database query rather than using the in-memory data directly without stressing the database. The reason is that the engine merges the results retrieved from the database with any existing in-memory entities. If there are more items in the database than in memory, the engine will merge the new ones from the database and the rest that are already in memory. This is good behavior because it avoids duplication of data and instances.

Given this behavior, you’re probably wondering how you can refresh an entity from the content database, skipping any existing in-memory instance. To do that, you can use a different DataContext instance, as long as you do not have to use the same DataContext instance. Otherwise, you can call the DataContext class’s Refresh method, which has these overloads:

public void Refresh(RefreshMode mode, IEnumerable entities);
public void Refresh(RefreshMode mode, params object[] entities);
public void Refresh(RefreshMode mode, object entity);

All of these overloads accept an argument of type RefreshMode, which you may remember from the “Handling concurrency conflicts” section. Depending on the value you choose for the RefreshMode argument, the Refresh method will either forcibly reload data from the content database (OverwriteCurrentValues) or merge your changed values with those in the content database (KeepChanges). Generally, the value of KeepCurrentValues is not very useful when provided to the Refresh method, because it simply forces the entities to use the values already in memory.

In software solutions with a distributed architecture, you sometimes need to serialize an entity, transfer it across the wire to a remote site or consumer, and eventually get it back to update the persistent storage. When your data is stored in SharePoint, LINQ to SharePoint becomes an interesting solution for working in a disconnected manner. In fact, when you generate the entity model with SPMetal.exe and provide it with the /serialization:unidirectional command-line argument, the tool will mark all the generated entities with the DataContract attribute of the .NET runtime serialization engine. Consequently, you can serialize your entities and use them, for example, as the content of a Windows Communication Foundation (WCF) message.

Serializing a LINQ to SharePoint DevLeapContact entity shows a code excerpt that serializes a LINQ to SharePoint entity.

 using (DevbookDataContext spContext = new DevbookDataContext(
    "http://devbook.sp2013.local/")) {
    spContext.DeferredLoadingEnabled = false;
    var contact = (from c in spContext.DevLeapContacts
                    where c.ContactID == "PP001"
                    select c).FirstOrDefault();
    // Let's see if we found the target contact
    if (contact != null) {
        // Prepare a DataContractSerializer instance
        DataContractSerializer dcs = new
           DataContractSerializer(typeof(DevLeapContact),
            new Type[] { typeof(DevLeapCustomer), typeof(DevLeapSupplier) });
        // Serialize the object graph
        using (XmlWriter xw = XmlWriter.Create(Console.Out)) {
            dcs.WriteObject(xw, contact);
            xw.Flush();
        }
    }
}

Note the line that disables DeferredLoadingEnabled. This is done to avoid circular references during entity serialization. The XML produced to serialize a DevLeapContact entity with DataContractSerializer shows the XML produced by the DataContractSerializer engine.

<?xml version="1.0"?>
<DevLeapContact xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
  i:type="DevLeapCustomer"
  xmlns="http://schemas.datacontract.org/2004/07/DevLeap.SP2013.Linq2SP">
    <_entityState>Unchanged</_entityState>
    <_id>1</_id>
    <_originalValues xmlns:d2p1=
      "http://schemas.microsoft.com/2003/10/Serialization/Arrays" i:nil="true" />
    <_path>/Lists/DevLeap Contacts</_path>
    <_title>Paolo Pialorsi</_title>
    <_version>19</_version>
    <_companyName>DevLeap</_companyName>
    <_contactID>PP001</_contactID>
    <_country>Italy</_country>
    <_invoicesDocument xmlns:d2p1=
      "http://schemas.datacontract.org/2004/07/Microsoft.SharePoint.Linq">
        <d2p1:Loaded>true</d2p1:Loaded>
        <d2p1:entities />
    </_invoicesDocument>
    <_customerLevel>LevelB</_customerLevel>
</DevLeapContact>

The XML stream contains the basic private fields of the entity, its original values, and the entity state. Thus, the XML produced is not an ideal solution for an interoperable cross-platform solution, but can be used to connect WCF consumers with WCF services (from .NET to .NET).

When the consumer makes changes to the received serialized entities and sends them back to the server, you can use the Attach method of the EntityList<T> class on the service side to reattach the entity to the DataContext and update the content database. Here’s the signature of this method:

public void Attach(TEntity entity);

This method simply accepts the entity to attach back to the DataContext tracking engine.

A final topic to cover here relates to managing model extensions and entity versioning. Let’s start with a couple of examples. Imagine that you have a well-defined LINQ to SharePoint model, such as the one created at the beginning of this chapter. At some point, a power user changes the data schema you provisioned, adding a custom column—such as a new Address column—to the DevLeapCustomer content type. To be able to see this new property, you should refresh the model via SPMetal.exe, which will then update the entity definition. However, it is not always possible to update the entity model and refresh all deployed assemblies.

Now consider a situation in which you have a content type that uses a custom field type, developed with .NET code and Visual Studio 2012, and you want to use that content type with LINQ to SharePoint. Unfortunately, SPMetal.exe does not support custom field types. Thus, you need to autonomously manage the code for reading and writing the custom field type.

To manage these situations but still use LINQ to SharePoint, you can implement the ICustomMapping interface for entities that you want to extend or update. This interface was specifically designed to support you when extending LINQ to SharePoint entities. Here’s its definition:

public interface ICustomMapping {
    void MapFrom(object listItem);
    void MapTo(object listItem);
    void Resolve(RefreshMode mode, object originalListItem, object databaseListItem);
}

The MapFrom and MapTo methods both receive an argument of type Object, which internally is an SPListItem instance that corresponds to the native SharePoint item behind the current entity. Using the MapFrom method, you can read untyped values from the low-level SPListItem instance and use them to configure a property—or whatever you want—in the entity. The MapTo method writes these properties back to the underlying SPListItem object. The Resolve method is a conflict resolution method similar to the ObjectChangeConflict and MemberChangeConflict methods you’ve already seen; however, in this case, it is up to the project developer to define the concurrency conflict behavior. Implementing the ICustomMapping interface shows a custom entity type created using SPMetal.exe and extended using the ICustomMapping interface.

 internal partial class DevLeapCustomer : ICustomMapping {
    private String _address;
    public String Address {
        get { return (this._ address); }
        set { this._ address = value; }
    }
    [CustomMapping(Columns = new String[] { "*" })]
    public void MapFrom(object listItem) {
        SPListItem item = listItem as SPListItem;
        if (item != null) {
            this.Address = item["address"].ToString();
        }
    }
    public void MapTo(object listItem) {
        SPListItem item = listItem as SPListItem;
        if (item != null) {
            item["address "] = this.Address;
        }
    }
    public void Resolve(RefreshMode mode, object originalListItem,
       object databaseListItem) {
        // Code omitted for the sake of brevity
    }
}

Note the CustomMapping attribute applied on top of the MapFrom method. This is an attribute that identifies new columns mapped with the MapFrom method. It requires an array of InternalName values of supported columns. In this example, the CustomMapping attribute accepts any kind of new column (through the use of *) in order to be useful in case of versioning.