SharePoint Entity Framework 2 – Attributes
上一篇《介紹》敘述瞭如何通過FieldAttribute來將實體類屬性和SharePoint列表項欄位關聯起來。使用FieldAttribute是一種最簡單的方法，而且可以應對絕大多數使用場景。本文將會介紹FieldAttribute的其他使用方法，以及其他有助於轉換的Attributes。
選項和列舉
SharePoint Entity Framework會“選項”欄位轉換為自定義列舉，那麼就需要有一種方式來把每個候選項和自定義列舉的成員對應起來，這是通過EnumMemberAttribute來完成的。
假設SharePoint列表包含一個名為Field3的欄位，型別為選項，包含三個候選項：Option #1, Option #2和Option #3。那麼我們就可以編寫如下的自定義列舉型別：
|
|
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
}
|
接下來我們在上一篇文章裡的SampleEntity類中增加一個屬性：
|
|
[Field(
"Field3"
)]
public
Choice Property3 {
get
;
set
; }
|
如果想要讀入的列表項的Field3欄位值為Option #2，entity.Read方法執行結束之後，entity.Property3的值就會變成Choice.Option2。
SharePoint Entity Framework還能正確地在多值列舉和SharePoint允許多選的“選項”欄位之間相互轉換，如下面的程式碼所示：
|
|
entity.Property3 = Choice.Option1 | Choice.Option3;
entity.Write(item);
item.Update();
|
執行後item["Field3"]的值會被更新為;#Option #1;#Option #3;#。
只允許讀取的欄位
預設情況下，所有被FieldAttribute修飾的屬性都會被Entity的Read方法和Write方法處理。有時候我們會希望某欄位只能被讀取到屬性裡，而不能從屬性寫回。這時我們可以手工指定屬性和欄位的對映方式。
在SharePoint Entity Framework中，對映方式用列舉型別MappingMode來表示。它有兩個成員：
- ReadWrite：FieldAttribute採用的預設值，表示該屬性既可以從欄位讀取值，也可以將值寫入到欄位中；
- ReadOnly：表示該屬性只能從欄位讀取值，而不可以將值寫入到欄位。在呼叫Entity.Write方法時，內部的轉換機制會忽略該屬性。
FieldAttribute提供Mode屬性以及相應的建構函式，我們可以通過它們來指定對映方式。下面通過程式碼來進一步解釋一下，首先在SampleEntity類中增加一個屬性：
|
|
[Field(
"Field4"
, MappingMode.ReadOnly)]
public
bool
Property4 {
get
;
set
; }
|
接著將某個SharePoint列表項讀入為實體，假設item["Field4"]的值是true，那麼在Read方法執行之後，entity.Property4的值也會變成true。接下來更改Property4的值並寫回到item：
|
|
entity.Property4 =
false
;
entity.Write(item);
|
因為修飾Property4的FieldAttribute被指定為使用MappingMode.ReadOnly，所以Property4的值不會被寫入到item，此時item["Field4"]的值依然是true。
超連結或圖片
SharePoint內建的欄位中有一些擁有比較複雜的格式，欄位記憶體儲的內容可能會包含多個值，超連結或圖片欄位就是其中之一。在SharePoint中，超連結或圖片欄位的值型別為SPFieldUrlValue，其字串表現形式為“Url,描述”。在轉換時，我們可以只提取Url或描述，也可以把它們同時提取到一個自定義物件中。
這種靈活的對映方式是通過FieldAttribute的子類UrlFieldAttribute來實現的（UrlFieldAttribute及SharePoint Entity Framework中其他所有的Attribute都位於WindStyle.SPEntity.Attributes名稱空間下），下面的程式碼描述了UrlFieldAttribute的幾種使用方法：
|
|
[UrlField(
"Field5"
, UrlValue.Url)]
public
Uri Property5Url {
get
;
set
; }
[UrlField(
"Field5"
, UrlValue.Description)]
public
string
Property5Description{
get
;
set
; }
|
UrlFieldAttribute允許使用UrlValue列舉來指定想要提取的部分，UrlValue列舉包含兩個成員，分別是Url和Description，分別對應於SPFieldUrlValue的兩個部分值。
如果想要同時提取Url和描述，就需要編寫一個自定義型別，如下面的程式碼所示：
|
|
public
class
Link
{
public
string
UrlAddress {
get
;
set
; }
public
string
Description {
get
;
set
; }
}
|
然後在SampleEntity中增加該型別的屬性：
|
|
[UrlField(
"Field5"
,
"UrlAddress"
,
"Description"
)]
public
Link Property5 {
get
;
set
; }
|
這一次使用了UrlFieldAttribute的另一個建構函式過載，分別指定了自定義型別（Link）中對應於Url和描述的屬性名稱。在進行轉換時，SharePoint Entity Framework會按照這兩個名稱在自定義型別中查詢相應的屬性。
需要注意的是，使用UrlValue來提取部分值時，UrlFieldAttribute的對映模式會變成ReadOnly，這表示此時只允許從欄位讀取值，而不允許將屬性的值寫入到欄位（因為屬性的值僅僅是該欄位應有值的一部分，寫入的話會破壞完整性），而完整地指定了兩個屬性名稱時則沒有此限制。
UrlFieldAttribute的使用形式如下表所示：
| 使用形式 | CLR型別 | 是否只允許讀取 |
| UrlField(“欄位名稱”, “表示Url的屬性名稱”, “表示描述的屬性名稱”) | 自定義型別 | 否 |
| UrlField(“欄位名稱”, UrlValue.Url) | Uri, string | 是 |
| UrlField(“欄位名稱”, UrlValue.Description) | string | 是 |
查閱項
與超連結或圖片類似，查閱項也是一個格式複雜的欄位，而且其複雜程度要更勝一籌。查閱項欄位的值型別為SPFieldLookupValue，其字串形式為“Id;#值”；如果該欄位允許多值，那麼值型別就會是SPFieldLookupValueCollection，字串型式是“Id1;#值1;#Id2;#值2”。
SharePoint Entity Framework提供了一個LookupFieldAttribute來關聯查閱項欄位和屬性，使用形式和UrlFieldAttribute也很相似，只不過LookupFieldAttribute使用LookupValue列舉來指定想要提取的部分，如下表所示：
| 使用形式 | CLR型別 | 是否只允許讀取 |
| LookupField(“欄位名稱”, “表示Id的屬性名稱”, “表示值的屬性名稱”) | 自定義型別及其集合形式 | 否 |
| LookupField(“欄位名稱”, LookupValue.Id) | int, int[], List<int> | 是 |
| LookupField(“欄位名稱”, LookupValue.Value) | string, string[], List<string> | 是 |
由於查閱項欄位可能包含多值，所以SharePoint Entity Framework支援將查閱項欄位和一個集合型別的屬性關聯起來，如下面的程式碼所示：
|
|
[LookupField(
"Field6"
, LookupValue.Id)]
public
int
[] Property6Ids{
get
;
set
; }
[LookupField(
"Field6"
,
"SPListItemId"
,
"Title"
)]
public
SampleEntity[] Property6{
get
;
set
; }
|
假設item["Field6"]的值為“1;#One;#2;#Two”，那麼執行完Read方法之後，Property6Ids的值會被更新為{1,2},而Property6的將會被更新為由兩個SampleEntity物件構成的陣列，這兩個物件的SPListItemId屬性的值分別為1和2，Title屬性的值分別為One和Two。
使用者或使用者組
在SharePoint中，使用者或使用者組的值型別為SPFieldUserValue和SPFieldUserValueCollection，分別從SPFieldLookupValue和SPFieldLookupValueCollection派生而來，所以可以直接使用LookupField來將其關聯到相應的屬性。
除此之外，還可以直接使用FieldAttribute來將使用者或使用者組欄位關聯到一個型別為SPUser（或其集合形式）的屬性，如下面的程式碼所示：
|
|
[Field(
"Field7"
)]
public
SPUser Property7 {
get
;
set
; }
|
至此，我們已經介紹完了SharePoint Entity Framework對SharePoint內建欄位的支援，下一篇文章將會介紹如何自定義轉換邏輯以及如何支援自定義欄位。
下一節：SharePoint Entity Framework 3 – 自定義轉換邏輯
轉載至：http://coding.windstyle.cn/sharepoint-entity-framework-2-attributes/