?

網站相關的對象模型

作為一個應用原型系統(tǒng)，SharePoint提供了很多強大的應用及管理功能，但是，在實際的應用中，這些原有的功能很難滿足用戶的需求。因此，SharePoint也提供了一套非常完整的對象模型作為底層接口，以此為基礎進行二次開發(fā)。

Windows SharePoint Services（以下簡稱WSS）作為SharePoint Portal Server（以下簡稱SPS）的基礎部分，是在開發(fā)過程中使用最多的一套體系。因此，在本書開發(fā)部分的開始，使用一章的篇幅來介紹WSS的對象模型體系，以及一些簡單的應用。

WSS提供了非常完善的一套對象模型體系，大致整個的Web服務器（SPWebServer類）、小到一個文件的版本信息（SPFileVersion類），以及一些網站的設置，都可以通過WSS對象模型來進行訪問或修改。此外，為了彌補.NET類庫在該環(huán)境中的一些不足，在SharePoint中也提供了一些常用的功能的函數(shù)，它們被封裝在Microsoft.SharePoint.Utilities命名空間中。

通過使用SharePoint的對象模型，可以完成幾乎所有的功能，但是在有些時候，由于SharePoint本身的限制（例如嚴格的權限控制），有一些功能僅使用對象模型是很難完成甚至無法完成的。所以，在考慮用戶需求和設計方案的時候，也應該盡可能地考慮到實現(xiàn)的難易程度。

在WSS對象模型體系中，提供了如下一些命名空間（namespace）：

·??? Microsoft.HtmlTrans.Interface

提供一個接口，用來將文檔庫中的某些文件以Html的形式顯示到客戶端，這樣在客戶端沒有安裝相應文件的瀏覽軟件的時候，也可以查看這些文件；

·??? Microsoft.SharePoint

該命名空間是最常用的一個命名空間，其中提供了WSS中關于網站內容的基本的對象模型，例如網站、列表、文件和用戶等，本章也主要是圍繞這一命名空間進行介紹；

·??? Microsoft.SharePoint.Administration

該命名空間中主要提供了WSS網站管理和參數(shù)設置的一些類；

·??? Microsoft.SharePoint.Dsp

該命名空間以及之下的幾個命名空間提供了一些WSS數(shù)據搜索用的接口；

·??? 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開發(fā)中一個重點的環(huán)節(jié)，我們將在第11章中對其進行詳細地敘述；

·??? Microsoft.SharePoint.WebPartPages.Communication

該命名空間提供了對Web部件通信的支持。

以上這些命名空間和類庫封裝在Microsoft.SharePoint.dll中。

由于篇幅的關系，在本章中只介紹最基本的一些對象模型的使用，只涉及到Microsoft.SharePoint這一命名空間。其他對象模型的使用方法請參照SDK。

為了便于實現(xiàn)和觀察，也便于避開Web環(huán)境中一些復雜的機制和權限控制，本章和下一章的示例代碼，均使用命令行（Console）方式完成。程序需要直接運行在裝有WSS或SPS的服務器上，并且默認操作者具有網站管理員的權限。此外，本章和第10章著重講解功能和某些注意事項，因此在介紹對象模型的時候，只介紹最常用的一些屬性和方法，并且在每部分的最后給出一個示例說明該對象模型的使用方法。更全面的類庫、屬性和方法的介紹，以及更加詳細的示例程序，請參考SDK中對應的章節(jié)。

本書中的代碼均使用C#語言編寫，在WSS或SPS環(huán)境中經過測試通過。

在絕大多數(shù)的WSS使用場景以及部分SPS的使用場景中，“網站”是使用得最多的一個對象，這是因為在WSS的體系結構中，幾乎所有的內容（包括用戶、列表、文件系統(tǒng)等）都是依附于網站之上的，這一點在對象模型中也能很明顯地體現(xiàn)出來。

在WSS的結構中，網站被劃分為Site（網站集）和Web（網站）這兩種概念。

?Site和Web的區(qū)別與聯(lián)系

顧名思義，網站集是網站的集合體，在WSS中，Site的主要用處是管理網站，在對象模型中，Site所對應的SPSite除了網站的集合（SPWebCollection）外幾乎不包含任何的信息，所有的信息都是儲存在Web所對應的SPWeb這一對象模型中的，Web才是真正的內容承載者。

在SharePoint的最初設計理念中，將網站集稱為Web，而網站稱為Site，這一點從SDK中的SharePoint體系結構圖中可以看出來。

但是，在設計對象模型的時候，卻又將網站集的對象模型稱為SPSite（即SharePoint Site），而網站的對象模型稱為SPWeb。因此在SDK的代碼示例中經常可以看到例如“SPSite web;”以及“SPWeb site;”這樣的變量命名方法，這對于初學者來說是非常容易引起混淆的。

作為開發(fā)的參考，為了便于說明，以及和對象模型的統(tǒng)一，本書中所指的Site均為網站集的概念（對應于SPSite），而Web均為網站的概念（對應于SPWeb），請讀者注意。

?SPSite的使用

SPSite作為網站集對應的對象模型，其主要的用處是獲取某個特定的網站，它最常用的幾個功能如下：
???????? 構造函數(shù)
SPSite的構造函數(shù)有兩種，分別以Site的url和Guid作為參數(shù)。
在SharePoint對象模型中，大部分對象都擁有一個Guid作為它唯一的標識符，通過這個Guid可以獲取該對象的實例，例如Site（SPSite）、Web（SPWeb）、列表（SPList）、視圖（SPView）以及SPS中的區(qū)域（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函數(shù)
該函數(shù)返回一個SPWeb類型的變量，通過該函數(shù)可以獲得該網站集中一個特定的網站。它有以下三種使用形式：
·????? OpenWeb()：在命令行模式中，該方法返回網站級中的頂級網站對象；但是在網絡環(huán)境中使用該方法會有不同的效果，詳見第11章11.3小節(jié)“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)
??????? {
??????????? // 使用構造函數(shù)創(chuàng)建網站集對象
??????????? 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是一套相對龐大的對象模型體系，在編寫程序的過程中，難免會出現(xiàn)預料之外的問題，因此應該盡可能對所有可能出錯的語句進行try-catch，如果有必要，捕獲每種特定的異常，并提供更加友好的出錯信息，使得程序更加人性化。在本書中，為了節(jié)省篇幅，除非特殊的需要和說明，在后面的示例程序中一般不進行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。在本書后續(xù)章節(jié)中除非特殊情況，不再使用完整的代碼，而使用代碼片段作為示例。
?

SPWeb的使用

在一般的應用場景下，SPWeb是使用最多的一個對象模型，因為幾乎所有的WSS的內容都是依附于SPWeb對象的，在編程中也是使用SPWeb來獲取其他的對象模型。而獲取SPWeb對象的方法在本章9.2.2小節(jié)“SPSite的使用”中已經有所提及，就不在這里重復了。

大多數(shù)和WSS相關的內容都是通過使用SPWeb的一些成員變量來獲取的，這些成員變量主要有：

·????? AllUsers：網站內的所有成員，以及通過域組（domain group）來瀏覽網站的用戶；

·????? Files：網站下的所有文件；

·????? Folders：網站下的所有目錄；

·????? Groups：所有跨網站用戶組；

·????? Lists：網站下的所有列表；

·????? ListTemplates：網站下的所有列表模板；

·????? Permissions：網站下的權限；

·????? Roles：網站下的所有角色；

·????? Users：屬于該網站的所有用戶；

·????? Webs：該網站的所有子網站。

通過使用這些成員變量，就可以獲取到相應內容的對象集合（Collection），進而獲取需要的內容。

此外，SPWeb的某些成員變量對應于該網站的一些屬性，例如：

·????? AllowAnonymousAccess：網站是否允許匿名訪問（只讀）；

·????? Author：網站的創(chuàng)建者（只讀）；

·????? Created：網站的創(chuàng)建時間（只讀）；

·????? 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函數(shù)（繼承自Object類），一般來說每個類也都會對這個方法進行重寫。SPWeb的ToString方法一般情況下就是返回了SPWeb.Title這個屬性。在大多數(shù)字符串操作過程中，一個對象的ToString方法是可以被隱式調用的（例如示例9-1中就使用了這個特性），在不知道該對象是否為空（null）的時候，如果顯式調用ToString方法會造成一個異常（NullReferenceException），但是在隱式調用的時候便不會產生這個異常，如果僅是作為輸出的需要，隱式的調用要比顯式的調用更加方便。

在示例9-2中，輸出每個網站的父網站，但是對于頂級網站來說，其父網站為空，如果顯示調用的話，便會出現(xiàn)異常，采用隱式調用就可以避開這個問題，只顯示一個空的字符串。

示例9-2中使用了三種輸出網站標題的方法：SPWeb.Title屬性，隱式調用SPWeb.ToString方法，顯式調用SPWeb.ToString方法。

列表相關的對象模型

在SharePoint中，列表（List）是一個非常強大的功能。它可以方便地自定義列表的結構，添加和刪除各種類型的字段，也可以設置計算字段和引用字段，也可以設置列表條目的審批功能，同時列表還提供了多種可以自定義的視圖，對列表的數(shù)據進行篩選或者排序。本節(jié)主要介紹列表相關的對象，包括列表（SPList）、列表視圖（SPListView）、列表字段（SPField）和列表條目（SPListItem）。

SPList的使用

在使用列表的功能之前，通常都需要首先獲取該列表對象，獲取SPList的主要方法是通過訪問SPWeb.Lists這一SPListCollection類型的屬性。從該集合中獲得一個特定的列表對象有如下三種方法：

·????? lists[string name]：通過該列表的名稱獲取；

·????? lists[Guid guid]：通過唯一標識該列表的Guid獲取；

·????? lists[int index]：通過列表在該列表集合中的下標來獲取

在網站上添加列表，也是通過SPListCollection對象來完成的。添加一個列表通過調用SPListCollection.Add方法來完成，創(chuàng)建成功之后，會返回新列表的Guid。該方法提供了如下三種形式：

·????? Add（string title, string description, SPListTemplate template）：

前兩個參數(shù)分別指定列表的名稱和簡介，第三個參數(shù)是一個SPListTemplate型變量，指定該列表創(chuàng)建時所需要的列表模板對象，該對象可以通過SPWeb.ListTemplates屬性獲得；

·????? Add（string title, string description, SPListTemplateType type）：

前兩個參數(shù)指定列表的名稱和簡介，第三個參數(shù)使用SPListTemplateType型枚舉指定列表模板，枚舉中所包含的都是網站默認擁有的基本類型的列表模板，如果要創(chuàng)建一個自定義的列表，請使用SPListTemplateType.GenericList作為該參數(shù)；

·????? Add（string title, string description, SPListTemplate template, SPDocTemplate docTemplate）：

該方法會創(chuàng)建一個文檔庫（一種特殊的列表），前兩個參數(shù)分別指定列表的名稱和簡介，第三個參數(shù)制定列表的模板對象，第四個參數(shù)指定文檔庫的模板對象，該參數(shù)是一個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的區(qū)別：BaseTemplate是生成列表的模板，例如“鏈接”和“聯(lián)系人”等，每個模板中都默認設置了一些獨有的字段，該屬性為SPListTemplateType型的枚舉類型，默認這些模板的字段設置可以在SDK的“Field Tables for Default Lists”一節(jié)中找到；它的具體位置為Microsoft Windows Share Point Services?Appendix?Field Tables for Default Lists，而BaseType則是列表的基礎類型，例如“討論區(qū)”、“文檔庫”等，每種基礎類型的列表都提供了一些普通列表所不具備的特殊的功能，該屬性為SPBaseType型的枚舉類型。

修改列表屬性后，通過調用SPList.Update方法使修改生效。

【示例9-3】? 在該示例中創(chuàng)建一個聯(lián)系人列表，并顯示該列表添加條目頁面的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中，列表中所有的數(shù)據都是通過視圖呈現(xiàn)給用戶的，視圖中定義了需要顯示的字段，以及顯示的方式，某一些特殊的列表默認擁有一些特殊的視圖將數(shù)據呈現(xiàn)出來，例如“任務”模板列表中的“日歷視圖”，等等。

除了負責數(shù)據的多樣化顯示，視圖的另外一個重要的作用就是對數(shù)據的篩選和排序，在SharePoint環(huán)境中可以直接對視圖的這些內容方便地進行修改，通過使用計算字段，可以更加豐富篩選和排序的功能。

獲取一個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參數(shù)指定了視圖的名稱，fields參數(shù)指定了需要顯示的字段名的集合，query參數(shù)指定了對數(shù)據的篩選條件，rowLimit參數(shù)指定了視圖中一次所返回的列表條目的最大個數(shù)，paged參數(shù)指定了該視圖是否支持翻頁，makeDefault參數(shù)指定了是否需要將該視圖作為默認視圖；

·????? Add(string name, StringCollection fields, string query,

???????? uint rowLimit, bool paged, bool makeDefault，

·????? SPViewCollection.SPViewType type, bool personalView)：

前面的參數(shù)含義與上文相同，type參數(shù)指定了該視圖的基本類型，personalView參數(shù)指定了該視圖是否為個人視圖（否則為公共視圖）。

需要注意的是，與列表的添加方法不同，視圖的添加方法返回的對象是SPView的對象，而不是一個Guid。

刪除一個視圖同樣使用SPViewCollection.Delete方法，用視圖的Guid作為參數(shù)。

有一點需要注意的是，在使用默認頁面瀏覽一個視圖的時候，視圖的翻頁功能只有“下一頁”而沒有“上一頁”，如果需要實現(xiàn)向前翻頁的功能，需要自己編寫程序來完成。

SPView中常用的一些屬性如下：

·????? ID：標識該視圖的唯一的Guid；

·????? ParentList：包含該視圖的列表對象（SPList）；

·????? PropertiesXml：該視圖的基本信息，包括url、名稱和類型等（只讀）；

·????? Query：視圖中對數(shù)據進行篩選的查詢xml字符串；

·????? SchemaXml：該視圖的信息，包括基本信息和例如篩選、分組等的設置（只讀）；

·????? Title：該視圖的名稱；

·????? ViewFields：該視圖需要顯示的字段的集合；

·????? Url：顯示該視圖所對應的url（只讀）；

修改視圖屬性后，使用SPView.Update方法使修改生效。

【示例9-4】? 該示例中創(chuàng)建了一個視圖，并指定了該視圖的一些設置：

// 首先獲取到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）對象，和傳統(tǒng)的數(shù)據表一樣，SharePoint的列表也是由若干個字段所組成的，每個字段可以設置為不同的數(shù)據類型，也可以擁有不同的屬性設置（例如默認值、是否隱藏、是否可以為空等）。而SharePoint列表的最大一個特點，就是字段的可定制性，不需要進行任何的編程，也不用深入數(shù)據庫進行復雜的調整，僅在使用界面上就可以方便地對列表的字段進行添加、刪除和修改，這種方便的特性也正是很多用戶喜愛SharePoint的一個重要原因。

獲得一個SPField對象的方法主要是通過SPList.Fields屬性得到所有字段，再通過以下兩種方法得到特定字段的對象。

·????? fields[string dispName]：根據該字段的顯示名稱獲得

·????? fields[int index]：根據該字段在集合中的下標獲得。

為列表添加一個字段有三種方法：

·????? Add(string dispName, SPFieldType type, bool bRequired)

其中第一個參數(shù)指定該字段的顯示名稱，第二個參數(shù)指定該字段的類型，第三個參數(shù)指定在填寫數(shù)據的時候，該字段是否為必填內容。

·????? AddLookup(string dispName, Guid lookupListID, bool bRequired)

該方法為列表添加一個特殊的字段——“查閱項”字段，通過第二個參數(shù)指定目標列表的Guid，其余兩個參數(shù)的含義和使用方法與Add方法相同。

·????? AddFieldAsXml(string strXml)

通過一段xml的描述添加一個字段，該描述中需要包括字段等信息，實際上，這段xml描述對應于SPField.SchemaXml屬性。

需要特別注意的是，以上三種方法所返回的雖然都是string型的變量，但是它們的含義各不相同，Add方法返回的是顯示名稱，AddLookup方法所返回的是內部名稱（這兩者的區(qū)別稍候會進行介紹），而AddFieldAsXml方法所返回的是一段包含字段名稱的xml。

注意

在添加字段時，bRequired參數(shù)（對應與SPField.Required屬性）指定的是在用戶界面中新建、修改列表項的時候，該字段是否為必填內容。但實際上，如果我們通過對象模型來創(chuàng)建或修改一個列表條目的時候，該字段并不會起到任何限制作用。

SPField擁有如下一些比較常用的屬性。

·????? DefaultFormula：計算字段的公式；

·????? DefaultValue：字段的默認值，即該字段在未進行設置時的初始值；

·????? Description：該字段的說明描述信息；

·????? Filterable：該字段是否可以被篩選（只讀）；

·????? Hidden：該字段是否在列表中顯示；

·????? InernalName：該字段的內部名稱；

·????? ParentList：該字段所在的列表的對象；

·????? ReadOnlyField：該字段是否被只讀；

·????? Required：在填寫數(shù)據的時候，該字段是否必填；

·????? 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屬性的時候，我們會發(fā)現(xiàn)除了SPField以及它的子類所包含的一些屬性之外，還會有一個“ColName”屬性，實際上這個屬性是和SharePoint列表實現(xiàn)的具體機制相關的，它保存的是在底層數(shù)據庫的某個表中存放該字段那一列的名稱。關于這一點，會在第12章高級開發(fā)中，進行比較詳細的介紹。

修改字段的屬性后，通過調用SPField.Update方法使修改生效。

【示例9-5】? 為列表創(chuàng)建一個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小節(jié)中進行說明了，在此通過示例的方式再次強調一下。

?SPListItem的使用

在列表的實際操作中，最終要接觸到的還是作為數(shù)據內容部分的列表條目（List Item）。一般來說，在訪問列表的某個具體條目之前，都需要先獲得一個列表條目的集合，在SharePoint對象模型中，提供了很多種方法來獲取列表條目集合：

最直接地獲取列表條目的方法為，使用SPList.Items屬性，該屬性返回列表中的所有列表條目。在需要得到或者遍歷所有列表條目的時候，可以使用這種獲取列表條目的方法。

如果有目的地要獲得部分列表條目，可以使用SPList.GetItems方法，該方法有如下三種形式：

·????? GetItems(SPView view)

返回指定視圖中的列表條目，通過這種方法可以按照視圖中所指定的篩選、排序及其他的條件按照順序返回列表條目。在返回的條目中，也只有在視圖中定義過的可查看字段中的數(shù)據才可以訪問到。

·????? GetItems(SPQuery query)

顧名思義，SPQuery是SharePoint中負責查詢列表條目的一個類，通過定義一個查詢，可以方便地獲取想要得到的列表條目，SPQuery提供了兩種構造函數(shù)，一種是無參數(shù)的，另外一種可以帶有一個SPView類型的參數(shù)，即在指定的視圖上進行二次的查找。SPQuery最核心的一個屬性就是Query屬性，它是一個字符串的類型，它通過一種特殊定義過的xml形式，即CAML（Collaborative Application Markup Language）的形式描述一個查詢的條件，實際上，這個查詢字符串和SPView.Query屬性是相當?shù)摹Ｔ赟PQuery中，也可以通過ViewFields屬性來指定需要查看的字段（如果不加以指定，則查看所有字段）。在本節(jié)最后的示例中，將演示SPQuery的用法。

·????? GetItems(SPQuery query, string viewID)

指定SPQuery查詢和視圖，獲取列表條目。需要特別注意的是，雖然第二個參數(shù)為字符串類型，但是在使用的時候需要傳入的是列表視圖的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，如果不加以檢查就進行類型轉換的話，會引發(fā)一個異常（NullReferenceException）。在使用這種方法填寫或修改字段數(shù)據的時候，除了DateTime類型的數(shù)據之外，可以一律使用string類型寫入（但是除非特殊需要，不建議使用這種做法）。

審批也是SharePoint列表的一個重要的特色，它允許一個列表條目呈現(xiàn)“已審批、待定、被拒絕”這三種狀態(tài)，在默認視圖中，只顯示已審批的條目，在“我的提交”視圖和“審批視圖”中，可以看到其他的條目。

在SharePoint中，一個列表條目的審批信息并非是保存在某個字段中的，而是在對象模型中對應為SPModerationInformation類，并通過SPListItem.ModerationInfomation屬性來訪問，該類只有兩個屬性。

·????? Comments：審批意見。即列表管理員進行審批操作的時候所填寫的意見。

·????? Status：審批狀態(tài)。該屬性為SPModerationStatusType枚舉類型，對應三種狀態(tài)。

需要注意的是，ModerationInfomation這一屬性，只有當列表允許審批的時候（即列表SPList的EnableModeration屬性為true的時候）才可以取得，否則，該值始終為null。

在使用允許審批的列表的時候，獲取列表條目時會有一些不同。使用SPList.Items屬性只能獲得該列表中狀態(tài)為“已通過”的那些列表條目，要獲得其他條目，則必須通過“我的提交”或“審批視圖”這兩個視圖，使用SPList.GetItems方法來取得。開啟了審批的列表都會有這兩個視圖存在，這兩個視圖SPView對象的ModerationType屬性分別為“Contributor”和“Moderator”，表明屬于哪一個審批的視圖。

在SPListItem中，還有一些比較常用的屬性如下。

·????? Attachments：該列表條目的附件集合；

·????? File：如果該列表是文檔庫的話，得到該文件的對象（以上兩個屬性的使用請參考下一節(jié)“文件相關的對象模型”）；

·????? ID：在該列表中唯一標識該列表條目的整型的id；

·????? ModerationInfomation：該列表條目的審批信息；

·????? ParentList：該列表條目所在列表的對象；

·????? Xml：以Xml的格式返回該列表條目中的所有數(shù)據。

在列表條目的內容修改后，通過調用SPListItem.Update方法使修改生效。

添加一個列表條目的方法非常簡單，只需要調用SPListItemCollection.Add方法，該方法不需要參數(shù)，直接返回一個空的SPListItem對象，通過對該對象對各字段的內容進行修改，再調用Update方法，即可將該條目添加到該列表中。

刪除一個列表條目，有兩種方法：

·????? SPListItemCollection.DeleteById(int id)

通過列表條目的id來刪除該條目；

·????? SPListItemCollection.Delete(int index)

通過集合中的下標來刪除該條目。

在通過Delete方法刪除一個列表中的所有條目時，注意必須使用下面這種逆序的循環(huán)方法：

int total = items.Count;

for(int i=total-1; i>=0; i--)

??? items.Delete(i);

而不能正向的循環(huán)，更不能使用foreach循環(huán)來進行，在初學者中，這是一個比較常見的錯誤。請讀者自己思考這樣做的原因。

在SPListItemCollection類中，還有一個非常有用的方法：GetDataTable方法，即：

DataTable GetDataTable();

該方法可以返回由這些列表條目所組成的DataTable對象，以便將數(shù)據綁定到一些顯示控件（如DataGrid）上。但是注意當列表中沒有條目的時候，該函數(shù)返回的是null，而不是一個有效的DataTable對象。

【示例9-6】? 通過SPQuery獲得Score字段中大于等于60的列表條目，并且在這些條目的標題后加上“（合格）”字符串，然后再另一列表中，添加一個新條目，寫入合格人數(shù)。

// 首先獲取到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();
?

在該例中，為了簡化場景，沒有考慮到不同人、不同科目的分數(shù)問題。另外，這個例子只是為了說明和列表條目有關對象模型的使用方法，在實際的應用場景中，類似于上面這種問題，可以通過視圖的篩選、分組和匯總的功能在一張列表中直接完成，而且可以接受多人、多科目這種條件，分別統(tǒng)計每一科的合格人數(shù)，不需要進行任何編程，SharePoint中強大的視圖功能便可以體現(xiàn)在其中。請讀者自己思考視圖設置的方法。

文件相關的對象模型

SPAttachmentCollection的使用

在SharePoint的列表中，每個列表條目可以擁有0到多個附件文件（附件功能可以在列表常規(guī)設置中開啟或關閉），在對象模型中，訪問這些附件，則可以使用對象模型中的SPAttachmentCollection類來完成。

使用SPAttachmentCollection.Count屬性可以得到該列表條目中附件的個數(shù)，使用以下方法，則可以獲得每一個附件所在的地址。

·????? attachments[int index]：通過下標得到附件的文件名，這些附件實際上也是保存在SharePoint的文件系統(tǒng)中的，它們的url為：“List/Attachments/ItemID/FileName”，自然地，SPAttachmentCollection的對象模型中也提供了這樣一個屬性來訪問這一串地址：

·????? UrlPrefix：附件文件的前綴url地址（絕對url）。

附件的添加和刪除，和添加、刪除文件的方法是一樣的。

·????? Add(string filename, byte[] data)：第一個參數(shù)指定文件名，第二個參數(shù)指定附件內容的字節(jié)流。該文件已經存在的時候，也會返回一個異常。

·????? Delete(string filename)：根據文件名刪除該附件。

與添加、刪除文件不同的是，因為附件操作是包含在列表條目的修改之中，所以使用Add方法和Delete方法必須調用SPListItem.Update方法才能使修改生效。為了更直接的對附件進行操作，免除Update這一麻煩，SPAttachmentCollection類中提供了AddNow和DeleteNow兩個方法，它們的參數(shù)和使用與Add和Delete方法一致，只是調用完之后立刻生效，而不再需要進行Update。

在一個列表條目生成之前，SPListItem中的一切屬性都是不可用的，所以在對附件進行操作的時候尤其要進行注意，只能對已有的列表條目進行附件的操作。在添加一個新的列表條目的時候，也必須先執(zhí)行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來訪問，它們之間是有著內在聯(lián)系和明確分工的。

在使用SPList訪問的時候，它的“FileLeafRef”（內部名稱）字段保存的是文件的文件名，它可以通過定義視圖和查詢來查找我們所需要的某部分文件。在獲得SPListItem之后，也可以通過SPListItem.File來得到該列表條目所對應的文件（SPFile）的對象。但是由于是列表的形式，在獲得列表的時候是很按照文件夾的方式去獲取的，這個時候就需要結合另外的類來進行操作。

判斷一個列表是否是文檔庫，可以通過判斷SPList.BaseType屬性是否為SPBaseType.DocumentLibrary來完成。而SharePoint也專門提供了一個SPList的子類——SPDocumentLibrary來訪問文檔庫，在判斷一個列表為文檔庫之后，可以將該對象強制轉換為SPDocumentLibrary類型，在該類型中，提供了一個有用的函數(shù)：

GetItemsInFolder(SPView view, SPFolder folder)：指定一個列表的視圖，指定一個文件夾，返回該文件夾內的文件所對應的列表條目集合對象（SPListItemCollection）。

同時，我們也可以通過SPList.RootFolder屬性得到該文檔庫的根目錄的對象（注意之前應把SPListCollection.IncludeRootFolder設為true）。

在使用SPFolder和SPFile對象訪問文檔庫的時候，可以方便地獲取文檔庫中的層級結構，也可以得到文件的簽入/簽出狀態(tài)和版本控制信息，也可以方便地對文件進行復制、移動和刪除的操作。但是僅使用這種方法，卻無法獲得一個文檔的審批狀態(tài)。

在判斷文件夾是否為文檔庫時，可以通過SPFolder.ContainingDocumentLibrary屬性來完成，如果該文件夾在文檔庫中，那么該屬性會返回該文檔庫所在列表的Guid，可以借此獲得列表對象；在判斷一個文件是否在文檔庫中時，使用SPFile.InDocumentLibrary屬性即可。在確定一個文件包含在文檔庫之后，通過SPFile.Item屬性就可以得到對應的列表條目對象（SPListItem）。

將SPFolder/SPFile與SPDocumentLibrary結合起來使用，可以充分地發(fā)揮SharePoint文檔庫的強大功能。此外，SharePoint文檔庫還提供了文檔討論的功能，通過ie的一個ActiveX插件來對每一篇文檔進行討論，在對象模型中也提供了SPDocDiscussion類獲得該討論的部分信息，有興趣的用戶可以參考SDK中的相關章節(jié)。

在使用文檔庫的時候，尤其是在中文SharePoint系統(tǒng)中，特別需要注意的是，要明確“列表名稱”和“目錄名稱”這兩個不同的概念，這兩者可能是不同的，例如，一個文檔庫的名稱叫做“共享文檔”（列表的名稱），而它所在的url是“Shared Document”（目錄的名稱）。在使用SPList和SPFolder的時候，不要將這兩者混淆起來。

用戶/權限相關的對象模型

權限系統(tǒng)是SharePoint的另一大特點，在WSS中，權限可以劃分到列表級，而且SharePoint的權限是詳細到代碼級別的，稱為CAS（Code Access Security），也就是說每一個對象模型中的方法、屬性的訪問都會涉及到權限的問題。這也是為什么前兩章都要使用命令行（Console）方式的程序作為示例，而且直接在服務器端運行的原因（正如本章一開始所說的，默認讀者是以管理員的身份在服務器端進行操作）。在這樣一種權限的機制上，應該說整個SharePoint環(huán)境是比較安全的，除非直接讀取底層數(shù)據庫，否則用戶無法獲得其權限之外的數(shù)據；然而在另一個角度上，這種權限的機制也比較死板，只要數(shù)據在用戶的訪問或修改權限之內，那么使用普通的方法也是無法真正限制用戶對數(shù)據的訪問和修改的。

而在用戶系統(tǒng)上，SharePoint可以與AD相結合，通過AD來管理、組織用戶，可以說非常靈活和強大。

一般來說，用戶系統(tǒng)與權限系統(tǒng)是比較緊密地結合在一起的，SharePoint也不例外。因此，本節(jié)將兩者結合起來介紹。SharePoint對象模型中與用戶/權限相關的類主要有以下三個：SPPermission、SPRole、SPUser。

SPPermission的使用

在SharePoint中，由于權限是深入到代碼級別的，在每執(zhí)行一句代碼——尤其是對數(shù)據進行修改、對系統(tǒng)進行管理的代碼——的時候，都有可能會因為當前執(zhí)行者的權限不足而引發(fā)異常。雖然try-catch能夠在事后檢測并捕獲到大部分這種異常，但是，事前的檢測在代碼編寫的過程中有時也是必要的；而有的時候，也需要根據用戶的不同權限顯示出不同的信息。用戶權限的檢測就是通過SPPermission類來完成的。

在介紹SPPermission類之前，有必要先簡要介紹一下和權限相關的重要的枚舉類型SPRights。在這個枚舉類型中，列舉了所有WSS網站中所用到的權限，例如創(chuàng)建列表條目、修改列表條目、刪除列表條目等。在使用這些權限的時候，可以通過二進制掩模（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）操作，根據操作結果是否非零，來表明該成員在該對象上是否擁有該權限。

但是，正如本節(jié)一開始所提到的，之所以需要檢查權限的設置，是因為有一些用戶沒有權限來進行數(shù)據的操作或系統(tǒng)的設置。而上面所涉及到的那些方法和屬性所需要的對于權限的控制的權限，顯然是“普通用戶”所不具備的。好在SharePoint為我們提供了一個“普通用戶”也可以執(zhí)行的方法，用來檢測權限，它是SPPermissionCollection中的一個方法：

·????? DoesUserHavePermission(SPRights permissionMask)

檢測當前的用戶是否具有參數(shù)中所描述的權限，該方法返回一個bool型的值。在執(zhí)行某些語句之前，或者在需要針對不同權限用戶顯示不同內容的時候，通過調用這個方法，就可以明確地知道當前執(zhí)行這段代碼的用戶，是否具有某種權限，從而再進行相應的處理。

【示例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網站中使用該對象，則會直接引發(fā)錯誤，并且該錯誤無法被try-catch所捕獲，請?zhí)貏e加以小心。

獲取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)：添加一個角色，第一個參數(shù)指定角色的名稱，第二個參數(shù)指定角色的描述，第三個參數(shù)指定角色所擁有的權限；

·????? 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的文件系統(tǒng)同樣分為文件和文件夾這兩大組成部分，但是與普通的asp.net編程不同的是，SharePoint中的文件和文件夾絕大部分是保存在數(shù)據庫中的，只有一少部分（“_layouts”目錄下的文件）是直接保存在服務器的文件系統(tǒng)中（這些文件默認的路徑為：“C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\ LAYOUTS”）。在一般的程序編寫中，極少有需要去訪問“_layouts”目錄下的文件，而訪問其他的文件（包括網頁、文檔庫、圖片庫等）都需要通過SharePoint的對象模型來完成。本節(jié)主要介紹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)：參數(shù)為該文件夾所對應的路徑（注意不要包含最后的“/”字符）。

文件夾的添加和刪除同樣是通過SPFolderCollection來完成的。

·????? Add(string url)：添加一個文件夾，參數(shù)為待添加文件夾的url，該函數(shù)成功后直接返回一個SPFolder對象；

·????? Delete(string url)：刪除一個文件夾，參數(shù)為待刪除文件夾的url。

在SPFolder類中，有如下一些常用的屬性。

·????? ContainingDocumentLibrary：如果該文件夾是包含于一個文檔庫中的，那么該屬性返回標識該文檔庫列表的Guid。該屬性只讀；

·????? Exists：判斷該文件夾是否存在，在獲取一個文件夾之后（尤其是通過url的方式獲取一個文件夾之后），非常有必要先判斷該文件夾是否存在，因為在獲取文件夾的時候，文件夾不存在并不會引發(fā)異常，而在使用一個不存在的文件夾的時候，必然會引發(fā)異常。該屬性只讀；

·????? Files：該文件夾下的所有文件的集合；

·????? Name：該文件夾的名稱（只讀）；

·????? ParentFolder：它的上一級文件夾的對象（只讀）；

·????? ParentWeb：該文件夾所在網站的對象（只讀）；

·????? ServerRelativeUrl：該文件夾相對于服務器根地址的url（只讀）；

·????? SubFolders：該文件夾下所有子文件夾的集合；

·????? Url：該文件夾相對于其所在網站的url（只讀）。

SPFolder也提供了兩個非常有用的函數(shù)。

·CopyTo(string newUrl)：將該文件夾復制到參數(shù)所指定的url中；

·MoveTo(string newUrl)：將該文件夾移動到參數(shù)所指定的url中。

【示例9-7】? 一個簡單的函數(shù)，通過遞歸的方法遍歷某文件夾下的層級結構：

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)：參數(shù)為該文件所在的url。

此外，對于文檔庫列表中的列表條目來說，也可以通過SPListItem.File來得到該文件的對象（關于文檔庫，稍候會進一步加以說明）。

在刪除文件的時候，同樣使用SPFile.Delete方法。

·????? Delete(string url)：參數(shù)為待刪除文件的url。

添加一個文件與添加文件夾稍有不同，需要指定文件的內容，并且有如下三種不同的形式。

·????? Add(string url, byte[] content)：第一個參數(shù)指定待添加文件的url，第二個參數(shù)中以字節(jié)流的方式指定文件的內容。在指定文件url的時候，既可以使用完整的url（需要保證該目錄存在），也可以只使用文件名（即添加到當前文件夾中）。使用該方法添加文件的時候，如果該url已經存在一個文件，則該函數(shù)會引發(fā)一個異常；

·????? Add(string url, byte[] content, bool overwrite)：與上一種形式不同，這種形式通過第三個參數(shù)來指定當文件已存在時，是否進行覆蓋。當overwrite為true時，會對重名的文件進行覆蓋；否則，如果出現(xiàn)重名的情況，仍然會引發(fā)一個異常；

·????? Add(string url, byte[] content, SPUser createdBy, SPUser lastModifiedBy, DateTime timeCreated, DateTime timeLastModified)：添加文件的時候，根據后4個參數(shù)，指定文件的創(chuàng)建者、修改者、創(chuàng)建時間、修改時間。但是在使用這種形式的時候需要注意，該程序的執(zhí)行者必須為網站的管理員，而且該形式只有在WSS網站上有效（在SPS網站上，該方法會產生一個“Access Denied”錯誤）。

以上三種方法在創(chuàng)建成功之后均會直接返回一個SPFile類型的對象。

SPFile類中一些屬性及其含義如下，這些屬性一律為只讀的。

·????? Author：文件的創(chuàng)建者，是一個SPUser類的對象（關于該類，會在下一節(jié)中進行說明）；

·????? CheckedOutBy：文檔庫的文件允許進行簽入和簽出的操作，該屬性為簽出的用戶；

·????? CheckedOutDate：文件簽出的時間；

·????? CheckedInComment：文件簽入時的評論內容；

·????? CheckOutExpires：文件簽出的過期時間；

·????? CheckOutStatus：文件簽出的狀態(tài)，

·????? Exists：該文件是否存在；

·????? IconUrl：SharePoint為每種常用類型的文件都提供了圖標，該屬性中保存了該圖標的圖像文件的文件名（并非完整的url），這些圖片一般保存在“_layouts/images/”目錄下；

·????? InDocumentLibrary：表示該文件是否在文檔庫中；

·????? Item：如果該文件在文檔庫中，那么該屬性（SPListItem類）獲取該文件在該文檔庫列表中的列表條目對象；

·????? Length：文件的大小（以字節(jié)為單位）；

·????? ModifiedBy：該文件的最后修改者；

·????? Name：該文件的文件名；

·????? ParentFolder：該文件所在的目錄對象；

·????? Properties：一個Hashtable型的對象，包括該文件的一些常用屬性（例如創(chuàng)建者、創(chuàng)建時間、修改者、修改時間、文件大小、文件的版本等信息）；

·????? ServerRelativeUrl：該文件相對于服務器根地址的url；

·????? TimeCreated：文件創(chuàng)建的時間；

·????? TimeLastModified：文件最后修改的時間；

·????? Url：該文件相對于其所在網站的地址；

·????? Versions：SPFileVersionCollection類的對象，SharePoint的文檔庫可以支持文檔的版本管理和控制，該屬性中保存了該文件自創(chuàng)建以來的各個版本，同時保存了各版本的信息。（由于篇幅所限，不再一一列舉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)：以參數(shù)為內容，保存該文件。

【示例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命名空間中。

?

?

總結

以上是生活随笔為你收集整理的SharePoint 编程指南(转)的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。