SharePoint Entity Framework 2 – Attributes

The previous article introduced how to associate properties of entity class and SharePoint List Item. We can use FieldAttribute, that is the most easy way, and suitable for most scenarios. This article will introduce other usages of FieldAttribute, and other attributes that used for association.

Choice and Enum

SharePoint Entity Framework will convert Choice field to custom enum type. Thus we need a approach to mapping each options of Choice field to  the member of custom enum type. That is done by using EnumMemberAttribute (All attributes classes of SharePoint Entity Framework are located in WindStyle.SPEntity.Attributes namespace).

Presume SharePoint List contains a field named Field3Field3 is a Choice field, contains three options: Option #1, Option #2 and Option #3. We can write a custom enum type, as shown below:

using WindStyle.SPEntity.Attributes;

[Flags]
public enum Choice
{
None = 0,
[EnumMember("Option #1")]
Option1 = 1,
[EnumMember("Option #2")]
Option2 = 2,
[EnumMember("Option #3")]
Option3 = 4
}

Next, let’s add a property in the SampleEntity class written in previous article:

[Field("Field3")]
public Choice Property3 { get; set; }

If the List Item we want to convert has a Field3 field with value Option #2, then after entity.Read method executed, the value of entity.Property3 will be Choice.Option2.

SharePoint Entity Framework also can convert between multi-value enum and multi-option Choice field, as shown below:

entity.Property3 = Choice.Option1 | Choice.Option3;
entity.Write(item);
item.Update();

After executed, the value of item[“Field3”] will be updated to ;#Option #1;#Option #3;#.

One-way Conversion (Only allowed reading from List Item)

By default, all the properties decorated by FieldAttribute will be processed by Read and Write method of Entity class. Sometimes we want a field only can be read to property, but cannot write back from property.  SharePoint Entity Framework allow us specify the mapping mode between field and property by using MappingMode enum type. MappingMode has two member:

  • ReadWrite: Means property can read value from field, also can write value to field. This is the default mapping mode used by FieldAttribute.
  • ReadOnly: Means property only can read value from field, but cannot write value to field. When invoking Entity.Write method, the internal conversion mechanism will ignore that property.

We can use the Mode property or an overload constructor of FieldAttribute to specify mapping mode. Let’s explain this through code sample. At first, add a property in SampleEntity class:

[Field("Field4", MappingMode.ReadOnly)]
public bool Property4 { get; set; }

Then read a SharePoint List Item to entity. Presume the value of item[“Field4”] is true, then after Read method executed, the value of entity.Property4 will also be true. Next, try to update Property4 and write back to item:

entity.Property4 = false;
entity.Write(item);

Since we specified MappingMode.ReadOnly for the FieldAttribute which decorates Property4, so the value of Property4 will not be write back to item. The value of item[“Field4”] is still true.

Hyperlink or Picture

Some of the SharePoint built-in field have more complex format. The field value may contains multiple value, Hyperlink or Picture field is one of them. In SharePoint, the value type of Hyperlink or Picture field is SPFieldUrlValue. Its string form is ‘Url, Description’. When converting, we can only extract Url or description, we also can extract both Url and description to a custom object.

This flexible mapping method is implemented by using UrlFieldAttribute (the child class of FieldAttribute). Below code shows how to use UrlFieldAttribute:

[UrlField("Field5", UrlValue.Url)]
public Uri Property5Url { get; set; }

[UrlField("Field5", UrlValue.Description)]
public string Property5Description{ get; set; }

UrlFieldAttribute allow using UrlValue enum to specify the value part to extract. UrlValue enum has two members: Url and Description,  corresponding to the two partial values of SPFieldUrlValue.

If you want to extract both Url and description, you need to write a custom type just like:

public class Link
{
public string UrlAddress { get; set; }

public string Description { get; set; }
}

Then add a Link type property in the SampleEntity class:

[UrlField("Field5", "UrlAddress", "Description")]
public Link Property5 { get; set; }

This time we used another overload constructor of UrlFieldAttribute. The 2nd and 3rd arguments are UrlAddress and Description, corresponding to the property names of custom Link type. When converting, SharePoint Entity Framework will find the correct properties by those names.

Note: If we use UrlValue enum to extract partial value of SPFieldUrlValue, the mapping mode of UrlFieldAttribute will be set to ReadOnly. It means property can read value from field, but cannot write value to field ( because the property value is only a part of the field value). But if we specify both two property names, this limitation will not have any impact.

Below table shows how to use UrlFieldAttribute:

Usage CLR Type Only Allowed Reading
UrlField(“Field Name”, “Property name that represents Url”, “Property name that represents description”) Custom type No
UrlField(“Field Name”, UrlValue.Url) Uri, string Yes
UrlField(“Field Name”, UrlValue.Description) string Yes

Lookup

Like Hyperlink or Picture field, Lookup is also a field with complex format, and its format is more complex. The value type of Lookup field is SPFieldLookupValue, its string form is “Id;#Value”; If that field allows multiple values, the value type will be SPFieldLookupValueCollection, the string form is “Id1;#Value1;#Id2;#Value2”.

SharePoint Entity Framework provides a LookupFieldAttribute to associate Lookup field and property. Like UrlFieldAttribute, we can specify the partial value we want to extract. The only difference is LookupFieldAttribute using LookupValue enum to specify the partial value to extract, as below table shows:

Usage CLR Type Only Allowed Reading
LookupField(“Field Name”, “Property name that represents Id”, “Property name that represents description”) Custom type and its collection form No
LookupField(“Field Name”, LookupValue.Id) int, int[], List<int> Yes
LookupField(“Field Name”, LookupValue.Value) string, string[], List<string> Yes

Since Lookup field may contains multiple value, SharePoint Entity Framework support associate it with a collection type property, as below code snippet shows:

[LookupField("Field6", LookupValue.Id)]
public int[] Property6Ids{ get; set; }

[LookupField("Field6", "SPListItemId", "Title")]
public SampleEntity[] Property6{ get; set; }

Presume value of item[“Field6”] is “1;#One;#2;Two”. After Read method executed, the value of Property6Ids will be updated to {1, 2}, the value of Property6 will be updated to an array that contains two SampleEntity object. The values of SPListItemId property of these objects will be 1 and 2, the values of Title property will be One and Two.

Person or Group

In SharePoint, the value type of Person or Group field is SPFieldUserValue (inherits from SPFieldLookupValue) and SPFieldUserValueCollection,(inherits from SPFieldLookupValueCollection). We can use LookupField directly to associate this field with its corresponding property.

In addition, we also can use FieldAttribute to associate this field with a SPUser type (or collection form of SPUser) property, as below code snippet shows:

[Field("Field7")]
public SPUser Property7 { get; set; }

At this point, we have introduced how SharePoint Entity Framework supports SharePoint built-in fields, next article will cover how to customize conversion logic and how to support custom fields.

发表评论

电子邮件地址不会被公开。 必填项已用*标注