SharePoint Entity Framework 1 - Introduction
2 min read

SharePoint Entity Framework 1 - Introduction

SharePoint Entity Framework is an open source class library used for converting between SharePoint List Item and custom entity class (Project homepage: Using SharePoint Entity Framework, you can read the field values from SharePoint List Item to corresponding properties of entity, or write the property values of entity to the corresponding Fields of SharePoint List Item. All you need is write a simple entity class. And in most cases, you don’t need to care about the conversion logic. SharePoint Entity Framework can greatly improve your coding productivity, and make your code more robust.

Supported Types

SharePoint Entity Framework supports most SharePoint built-in Field types and their corresponding CLR types. Following table lists all the supported types:

SharePoint Field Type CLR Type
Single line of text StringGuid, Guid?
Multiple lines of text string
Choice Custom Enum type and it’s nullable form
Number int, int?double, double?
Currency decimal, decimal?
Date and Time DateTime, DateTime?
Yes/No bool, bool?
Hyperlink or Picture UriStringCustom type
Person or Group SPUser, SPUser[], List<SPUser>int, int[], List<int>string, string[], List<string>Custom type and it’s collection form
Lookup int, int[], List<int>string, string[], List<string>Custom type and it’s collection form

Base class

SharePoint Entity Framework requires entity class must derive from the base class Entity(located in WindStyle.SPEntity namespace).

Following table lists the default properties provided by Entity class:

Name Type Description
SPListItemId int Identity of corresponding list item
SPListItemUniqueId Guid Unique identity of corresponding list item
SPParentListId Guid Unique identity of the parent list of corresponding list item
SPParentWebId Guid Unique identity of the parent web of corresponding list item
SPParentSiteId Guid Unique identity of the parent site collection of corresponding list item
Title string Title of corresponding list item

Following table lists the default methods provided by Entity class:

Method Return value Description
Read(SPListItem) void Read the SharePoint List Item to entity
Write(SPListItem) void Write the entity to SharePoint List Item

Writing a simple entity class

Let’s write a simple entity class:

using WindStyle.SPEntity;
using WindStyle.SPEntity.Attributes;

public class SampleEntity : Entity
public int Property1 { get; set; }

public string Property2 { get; set; }

SampleEntity class contains two properties: Property1 and Property2. Both of them decorated by FieldAttribute. When converting, SharePoint Entity Framework will find the corresponding field in the list item by the internal name of the field specified in FieldAttribute.


Following code snippet shows how to read a SharePoint List Item to an entity:

SPListItem item = DoSomethingToGetListItem();
Sample entity = new SampleEntity();

After the property updated, we can call the Write method of the entity if we need to write it back to SharePoint List Item. As following code snippet shows:


Bulk conversion

SharePoint developers are very familiar with SPListItemCollection, SharePoint Entity Framework provide a Utilities class with two method to help us converting a SPListItemCollection object to an entity collection:

Method Return value Description
AsEnumerable(SPListItemCollection) IEnumerable<SPListItem> Convert SPListItemCollection to IEnumerable<SPListItem>
Convert<T>(IEnumerable<SPListItem>, SPRegionalSettings) IEnumerable<T> Convert IEnumerable<SPListItem> to IEnumerable<T>

Both of above methods are implemented as extension method for facilitating invoking. Following code shows how to use them:

SPListItemCollection items = DoSomethingToGetListItems();
SampleEntity[] entities = items.AsEnumerable().Convert<SampleEntity>().ToArray();

SharePoint Entity Framework is designed to help developers quickly converting between SharePoint List Item and entity class. Therefore, It provides supports for most common types and makes the API as simple and friendly as possible.

For simple scenarios,  the code you need to write may not much more than above code snippets. SharePoint Entity Framework also provides the extension mechanisms to support the complex scenarios, please read the follow-up articles.