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: http://spentity.codeplex.com). 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
{
[Field("Field1")]
public int Property1 { get; set; }
[Field("Field2")]
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.
Conversion
Following code snippet shows how to read a SharePoint List Item to an entity:
SPListItem item = DoSomethingToGetListItem();
Sample entity = new SampleEntity();
entity.Read(item)
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:
entity.Property1++;
entity.Write(item);
item.Update();
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.