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