網站相關的對象模型
作爲一個應用原型系統，SharePoint提供了很多強大的應用及管理功能，但是，在實際的應用中，這些原有的功能很難滿足用戶的需求。因此，SharePoint也提供了一套非常完整的對象模型作爲底層接口，以此爲基礎進行二次開發。
Windows SharePoint Services（以下簡稱WSS）作爲SharePoint Portal Server（以下簡稱SPS）的基礎部分，是在開發過程中使用最多的一套體系。因此，在本書開發部分的開始，使用一章的篇幅來介紹WSS的對象模型體系，以及一些簡單的應用。
WSS提供了非常完善的一套對象模型體系，大致整個的Web服務器（SPWebServer類）、小到一個文件的版本信息（SPFileVersion類），以及一些網站的設置，都可以通過WSS對象模型來進行訪問或修改。此外，爲了彌補.NET類庫在該環境中的一些不足，在SharePoint中也提供了一些常用的功能的函數，它們被封裝在Microsoft.SharePoint.Utilities命名空間中。
通過使用SharePoint的對象模型，可以完成幾乎所有的功能，但是在有些時候，由於SharePoint本身的限制（例如嚴格的權限控制），有一些功能僅使用對象模型是很難完成甚至無法完成的。所以，在考慮用戶需求和設計方案的時候，也應該儘可能地考慮到實現的難易程度。
在WSS對象模型體系中，提供瞭如下一些命名空間（namespace）：
· Microsoft.HtmlTrans.Interface
提供一個接口，用來將文檔庫中的某些文件以Html的形式顯示到客戶端，這樣在客戶端沒有安裝相應文件的瀏覽軟件的時候，也可以查看這些文件；
· Microsoft.SharePoint
該命名空間是最常用的一個命名空間，其中提供了WSS中關於網站內容的基本的對象模型，例如網站、列表、文件和用戶等，本章也主要是圍繞這一命名空間進行介紹；
· Microsoft.SharePoint.Administration
該命名空間中主要提供了WSS網站管理和參數設置的一些類；
· Microsoft.SharePoint.Dsp
該命名空間以及之下的幾個命名空間提供了一些WSS數據搜索用的接口；
· Microsoft.SharePoint.Meetings
該命名空間提供了對會議室網站進行操作的一些類；
· Microsoft.SharePoint.Security
該命名空間提供了WSS中自定義權限管理相關的類；
· Microsoft.SharePoint.SoapServer
該命名空間提供了關於WebPart和WebPart頁相關的WebService類；
· Microsoft.SharePoint.Utilities
該命名空間提供了一些網站中常用的功能，主要是擴充.NET類庫中的一些功能；
· Microsoft.SharePoint.WebControls
該命名空間提供了一些WSS中特有的Web控件類；
· Microsoft.SharePoint.WebPartPages
該命名空間提供了Web部件和Web部件頁相關的類，其中Web部件（WebPart）是SharePoint開發中一個重點的環節，我們將在第11章中對其進行詳細地敘述；
· Microsoft.SharePoint.WebPartPages.Communication
該命名空間提供了對Web部件通信的支持。
以上這些命名空間和類庫封裝在Microsoft.SharePoint.dll中。
由於篇幅的關係，在本章中只介紹最基本的一些對象模型的使用，只涉及到Microsoft.SharePoint這一命名空間。其他對象模型的使用方法請參照SDK。
爲了便於實現和觀察，也便於避開Web環境中一些複雜的機制和權限控制，本章和下一章的示例代碼，均使用命令行（Console）方式完成。程序需要直接運行在裝有WSS或SPS的服務器上，並且默認操作者具有網站管理員的權限。此外，本章和第10章着重講解功能和某些注意事項，因此在介紹對象模型的時候，只介紹最常用的一些屬性和方法，並且在每部分的最後給出一個示例說明該對象模型的使用方法。更全面的類庫、屬性和方法的介紹，以及更加詳細的示例程序，請參考SDK中對應的章節。
本書中的代碼均使用C#語言編寫，在WSS或SPS環境中經過測試通過。
在絕大多數的WSS使用場景以及部分SPS的使用場景中，“網站”是使用得最多的一個對象，這是因爲在WSS的體系結構中，幾乎所有的內容（包括用戶、列表、文件系統等）都是依附於網站之上的，這一點在對象模型中也能很明顯地體現出來。
在WSS的結構中，網站被劃分爲Site（網站集）和Web（網站）這兩種概念。
Site和Web的區別與聯繫
顧名思義，網站集是網站的集合體，在WSS中，Site的主要用處是管理網站，在對象模型中，Site所對應的SPSite除了網站的集合（SPWebCollection）外幾乎不包含任何的信息，所有的信息都是儲存在Web所對應的SPWeb這一對象模型中的，Web纔是真正的內容承載者。
在SharePoint的最初設計理念中，將網站集稱爲Web，而網站稱爲Site，這一點從SDK中的SharePoint體系結構圖中可以看出來。
但是，在設計對象模型的時候，卻又將網站集的對象模型稱爲SPSite（即SharePoint Site），而網站的對象模型稱爲SPWeb。因此在SDK的代碼示例中經常可以看到例如“SPSite web;”以及“SPWeb site;”這樣的變量命名方法，這對於初學者來說是非常容易引起混淆的。
作爲開發的參考，爲了便於說明，以及和對象模型的統一，本書中所指的Site均爲網站集的概念（對應於SPSite），而Web均爲網站的概念（對應於SPWeb），請讀者注意。
SPSite的使用
SPSite作爲網站集對應的對象模型，其主要的用處是獲取某個特定的網站，它最常用的幾個功能如下：
„ 構造函數
SPSite的構造函數有兩種，分別以Site的url和Guid作爲參數。
在SharePoint對象模型中，大部分對象都擁有一個Guid作爲它唯一的標識符，通過這個Guid可以獲取該對象的實例，例如Site（SPSite）、Web（SPWeb）、列表（SPList）、視圖（SPView）以及SPS中的區域（Area）、門戶列表（AreaListing）等。但也有一些是採用整型作爲標識符的，例如列表項（SPListItem）、角色（SPRole）和用戶（SPUser）等。
„ AllWebs屬性
該屬性是一個SPWebCollection類型的變量，通過這個屬性，便可以獲取到該網站集中的所有網站，包括一個頂級網站和它下面的所有子網站。然後通過以下三種形式之一，便可以得到某個特定的SPWeb的對象：
· webs[int index]：根據在該集合中的下標獲取一個Web；
· webs[string url]：根據Web的相對url（相對於包含該網站的Site）獲取Web；
· webs[Guid guid]：根據唯一標識該Web的guid獲取。
在WSS對象模型中，集合（Collection）是一個比較重要的概念，它實際上是一種對象的存儲方式（即.NET框架中集合的概念）。一般來說SPxxxCollection便是SPxxx這個類所對應的集合類，例如SPWebCollection、SPListCollection和SPFileCollection等。但是應該注意到的是，SPSiteCollection並不是包含在Microsoft.SharePoint命名空間中的類，而是在Microsoft.SharePoint.Administration這一命名空間中的，這也說明了Site的主要意義在於網站本身的管理，而非網站內容的管理。
„ RootWeb屬性
該屬性是一個SPWeb類型的變量，它所對應的對象是該網站集中的頂級網站，通過它可以逐步獲得該網站級中的層級結構。（關於頂級網站和子網站的概念，請參考本書中“2.1.2Windows SharePoint 站點架構簡介”部分。）
„ OpenWeb函數
該函數返回一個SPWeb類型的變量，通過該函數可以獲得該網站集中一個特定的網站。它有以下三種使用形式：
· OpenWeb()：在命令行模式中，該方法返回網站級中的頂級網站對象；但是在網絡環境中使用該方法會有不同的效果，詳見第11章11.3小節“WebPart編程中的對象模型”；
· OpenWeb(Guid guid)：返回該guid所對應的網站對象；
· OpenWeb(string url)：返回該url所對應的網站對象，注意該url爲相對地址（相對於服務器根路徑或者網站集根路徑）。
【示例9-1】 SPSite的基本使用。
在這個示例中，展示了SPSite的基本用法，包括上面所提到的幾個重要功能：
using System;
using Microsoft.SharePoint;
namespace WSSModelObject
{
class Example1_1
{
[STAThread]
static void Main(string[] args)
{
// 使用構造函數創建網站集對象
SPSite site = new SPSite("http://localhost/");
// 獲取根網站信息
Console.WriteLine("Root:" + site.RootWeb);
// 遍歷網站集中的所有網站
Console.WriteLine("All Webs in site:");
foreach(SPWeb web in site.AllWebs)
{
Console.WriteLine(web);
}
// 打開某個特定的網站
try
{
SPWeb web = site.OpenWeb("subweb1");
Console.WriteLine(web);
}
catch(Exception ex)
{
Console.WriteLine(ex.Message);
}
}
}
}
在編寫程序的過程中，合理地使用try-catch語句是一種良好的編程習慣。SharePoint是一套相對龐大的對象模型體系，在編寫程序的過程中，難免會出現預料之外的問題，因此應該儘可能對所有可能出錯的語句進行try-catch，如果有必要，捕獲每種特定的異常，並提供更加友好的出錯信息，使得程序更加人性化。在本書中，爲了節省篇幅，除非特殊的需要和說明，在後面的示例程序中一般不進行try-catch處理，請讀者注意。
編寫SharePoint的程序需要在引用中添加Microsoft.SharePoint.dll，如果是在安裝了WSS的機器上，在VS.NET中添加引用界面選擇Windows SharePoint Services即可，也可以將dll複製到其他的機器上再引用（但是仍然需要在裝有WSS的機器上才能運行），該dll的默認安裝路徑爲：C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI。在本書後續章節中除非特殊情況，不再使用完整的代碼，而使用代碼片段作爲示例。
SPWeb的使用
在一般的應用場景下，SPWeb是使用最多的一個對象模型，因爲幾乎所有的WSS的內容都是依附於SPWeb對象的，在編程中也是使用SPWeb來獲取其他的對象模型。而獲取SPWeb對象的方法在本章9.2.2小節“SPSite的使用”中已經有所提及，就不在這裏重複了。
大多數和WSS相關的內容都是通過使用SPWeb的一些成員變量來獲取的，這些成員變量主要有：
· AllUsers：網站內的所有成員，以及通過域組（domain group）來瀏覽網站的用戶；
· Files：網站下的所有文件；
· Folders：網站下的所有目錄；
· Groups：所有跨網站用戶組；
· Lists：網站下的所有列表；
· ListTemplates：網站下的所有列表模板；
· Permissions：網站下的權限；
· Roles：網站下的所有角色；
· Users：屬於該網站的所有用戶；
· Webs：該網站的所有子網站。
通過使用這些成員變量，就可以獲取到相應內容的對象集合（Collection），進而獲取需要的內容。
此外，SPWeb的某些成員變量對應於該網站的一些屬性，例如：
· AllowAnonymousAccess：網站是否允許匿名訪問（只讀）；
· Author：網站的創建者（只讀）；
· Created：網站的創建時間（只讀）；
· CurrentUser：當前的用戶（只讀）；
· ID：唯一標識該網站的Guid（只讀）；
· IsRootWeb：該網站是否爲頂級網站（只讀）；
· ParentWeb：該網站的父網站（只讀）；
· Site：該網站所屬的網站集（只讀）；
· Title：該網站的標題；
· Url：該網站的url（絕對路徑）（只讀）；
· WebTemplate：該網站的模板（只讀）。
SPWeb對象還提供了一些方法，例如：
· GetFile：通過url獲取一個文件的對象（SPFile）；
· GetFolder：通過url獲取一個目錄的對象（SPFolder）；
· GetListOfType：獲取特定類型的列表的集合；
· GetSubwebsForCurrentUser：獲取該網站的子網站（可以指定模板）；
· GetViewFromUrl：通過url獲取一個列表的視圖（SPView）；
· SaveAsTemplate：將網站保存爲模板；
· SearchDocuments：搜索網站的文檔庫（需要開啓全文檢索功能）；
· SearchListItems：搜索列表條目；
· Update：使網站屬性的修改生效。
在SharePoint的對象模型中，一些比較重要的對象都會擁有Update方法（例如SPWeb、SPList、SPField和SPListItem），在修改這些對象的屬性時，只有在調用Update方法之後，這些修改纔會真正生效。僅限普通屬性，不包括集合類的屬性，比如SPWeb.Lists中添加或刪除一個列表，不需要調用SPWeb.Update方法。這一點需要特別引起注意 。
【示例9-2】 得到一個網站集中的所有網站，並輸出它們的標題、url、父網站及子網站。
SPSite site = new SPSite("http://localhost/");
foreach(SPWeb web in site.AllWebs)
{
Console.WriteLine("Title: " + web.Title);
Console.WriteLine("Url: " + url);
Console.WriteLine("ParentWeb: " + web.ParentWeb);
Console.Write("SubWebs: ");
foreach(SPWeb subweb in web.Webs)
Console.Write(subweb.ToString() + " ");
Console.WriteLine();
}
一個小技巧：在.NET對象模型中，每個類都會有ToString函數（繼承自Object類），一般來說每個類也都會對這個方法進行重寫。SPWeb的ToString方法一般情況下就是返回了SPWeb.Title這個屬性。在大多數字符串操作過程中，一個對象的ToString方法是可以被隱式調用的（例如示例9-1中就使用了這個特性），在不知道該對象是否爲空（null）的時候，如果顯式調用ToString方法會造成一個異常（NullReferenceException），但是在隱式調用的時候便不會產生這個異常，如果僅是作爲輸出的需要，隱式的調用要比顯式的調用更加方便。
在示例9-2中，輸出每個網站的父網站，但是對於頂級網站來說，其父網站爲空，如果顯示調用的話，便會出現異常，採用隱式調用就可以避開這個問題，只顯示一個空的字符串。
示例9-2中使用了三種輸出網站標題的方法：SPWeb.Title屬性，隱式調用SPWeb.ToString方法，顯式調用SPWeb.ToString方法。
列表相關的對象模型
在SharePoint中，列表（List）是一個非常強大的功能。它可以方便地自定義列表的結構，添加和刪除各種類型的字段，也可以設置計算字段和引用字段，也可以設置列表條目的審批功能，同時列表還提供了多種可以自定義的視圖，對列表的數據進行篩選或者排序。本節主要介紹列表相關的對象，包括列表（SPList）、列表視圖（SPListView）、列表字段（SPField）和列表條目（SPListItem）。
SPList的使用
在使用列表的功能之前，通常都需要首先獲取該列表對象，獲取SPList的主要方法是通過訪問SPWeb.Lists這一SPListCollection類型的屬性。從該集合中獲得一個特定的列表對象有如下三種方法：
· lists[string name]：通過該列表的名稱獲取；
· lists[Guid guid]：通過唯一標識該列表的Guid獲取；
· lists[int index]：通過列表在該列表集合中的下標來獲取
在網站上添加列表，也是通過SPListCollection對象來完成的。添加一個列表通過調用SPListCollection.Add方法來完成，創建成功之後，會返回新列表的Guid。該方法提供瞭如下三種形式：
· Add（string title, string description, SPListTemplate template）：
前兩個參數分別指定列表的名稱和簡介，第三個參數是一個SPListTemplate型變量，指定該列表創建時所需要的列表模板對象，該對象可以通過SPWeb.ListTemplates屬性獲得；
· Add（string title, string description, SPListTemplateType type）：
前兩個參數指定列表的名稱和簡介，第三個參數使用SPListTemplateType型枚舉指定列表模板，枚舉中所包含的都是網站默認擁有的基本類型的列表模板，如果要創建一個自定義的列表，請使用SPListTemplateType.GenericList作爲該參數；
· Add（string title, string description, SPListTemplate template, SPDocTemplate docTemplate）：
該方法會創建一個文檔庫（一種特殊的列表），前兩個參數分別指定列表的名稱和簡介，第三個參數制定列表的模板對象，第四個參數指定文檔庫的模板對象，該參數是一個SPDocTemplate類型的變量，可以通過SPWeb.DocTemplates屬性獲得。
刪除列表時，通過調用SPListCollection.Delete方法來完成，該方法只有一種形式：
· Delete（Guid guid）：通過列表的Guid刪除該列表。
SPList類有如下一些常用的屬性：
· BaseTemplate：該列表所對應的列表模板（只讀）；
· BaseType：該列表的基礎類型（只讀）；
· DefaultView：該列表的默認視圖對象（只讀）；
· EnableAttachments：該列表是否允許添加附件；
· EnableModeration：該列表是否開啓審批功能；
· Fields：列表字段的集合（將在下文進行詳細介紹）；
· Forms：列表表單的集合，主要有瀏覽、添加和修改幾個頁面（只讀）；
· ID：標識該列表的唯一的Guid（只讀）；
· Items：列表條目的集合（將在下文進行詳細介紹）；
· ParentWeb：列表所在的網站對象（只讀）；
· Title：列表的標題；
· Views：該列表的視圖的集合（將在下文進行詳細介紹）（只讀）。
這其中值得注意的是BaseTemplate與BaseType的區別：BaseTemplate是生成列表的模板，例如“鏈接”和“聯繫人”等，每個模板中都默認設置了一些獨有的字段，該屬性爲SPListTemplateType型的枚舉類型，默認這些模板的字段設置可以在SDK的“Field Tables for Default Lists”一節中找到；它的具體位置爲Microsoft Windows Share Point ServicesŽAppendixŽField Tables for Default Lists，而BaseType則是列表的基礎類型，例如“討論區”、“文檔庫”等，每種基礎類型的列表都提供了一些普通列表所不具備的特殊的功能，該屬性爲SPBaseType型的枚舉類型。
修改列表屬性後，通過調用SPList.Update方法使修改生效。
【示例9-3】 在該示例中創建一個聯繫人列表，並顯示該列表添加條目頁面的url。
// 首先獲取到SPWeb對象web
SPListCollection lists = web.Lists;
SPList newList = null;
try
{
Guid id = lists.Add("DemoList", "這是一個測試列表",
SPListTemplateType.Contacts);
newList = lists[id];
SPForm form = newList.Forms[PAGETYPE.PAGE_NEWFORM];
Console.WriteLine(form.Url);
}
catch
{
Console.WriteLine("列表添加失敗");
}
SPView的使用
視圖在SharePoint的列表中是一個比較重要的概念，在SharePoint中，列表中所有的數據都是通過視圖呈現給用戶的，視圖中定義了需要顯示的字段，以及顯示的方式，某一些特殊的列表默認擁有一些特殊的視圖將數據呈現出來，例如“任務”模板列表中的“日曆視圖”，等等。
除了負責數據的多樣化顯示，視圖的另外一個重要的作用就是對數據的篩選和排序，在SharePoint環境中可以直接對視圖的這些內容方便地進行修改，通過使用計算字段，可以更加豐富篩選和排序的功能。
獲取一個SPView對象有如下幾種方法：
（1）通過List.DefaultView屬性得到該列表的默認視圖；
（2）通過SPWeb.GetViewFromUrl方法根據url獲取到該視圖，在實際使用中，可以使用這種方法先獲得一個視圖，再得到這個視圖所在的列表的對象；
（3）通過List.Views得到該列表的所有視圖，再通過以下三種方式得到特定的視圖：
· views[string name]：通過視圖的名稱獲取；
· views[Guid guid]：通過唯一標識該視圖的Guid獲取；
· views[int index]：通過視圖在該視圖集合中的下標來獲取。
添加一個視圖通過調用SPViewCollection.Add方法來完成，該方法有兩種形式：
· Add(string name, StringCollection fields, string query,
uint rowLimit, bool paged, bool makeDefault)：
name參數指定了視圖的名稱，fields參數指定了需要顯示的字段名的集合，query參數指定了對數據的篩選條件，rowLimit參數指定了視圖中一次所返回的列表條目的最大個數，paged參數指定了該視圖是否支持翻頁，makeDefault參數指定了是否需要將該視圖作爲默認視圖；
· Add(string name, StringCollection fields, string query,
uint rowLimit, bool paged, bool makeDefault，
· SPViewCollection.SPViewType type, bool personalView)：
前面的參數含義與上文相同，type參數指定了該視圖的基本類型，personalView參數指定了該視圖是否爲個人視圖（否則爲公共視圖）。
需要注意的是，與列表的添加方法不同，視圖的添加方法返回的對象是SPView的對象，而不是一個Guid。
刪除一個視圖同樣使用SPViewCollection.Delete方法，用視圖的Guid作爲參數。
有一點需要注意的是，在使用默認頁面瀏覽一個視圖的時候，視圖的翻頁功能只有“下一頁”而沒有“上一頁”，如果需要實現向前翻頁的功能，需要自己編寫程序來完成。
SPView中常用的一些屬性如下：
· ID：標識該視圖的唯一的Guid；
· ParentList：包含該視圖的列表對象（SPList）；
· PropertiesXml：該視圖的基本信息，包括url、名稱和類型等（只讀）；
· Query：視圖中對數據進行篩選的查詢xml字符串；
· SchemaXml：該視圖的信息，包括基本信息和例如篩選、分組等的設置（只讀）；
· Title：該視圖的名稱；
· ViewFields：該視圖需要顯示的字段的集合；
· Url：顯示該視圖所對應的url（只讀）；
修改視圖屬性後，使用SPView.Update方法使修改生效。
【示例9-4】 該示例中創建了一個視圖，並指定了該視圖的一些設置：
// 首先獲取到SPWeb對象web
SPList list = web.Lists["ListName"];
SPViewCollection views = list.Views;
string viewName = "View_Name";
StringCollection viewFields = new StringCollection();
viewFields.Add("Field1_Name");
viewFields.Add("Field2_Name");
viewFields.Add("Field3_Name");
string query = "<Where><Eq><FieldRef Name=\"Field3_Name\"/>" +
"<Value Type=\"Text\">Text</Value></Eq></Where>";
views.Add(viewName, viewFields, query, 100, true, false);
程序中的StringCollection類是在System.Collection.Specialized命名空間中。
SPField的使用
SPField對應於列表對象中的字段（Field）對象，和傳統的數據表一樣，SharePoint的列表也是由若干個字段所組成的，每個字段可以設置爲不同的數據類型，也可以擁有不同的屬性設置（例如默認值、是否隱藏、是否可以爲空等）。而SharePoint列表的最大一個特點，就是字段的可定製性，不需要進行任何的編程，也不用深入數據庫進行復雜的調整，僅在使用界面上就可以方便地對列表的字段進行添加、刪除和修改，這種方便的特性也正是很多用戶喜愛SharePoint的一個重要原因。
獲得一個SPField對象的方法主要是通過SPList.Fields屬性得到所有字段，再通過以下兩種方法得到特定字段的對象。
· fields[string dispName]：根據該字段的顯示名稱獲得
· fields[int index]：根據該字段在集合中的下標獲得。
爲列表添加一個字段有三種方法：
· Add(string dispName, SPFieldType type, bool bRequired)
其中第一個參數指定該字段的顯示名稱，第二個參數指定該字段的類型，第三個參數指定在填寫數據的時候，該字段是否爲必填內容。
· AddLookup(string dispName, Guid lookupListID, bool bRequired)
該方法爲列表添加一個特殊的字段——“查閱項”字段，通過第二個參數指定目標列表的Guid，其餘兩個參數的含義和使用方法與Add方法相同。
· AddFieldAsXml(string strXml)
通過一段xml的描述添加一個字段，該描述中需要包括字段等信息，實際上，這段xml描述對應於SPField.SchemaXml屬性。
需要特別注意的是，以上三種方法所返回的雖然都是string型的變量，但是它們的含義各不相同，Add方法返回的是顯示名稱，AddLookup方法所返回的是內部名稱（這兩者的區別稍候會進行介紹），而AddFieldAsXml方法所返回的是一段包含字段名稱的xml。
注意
在添加字段時，bRequired參數（對應與SPField.Required屬性）指定的是在用戶界面中新建、修改列表項的時候，該字段是否爲必填內容。但實際上，如果我們通過對象模型來創建或修改一個列表條目的時候，該字段並不會起到任何限制作用。
SPField擁有如下一些比較常用的屬性。
· DefaultFormula：計算字段的公式；
· DefaultValue：字段的默認值，即該字段在未進行設置時的初始值；
· Description：該字段的說明描述信息；
· Filterable：該字段是否可以被篩選（只讀）；
· Hidden：該字段是否在列表中顯示；
· InernalName：該字段的內部名稱；
· ParentList：該字段所在的列表的對象；
· ReadOnlyField：該字段是否被只讀；
· Required：在填寫數據的時候，該字段是否必填；
· SchemaXml：該字段設置的信息；
· Sortable：該字段是否可以被排序；
· Title：該字段的字段名，即顯示名稱；
· Type：該字段的類型，爲SPFieldType類型的枚舉。
在SharePoint中，每一個字段都有兩個名稱，即顯示名稱（DisplayName）和內部名稱（InternalName），它們在對象模型中對應於SPField.Title和SPField.InternalName。其中顯示名稱是在用戶使用界面上看到的名稱，雖然該名稱在網站使用界面的操作中是不可重複的，但是，在使用對象模型添加字段的時候，或者內部管理的時候，可能會有一些重名的字段（其中典型的代表就是每個列表的“標題”字段）；而內部名稱是SharePoint列表用於內部管理的名稱，它在列表中是唯一的，而且其中沒有中文和空格（在保存爲內部名稱時，對於這些字符會進行編碼）。
在編寫程序的時候，
在下列情況中必須使用顯示名稱：
· 使用SPList.Fields["name"]獲取該字段對象時，必須通過顯示名稱。
在下列情況中必須使用內部名稱：
· 使用SPView.ViewFields的時候，添加、刪除都是通過內部名稱，獲取的時候也是得到內部名稱；
· 使用SPView.Query的時候，必須使用內部名稱；
· 使用SPQuery（下面會提到該類）的時候，必須使用內部名稱。
在下列情況中即可以使用顯示名稱，也可以使用內部名稱：
· 使用SPListItem["fieldName"]獲取或設置列表項某個字段的值。
上面所提到的一些屬性是SPField類中的屬性，也就是所有字段都擁有的一些屬性，而SharePoint對象模型中，也爲每一種類型的字段提供了單獨的類，例如SPFieldText、SPFieldLookup和SPFieldNumber等，每一個類都有一些該類型的字段所擁有的特殊屬性，這些類是SPField的子類，在使用的時候需要通過強制類型轉換，將SPField類轉換爲對應的類型。這些類的具體使用方法由於篇幅原因不在此進行詳細地介紹，請參考SDK中的有關內容。
在使用SchemaXml屬性的時候，我們會發現除了SPField以及它的子類所包含的一些屬性之外，還會有一個“ColName”屬性，實際上這個屬性是和SharePoint列表實現的具體機制相關的，它保存的是在底層數據庫的某個表中存放該字段那一列的名稱。關於這一點，會在第12章高級開發中，進行比較詳細的介紹。
修改字段的屬性後，通過調用SPField.Update方法使修改生效。
【示例9-5】 爲列表創建一個NumDemo字段，並指定該字段的最大值和最小值：
// 首先獲取到SPWeb對象web
SPList list = web.Lists["ListName"];
string fieldName = list.Fields.Add("NumDemo", SPFieldType.Number, false);
SPFieldNumber field = (SPFieldNumber)list.Fields[fieldName];
field.MinimumValue = 0;
field.MaximumValue = 100;
field.Update();
該示例中值得注意的是，在列表的字段集合中添加一個字段之後，沒有調用list.Update方法，而在對字段本身的屬性進行修改之後，調用了field.Update方法。關於對象模型中Update方法的這一點特性已經在本章9.2小節中進行說明了，在此通過示例的方式再次強調一下。
SPListItem的使用
在列表的實際操作中，最終要接觸到的還是作爲數據內容部分的列表條目（List Item）。一般來說，在訪問列表的某個具體條目之前，都需要先獲得一個列表條目的集合，在SharePoint對象模型中，提供了很多種方法來獲取列表條目集合：
最直接地獲取列表條目的方法爲，使用SPList.Items屬性，該屬性返回列表中的所有列表條目。在需要得到或者遍歷所有列表條目的時候，可以使用這種獲取列表條目的方法。
如果有目的地要獲得部分列表條目，可以使用SPList.GetItems方法，該方法有如下三種形式：
· GetItems(SPView view)
返回指定視圖中的列表條目，通過這種方法可以按照視圖中所指定的篩選、排序及其他的條件按照順序返回列表條目。在返回的條目中，也只有在視圖中定義過的可查看字段中的數據纔可以訪問到。
· GetItems(SPQuery query)
顧名思義，SPQuery是SharePoint中負責查詢列表條目的一個類，通過定義一個查詢，可以方便地獲取想要得到的列表條目，SPQuery提供了兩種構造函數，一種是無參數的，另外一種可以帶有一個SPView類型的參數，即在指定的視圖上進行二次的查找。SPQuery最核心的一個屬性就是Query屬性，它是一個字符串的類型，它通過一種特殊定義過的xml形式，即CAML（Collaborative Application Markup Language）的形式描述一個查詢的條件，實際上，這個查詢字符串和SPView.Query屬性是相當的。在SPQuery中，也可以通過ViewFields屬性來指定需要查看的字段（如果不加以指定，則查看所有字段）。在本節最後的示例中，將演示SPQuery的用法。
· GetItems(SPQuery query, string viewID)
指定SPQuery查詢和視圖，獲取列表條目。需要特別注意的是，雖然第二個參數爲字符串類型，但是在使用的時候需要傳入的是列表視圖的Guid，而不是視圖的名稱，而且該Guid要以一種特殊的形式傳入，即兩邊用“{}”包圍起來，全大寫形式，這種形式可以通過Guid.ToString("B").ToUpper()方法得到。
在使用SPQuery的時候，必須每使用一次都要重新進行構造（即使用new運算符重新生成一個新的對象），然後再指定Query屬性。否則，如果不進行重新構造，即使指定了不同的Query屬性，在每次查詢的時候始終得到的是第一次指定的Query條件的查詢結果。這一點非常容易被忽略。
以上幾種方法所返回的都是SPListItemCollection類型的列表條目集合，獲得該集合後，在獲得某個具體的列表條目時，有下面兩種方法。
· items[int index]：通過在集合中的下標得到該條目，這種方法多在遍歷集合的時候使用；
也可以使用SPListItemCollection.GetItemById方法。
· GetItemById(int id)：在SharePoint中，每個列表條目都會有一個在該列表中唯一的id（int型），調用SPListItemCollection類的GetItemById方法，就可以通過該id來得到對應的列表條目。
在得到列表條目之後，就可以對該條目的內容進行訪問或修改了，訪問條目某個字段的方法最常用的方法爲： item[string fieldName]，其中fieldName可以使用該字段的顯示名稱，也可以使用該字段的內部名稱。還有一點需要注意的是，該方法所返回的是一個Object類型的變量，如果需要使用該變量的話，必須要對它進行強制類型轉換，在轉換的時候也要特別注意，如果該條目的該字段沒有填寫任何內容，那麼該返回值是null，如果不加以檢查就進行類型轉換的話，會引發一個異常（NullReferenceException）。在使用這種方法填寫或修改字段數據的時候，除了DateTime類型的數據之外，可以一律使用string類型寫入（但是除非特殊需要，不建議使用這種做法）。
審批也是SharePoint列表的一個重要的特色，它允許一個列表條目呈現“已審批、待定、被拒絕”這三種狀態，在默認視圖中，只顯示已審批的條目，在“我的提交”視圖和“審批視圖”中，可以看到其他的條目。
在SharePoint中，一個列表條目的審批信息並非是保存在某個字段中的，而是在對象模型中對應爲SPModerationInformation類，並通過SPListItem.ModerationInfomation屬性來訪問，該類只有兩個屬性。
· Comments：審批意見。即列表管理員進行審批操作的時候所填寫的意見。
· Status：審批狀態。該屬性爲SPModerationStatusType枚舉類型，對應三種狀態。
需要注意的是，ModerationInfomation這一屬性，只有當列表允許審批的時候（即列表SPList的EnableModeration屬性爲true的時候）纔可以取得，否則，該值始終爲null。
在使用允許審批的列表的時候，獲取列表條目時會有一些不同。使用SPList.Items屬性只能獲得該列表中狀態爲“已通過”的那些列表條目，要獲得其他條目，則必須通過“我的提交”或“審批視圖”這兩個視圖，使用SPList.GetItems方法來取得。開啓了審批的列表都會有這兩個視圖存在，這兩個視圖SPView對象的ModerationType屬性分別爲“Contributor”和“Moderator”，表明屬於哪一個審批的視圖。
在SPListItem中，還有一些比較常用的屬性如下。
· Attachments：該列表條目的附件集合；
· File：如果該列表是文檔庫的話，得到該文件的對象（以上兩個屬性的使用請參考下一節“文件相關的對象模型”）；
· ID：在該列表中唯一標識該列表條目的整型的id；
· ModerationInfomation：該列表條目的審批信息；
· ParentList：該列表條目所在列表的對象；
· Xml：以Xml的格式返回該列表條目中的所有數據。
在列表條目的內容修改後，通過調用SPListItem.Update方法使修改生效。
添加一個列表條目的方法非常簡單，只需要調用SPListItemCollection.Add方法，該方法不需要參數，直接返回一個空的SPListItem對象，通過對該對象對各字段的內容進行修改，再調用Update方法，即可將該條目添加到該列表中。
刪除一個列表條目，有兩種方法：
· SPListItemCollection.DeleteById(int id)
通過列表條目的id來刪除該條目；
· SPListItemCollection.Delete(int index)
通過集合中的下標來刪除該條目。
在通過Delete方法刪除一個列表中的所有條目時，注意必須使用下面這種逆序的循環方法：
int total = items.Count;
for(int i=total-1; i>=0; i--)
items.Delete(i);
而不能正向的循環，更不能使用foreach循環來進行，在初學者中，這是一個比較常見的錯誤。請讀者自己思考這樣做的原因。
在SPListItemCollection類中，還有一個非常有用的方法：GetDataTable方法，即：
DataTable GetDataTable();
該方法可以返回由這些列表條目所組成的DataTable對象，以便將數據綁定到一些顯示控件（如DataGrid）上。但是注意當列表中沒有條目的時候，該函數返回的是null，而不是一個有效的DataTable對象。
【示例9-6】 通過SPQuery獲得Score字段中大於等於60的列表條目，並且在這些條目的標題後加上“（合格）”字符串，然後再另一列表中，添加一個新條目，寫入合格人數。
// 首先獲取到SPWeb對象web
SPListCollection lists = web.Lists;
SPList scoreList = lists["Score"];
SPList passList = lists["Pass"];
SPQuery query = new SPQuery();
query.Query = "<Where><Geq><FieldRef Name='Score'/>" +
"<Value Type='Number'>60</Value></Geq></Where>";
SPListItemCollection items = scoreList.GetItems(query);
foreach(SPListItem item in items)
{
string title = item["Title"] + "（合格）";
item["Title"] = title;
item.Update();
}
SPListItem newItem = passList.Items.Add();
newItem["Count"] = items.Count;
newItem.Update();
在該例中，爲了簡化場景，沒有考慮到不同人、不同科目的分數問題。另外，這個例子只是爲了說明和列表條目有關對象模型的使用方法，在實際的應用場景中，類似於上面這種問題，可以通過視圖的篩選、分組和彙總的功能在一張列表中直接完成，而且可以接受多人、多科目這種條件，分別統計每一科的合格人數，不需要進行任何編程，SharePoint中強大的視圖功能便可以體現在其中。請讀者自己思考視圖設置的方法。
文件相關的對象模型
SPAttachmentCollection的使用
在SharePoint的列表中，每個列表條目可以擁有0到多個附件文件（附件功能可以在列表常規設置中開啓或關閉），在對象模型中，訪問這些附件，則可以使用對象模型中的SPAttachmentCollection類來完成。
使用SPAttachmentCollection.Count屬性可以得到該列表條目中附件的個數，使用以下方法，則可以獲得每一個附件所在的地址。
· attachments[int index]：通過下標得到附件的文件名，這些附件實際上也是保存在SharePoint的文件系統中的，它們的url爲：“List/Attachments/ItemID/FileName”，自然地，SPAttachmentCollection的對象模型中也提供了這樣一個屬性來訪問這一串地址：
· UrlPrefix：附件文件的前綴url地址（絕對url）。
附件的添加和刪除，和添加、刪除文件的方法是一樣的。
· Add(string filename, byte[] data)：第一個參數指定文件名，第二個參數指定附件內容的字節流。該文件已經存在的時候，也會返回一個異常。
· Delete(string filename)：根據文件名刪除該附件。
與添加、刪除文件不同的是，因爲附件操作是包含在列表條目的修改之中，所以使用Add方法和Delete方法必須調用SPListItem.Update方法才能使修改生效。爲了更直接的對附件進行操作，免除Update這一麻煩，SPAttachmentCollection類中提供了AddNow和DeleteNow兩個方法，它們的參數和使用與Add和Delete方法一致，只是調用完之後立刻生效，而不再需要進行Update。
在一個列表條目生成之前，SPListItem中的一切屬性都是不可用的，所以在對附件進行操作的時候尤其要進行注意，只能對已有的列表條目進行附件的操作。在添加一個新的列表條目的時候，也必須先執行SPListItem.Update，使之成爲已有的列表條目，然後才能進行附件操作。
【示例9-9】 該示例讀取DemoList列表第一個列表條目的附件，並將它們保存到本地：
// 首先獲取到SPWeb對象web
SPList list = web.Lists["DemoList"];
SPListItem item = list.Items[0];
SPAttachmentCollection attach = item.Attachments;
for(int i=0; i<attach.Count; i++)
{
String url = attach.UrlPrefix + attach[i];
Console.WriteLine("正在下載{0}...", url);
SPFile file = web.GetFile(url);
FileStream fs = new FileStream(file.Name, FileMode.Create);
byte[] content = file.OpenBinary();
fs.Write(content, 0, content.Length);
fs.Close();
}
注意在該程序中，默認列表DemoList存在，也默認該列表中擁有至少一個列表條目。
文檔庫
文檔庫是SharePoint中非常重要的一個功能，它提供了例如簽入/簽出,結合Microsoft Office在線編輯、版本控制等諸多方便的功能。而在SharePoint的對象模型中文檔庫也是一個比較特殊的對象。
在SharePoint中，文檔庫有三種形式：文檔庫、表單庫、圖片庫。
作爲一個特殊的對象，文檔庫即是一個列表（List），也是一個文件夾（Folder）。這樣的特性就意味着文檔庫既可以通過SPList對象來訪問，也可以通過SPFolder和SPFile來訪問，它們之間是有着內在聯繫和明確分工的。
在使用SPList訪問的時候，它的“FileLeafRef”（內部名稱）字段保存的是文件的文件名，它可以通過定義視圖和查詢來查找我們所需要的某部分文件。在獲得SPListItem之後，也可以通過SPListItem.File來得到該列表條目所對應的文件（SPFile）的對象。但是由於是列表的形式，在獲得列表的時候是很按照文件夾的方式去獲取的，這個時候就需要結合另外的類來進行操作。
判斷一個列表是否是文檔庫，可以通過判斷SPList.BaseType屬性是否爲SPBaseType.DocumentLibrary來完成。而SharePoint也專門提供了一個SPList的子類——SPDocumentLibrary來訪問文檔庫，在判斷一個列表爲文檔庫之後，可以將該對象強制轉換爲SPDocumentLibrary類型，在該類型中，提供了一個有用的函數：
GetItemsInFolder(SPView view, SPFolder folder)：指定一個列表的視圖，指定一個文件夾，返回該文件夾內的文件所對應的列表條目集合對象（SPListItemCollection）。
同時，我們也可以通過SPList.RootFolder屬性得到該文檔庫的根目錄的對象（注意之前應把SPListCollection.IncludeRootFolder設爲true）。
在使用SPFolder和SPFile對象訪問文檔庫的時候，可以方便地獲取文檔庫中的層級結構，也可以得到文件的簽入/簽出狀態和版本控制信息，也可以方便地對文件進行復制、移動和刪除的操作。但是僅使用這種方法，卻無法獲得一個文檔的審批狀態。
在判斷文件夾是否爲文檔庫時，可以通過SPFolder.ContainingDocumentLibrary屬性來完成，如果該文件夾在文檔庫中，那麼該屬性會返回該文檔庫所在列表的Guid，可以藉此獲得列表對象；在判斷一個文件是否在文檔庫中時，使用SPFile.InDocumentLibrary屬性即可。在確定一個文件包含在文檔庫之後，通過SPFile.Item屬性就可以得到對應的列表條目對象（SPListItem）。
將SPFolder/SPFile與SPDocumentLibrary結合起來使用，可以充分地發揮SharePoint文檔庫的強大功能。此外，SharePoint文檔庫還提供了文檔討論的功能，通過ie的一個ActiveX插件來對每一篇文檔進行討論，在對象模型中也提供了SPDocDiscussion類獲得該討論的部分信息，有興趣的用戶可以參考SDK中的相關章節。
在使用文檔庫的時候，尤其是在中文SharePoint系統中，特別需要注意的是，要明確“列表名稱”和“目錄名稱”這兩個不同的概念，這兩者可能是不同的，例如，一個文檔庫的名稱叫做“共享文檔”（列表的名稱），而它所在的url是“Shared Document”（目錄的名稱）。在使用SPList和SPFolder的時候，不要將這兩者混淆起來。
用戶/權限相關的對象模型
權限系統是SharePoint的另一大特點，在WSS中，權限可以劃分到列表級，而且SharePoint的權限是詳細到代碼級別的，稱爲CAS（Code Access Security），也就是說每一個對象模型中的方法、屬性的訪問都會涉及到權限的問題。這也是爲什麼前兩章都要使用命令行（Console）方式的程序作爲示例，而且直接在服務器端運行的原因（正如本章一開始所說的，默認讀者是以管理員的身份在服務器端進行操作）。在這樣一種權限的機制上，應該說整個SharePoint環境是比較安全的，除非直接讀取底層數據庫，否則用戶無法獲得其權限之外的數據；然而在另一個角度上，這種權限的機制也比較死板，只要數據在用戶的訪問或修改權限之內，那麼使用普通的方法也是無法真正限制用戶對數據的訪問和修改的。
而在用戶系統上，SharePoint可以與AD相結合，通過AD來管理、組織用戶，可以說非常靈活和強大。
一般來說，用戶系統與權限系統是比較緊密地結合在一起的，SharePoint也不例外。因此，本節將兩者結合起來介紹。SharePoint對象模型中與用戶/權限相關的類主要有以下三個：SPPermission、SPRole、SPUser。
SPPermission的使用
在SharePoint中，由於權限是深入到代碼級別的，在每執行一句代碼——尤其是對數據進行修改、對系統進行管理的代碼——的時候，都有可能會因爲當前執行者的權限不足而引發異常。雖然try-catch能夠在事後檢測並捕獲到大部分這種異常，但是，事前的檢測在代碼編寫的過程中有時也是必要的；而有的時候，也需要根據用戶的不同權限顯示出不同的信息。用戶權限的檢測就是通過SPPermission類來完成的。
在介紹SPPermission類之前，有必要先簡要介紹一下和權限相關的重要的枚舉類型SPRights。在這個枚舉類型中，列舉了所有WSS網站中所用到的權限，例如創建列表條目、修改列表條目、刪除列表條目等。在使用這些權限的時候，可以通過二進制掩模（Mask）的方式，將多個權限進行或（or）操作，得到一個新的包含所有用戶指定的權限的SPRights變量，後文中的PermissionMask一般都是通過這種方法獲得的。由於篇幅關係，這些具體的權限及其含義就不在此列出了，需要使用的時候，請讀者參考SDK中的相關內容。
另外，SharePoint也提供了SPPermissionGroup枚舉類型，其中定義了每種角色的PermissionMask，在需要獲取角色默認權限的時候，可以直接使用該枚舉類型。
權限都是掛靠在某個對象上的（比如網站、列表等），在訪問這些對象的權限的時候，可以直接通過SPWeb.Permissions屬性和SPList.Permissions屬性來獲得。獲取某個具體的用戶、角色的權限的時候，通過以下方法來取得：
· permissions[SPMember member]
其中SPMember是表示用戶的SPUser類、表示角色的SPRole類、表示用戶組的SPGroup類的一個父類。通過這種方式，可以獲得某個網站（或列表）上，某個用戶（或角色）的權限。
添加、刪除某個用戶的權限的時候，同樣通過SPPermissionCollection類的方法來完成：
· Add(SPMember member, SPRights permissionMask)：爲某個網站成員（用戶或角色）添加permissionMask中指定的權限；
· Remove(SPMember member)：刪除指定網站成員的權限；
· ResetPermissions()：按照父網站的權限設置，重置該對象的權限。
在得到一個SPPermission對象之後，可以使用它的一些屬性：
· Member：一個SPMember的對象，即擁有該權限的成員；
· Parent：一個Object的對象，即擁有該權限的對象（SPWeb或SPList）；
· PermissionMask：具體的權限設置；
· Xml：以xml形式描述的權限設置。
通過將PermissionMask屬性與SPRights枚舉中的某些具體權限進行與（and）操作，根據操作結果是否非零，來表明該成員在該對象上是否擁有該權限。
但是，正如本節一開始所提到的，之所以需要檢查權限的設置，是因爲有一些用戶沒有權限來進行數據的操作或系統的設置。而上面所涉及到的那些方法和屬性所需要的對於權限的控制的權限，顯然是“普通用戶”所不具備的。好在SharePoint爲我們提供了一個“普通用戶”也可以執行的方法，用來檢測權限，它是SPPermissionCollection中的一個方法：
· DoesUserHavePermission(SPRights permissionMask)
檢測當前的用戶是否具有參數中所描述的權限，該方法返回一個bool型的值。在執行某些語句之前，或者在需要針對不同權限用戶顯示不同內容的時候，通過調用這個方法，就可以明確地知道當前執行這段代碼的用戶，是否具有某種權限，從而再進行相應的處理。
【示例9-10】 列舉某個網站上當前用戶的所有權限：
// 首先獲取到SPWeb對象web
foreach(SPRights right in Enum.GetValues(typeof(SPRights)))
{
if(web.Permissions.DoesUserHavePermissions(right))
{
Console.WriteLine(right.ToString());
}
}
讀者可以使用不同的網站用戶身份登錄服務器運行這段代碼，觀察得到的結果有何不同。
SPUser的使用
SPUser是SharePoint中的用戶類，在獲取SPUser對象的時候，可以通過SPWeb.Users、SPWeb.AllUsers或者SPRole.Users來得到一個SPUserCollection，再通過以下兩種方式得到用戶。
· users[string loginName]：以登錄名獲取到集合中的用戶；
· users[int index]：以集合中的下標獲取到用戶。
也可以使用如下方法。
· GetByID(int id)：通過用戶id獲取某個用戶的對象；
· GetByEmail(string email）：通過用戶的電子郵件地址獲取某個用戶的對象。
如果只需要獲取到當前用戶的話，也可以方便地使用SPWeb.CurrentUser屬性。
爲某個集合添加、刪除用戶的時候，使用SPUserCollection類中的方法。
· AddCollection(SPUserInfo[] users)：添加一批用戶，其中SPUserInfo是一個簡單的結構，其中包含Email、LoginName、Name和Notes這四個屬性，屬性的含義見SPUser類的屬性；
· Remove(int index)：通過集合中的下標來刪除集合中的用戶；
· Remove(string loginName)：通過用戶的登錄名來刪除該用戶；
· RemoveByID(int id)：通過用戶的id來刪除該用戶；
· RemoveCollection(string[] loginNames)：通過登錄名刪除一批用戶。
SPUser有如下幾個常用的屬性。
· Email：用戶的E-mail地址；
· ID：在當前Site上，唯一標識該用戶的id（int型）（只讀）；
· IsDomainGroup：該用戶是否是一個域組（只讀）；
· IsSiteAdmin：當前用戶是否是網站管理員（只讀）；
· LoginName：用戶的登錄名（只讀）；
· Name：用戶的顯示名稱；
· Notes：用戶的簡要說明；
· ParentWeb：該用戶所在的網站（只讀）；
· Roles：該用戶在該網站的角色；
· Xml：該用戶信息的xml形式的描述（只讀）。
需要值得注意的是，在上述的用戶信息中，只有LoginName是唯一的（也是全局唯一的），在不同的網站上，用戶可能擁有不同的E-mail、顯示名稱和簡介。
在修改用戶的屬性之後，需要調用SPUser.Update方法使修改生效。
爲用戶添加角色的過程，一般而言，是通過在角色中加入該用戶來完成的，將在下一部分介紹這一方法。
SPRole的使用
SPRole對應於WSS網站中的用戶角色（也稱爲網站用戶組，即Site Group）。首先要特別提醒讀者注意的是，該對象模型只能應用於WSS網站中，在SPS網站中使用該對象，則會直接引發錯誤，並且該錯誤無法被try-catch所捕獲，請特別加以小心。
獲取SPRole的對象，一般也是先通過SPWeb.Roles屬性或者SPUser.Roles屬性得到一個SPRoleCollection對象，再通過以下兩種形式得到特定的SPRole。
· roles[string name]：通過角色的名稱獲取；
· roles[int index]：通過集合中的下標獲取；
或者使用如下方法。
· GetByID(int id)：通過角色的id獲取；
· GetSpecialRole(SPRoleType type)：一般來說，網站會默認的擁有一些特殊的角色（管理員、網站設計者、討論參與者、讀者和來賓），在對象模型中，SPRoleType枚舉類型對應這五種已有的角色。該方法可以直接獲得這五種特殊的角色之一。
添加、刪除角色的時候使用SPRoleCollection中的方法。
· Add(string name, string description, SPRights permissionMask)：添加一個角色，第一個參數指定角色的名稱，第二個參數指定角色的描述，第三個參數指定角色所擁有的權限；
· Remove(int index)：通過在集合中的下標刪除該角色；
· Remove(string name)：通過角色名稱刪除該角色；
· RemoveByID(int id)：通過角色的id刪除該角色。
SPRole的常用屬性如下：
· Description：該角色的描述信息；
· ID：在該網站上唯一標識該角色的ID（int型）（只讀）；
· Name：該角色的名稱；
· ParentWeb：該角色所在網站的對象（只讀）；
· PermissionMask：該角色所擁有的權限；
· Type：該角色的類型（僅對特殊角色有效）（只讀）；
· Users：該角色中的用戶的集合；
· Xml：該角色的xml形式的描述（只讀）。
在修改角色的信息後，需要調用SPRole.Update方法使修改生效。
在管理一個角色中的用戶的時候，直接使用SPRole的方法（而不是在SPRole.Users屬性中進行添加或刪除）。
· AddUser(SPUser user)：直接通過該用戶的SPUser的對象實例來添加該用戶；
· AddUser(string loginName, string email, string name, string notes)：通過用戶的基本信息添加該用戶；
· RemoveUser(SPUser user)：刪除該用戶。
【示例9-11】 獲取網站中的角色，在不存在當前用戶的角色中加入當前用戶，然後遍歷該角色中的所有用戶。
// 首先獲取到SPWeb對象web
SPUser current = web.CurrentUser;
foreach(SPRole role in web.Roles)
{
Console.WriteLine("Role:{0}", role.Name);
if(role.Type != SPRoleType.Guest)
try
{
SPUser user = role.Users[current.LoginName];
}
catch
{
role.AddUser(current);
}
foreach(SPUser user in role.Users)
Console.WriteLine("\tUser:{0}", user.Name);
}
在該示例中，在添加用戶的時候排除掉了“來賓”這一角色，這是因爲該角色一般只應用在SPS的網站當中，無法將WSS網站中的普通用戶加入該角色當中。
SharePoint的文件系統同樣分爲文件和文件夾這兩大組成部分，但是與普通的asp.net編程不同的是，SharePoint中的文件和文件夾絕大部分是保存在數據庫中的，只有一少部分（“_layouts”目錄下的文件）是直接保存在服務器的文件系統中（這些文件默認的路徑爲：“C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\ LAYOUTS”）。在一般的程序編寫中，極少有需要去訪問“_layouts”目錄下的文件，而訪問其他的文件（包括網頁、文檔庫、圖片庫等）都需要通過SharePoint的對象模型來完成。本節主要介紹SharePoint文件相關的對象模型SPFolder和SPFile，之後會介紹列表中附件的對象模型SPAttachmentCollection，最後用一定的篇幅對SharePoint中特殊的列表“文檔庫”進行一些簡要地說明。
SPFolder的使用
SPFolder是SharePoint對象模型中文件夾相關的類，它的使用方法相對比較簡單。獲取一個SPFolder的對象可以通過SPFolderCollection使用以下兩種方法獲得。
· folders[int index]：通過文件夾集合中的下標來獲得；
· folders[string url]：通過該文件夾的url來獲得。
而SPFolderCollection對象一般可通過SPWeb.Folders屬性或SPFolder.SubFolders屬性來獲得。
而在SPWeb和SPList的對象模型中，都有該網站（或列表）所在的根目錄的信息，可以直接通過SPWeb.RootFolder屬性和SPList.RootFolder屬性得到。但是需要特別指出的是，SPList.RootFolder的訪問默認是沒有開啓的，如果想通過這種方法得到一個SPFolder對象，必須先將SPListCollection.IncludeRootFolder屬性設爲true。
在SPWeb中，也可以使用GetFolder方法來獲得該網站中的某個文件夾對應的SPFolder對象。
· GetFolder(string url)：參數爲該文件夾所對應的路徑（注意不要包含最後的“/”字符）。
文件夾的添加和刪除同樣是通過SPFolderCollection來完成的。
· Add(string url)：添加一個文件夾，參數爲待添加文件夾的url，該函數成功後直接返回一個SPFolder對象；
· Delete(string url)：刪除一個文件夾，參數爲待刪除文件夾的url。
在SPFolder類中，有如下一些常用的屬性。
· ContainingDocumentLibrary：如果該文件夾是包含於一個文檔庫中的，那麼該屬性返回標識該文檔庫列表的Guid。該屬性只讀；
· Exists：判斷該文件夾是否存在，在獲取一個文件夾之後（尤其是通過url的方式獲取一個文件夾之後），非常有必要先判斷該文件夾是否存在，因爲在獲取文件夾的時候，文件夾不存在並不會引發異常，而在使用一個不存在的文件夾的時候，必然會引發異常。該屬性只讀；
· Files：該文件夾下的所有文件的集合；
· Name：該文件夾的名稱（只讀）；
· ParentFolder：它的上一級文件夾的對象（只讀）；
· ParentWeb：該文件夾所在網站的對象（只讀）；
· ServerRelativeUrl：該文件夾相對於服務器根地址的url（只讀）；
· SubFolders：該文件夾下所有子文件夾的集合；
· Url：該文件夾相對於其所在網站的url（只讀）。
SPFolder也提供了兩個非常有用的函數。
·CopyTo(string newUrl)：將該文件夾複製到參數所指定的url中；
·MoveTo(string newUrl)：將該文件夾移動到參數所指定的url中。
【示例9-7】 一個簡單的函數，通過遞歸的方法遍歷某文件夾下的層級結構：
void LookupFolders(SPFolder parentFolder, int level)
{
for(int i=0; i<level; i++)
Console.Write('\t');
Console.WriteLine(parentFolder.Name);
foreach(SPFolder subFolder in parentFolder.SubFolders)
{
if(subFolder.Exists)
LookupFolders(subFolder, level+1);
}
}
SPFile的使用
SPFile對應於SharePoint對象模型中的文件，它的使用方法與SPFolder類大致相似。在獲取SPFile對象的時候，仍是通過SPFileCollection來進行，形式也與獲取SPFolder相同。在SPWeb中，也同樣提供了SPWeb.GetFile方法來獲取一個文件。
· GetFile(string url)：參數爲該文件所在的url。
此外，對於文檔庫列表中的列表條目來說，也可以通過SPListItem.File來得到該文件的對象（關於文檔庫，稍候會進一步加以說明）。
在刪除文件的時候，同樣使用SPFile.Delete方法。
· Delete(string url)：參數爲待刪除文件的url。
添加一個文件與添加文件夾稍有不同，需要指定文件的內容，並且有如下三種不同的形式。
· Add(string url, byte[] content)：第一個參數指定待添加文件的url，第二個參數中以字節流的方式指定文件的內容。在指定文件url的時候，既可以使用完整的url（需要保證該目錄存在），也可以只使用文件名（即添加到當前文件夾中）。使用該方法添加文件的時候，如果該url已經存在一個文件，則該函數會引發一個異常；
· Add(string url, byte[] content, bool overwrite)：與上一種形式不同，這種形式通過第三個參數來指定當文件已存在時，是否進行覆蓋。當overwrite爲true時，會對重名的文件進行覆蓋；否則，如果出現重名的情況，仍然會引發一個異常；
· Add(string url, byte[] content, SPUser createdBy, SPUser lastModifiedBy, DateTime timeCreated, DateTime timeLastModified)：添加文件的時候，根據後4個參數，指定文件的創建者、修改者、創建時間、修改時間。但是在使用這種形式的時候需要注意，該程序的執行者必須爲網站的管理員，而且該形式只有在WSS網站上有效（在SPS網站上，該方法會產生一個“Access Denied”錯誤）。
以上三種方法在創建成功之後均會直接返回一個SPFile類型的對象。
SPFile類中一些屬性及其含義如下，這些屬性一律爲只讀的。
· Author：文件的創建者，是一個SPUser類的對象（關於該類，會在下一節中進行說明）；
· CheckedOutBy：文檔庫的文件允許進行簽入和簽出的操作，該屬性爲簽出的用戶；
· CheckedOutDate：文件簽出的時間；
· CheckedInComment：文件簽入時的評論內容；
· CheckOutExpires：文件簽出的過期時間；
· CheckOutStatus：文件簽出的狀態，
· Exists：該文件是否存在；
· IconUrl：SharePoint爲每種常用類型的文件都提供了圖標，該屬性中保存了該圖標的圖像文件的文件名（並非完整的url），這些圖片一般保存在“_layouts/images/”目錄下；
· InDocumentLibrary：表示該文件是否在文檔庫中；
· Item：如果該文件在文檔庫中，那麼該屬性（SPListItem類）獲取該文件在該文檔庫列表中的列表條目對象；
· Length：文件的大小（以字節爲單位）；
· ModifiedBy：該文件的最後修改者；
· Name：該文件的文件名；
· ParentFolder：該文件所在的目錄對象；
· Properties：一個Hashtable型的對象，包括該文件的一些常用屬性（例如創建者、創建時間、修改者、修改時間、文件大小、文件的版本等信息）；
· ServerRelativeUrl：該文件相對於服務器根地址的url；
· TimeCreated：文件創建的時間；
· TimeLastModified：文件最後修改的時間；
· Url：該文件相對於其所在網站的地址；
· Versions：SPFileVersionCollection類的對象，SharePoint的文檔庫可以支持文檔的版本管理和控制，該屬性中保存了該文件自創建以來的各個版本，同時保存了各版本的信息。（由於篇幅所限，不再一一列舉SPFileVersion類的屬性，有興趣的讀者請參考SDK。）
SPFile類中也同樣提供了一些方法。
· CheckIn()：將文件簽入文檔庫；
· CheckOut()：將文件從文檔庫中籤出；
· CopyTo(string newUrl)：將文件複製到一個新的url地址中；
· CopyTo(string newUrl, bool overwrite)：將文件複製到新的url地址中，並指定是否覆蓋同名文件；
· MoveTo(string newUrl)：將文件移動到一個新的地址中；
· MoveTo(string newUrl, bool overwrite)：將文件移動到一個新的地址中，並指定是否覆蓋同名文件；
· OpenBinary()：以byte[]的形式返回該文件的內容；
· SaveBinary(byte[] content)：以參數爲內容，保存該文件。
【示例9-8】 該示例中演示了從本地上傳文件到文檔庫的過程：
// 首先獲取到SPWeb對象web
SPFolder folder = web.GetFolder("Shared Documents");
if(folder.Exists)
{
FileStream fs = new FileStream(@"C:\Demo.txt", FileMode.Open);
byte[] content = new byte[fs.Length];
fs.Read(content, 0, (int)fs.Length);
folder.Files.Add("Demo.txt", content);
fs.Close();
}
else
Console.WriteLine("Folder Not Exist!");
該程序中的FileStream類和FileMode枚舉是在System.IO命名空間中。