财神网名

書名： SharePoint 2013 應(yīng)用開發(fā)實戰(zhàn)
作者名：劉中正
本章字數(shù)： 2819字
更新時間： 2021-03-26 18:51:22

3.1 .NET客戶端對象模型

.NET客戶端對象模型是在SharePoint 2010引入的。在之前的版本，要想在客戶端上和SharePoint通信，只能通過Web Service。Web Service使用起來并不方便，.NET客戶端對象模型的推出，使程序員可以使用熟悉的對象模型來和SharePoint進行遠程交互。

3.1.1 環(huán)境準備

使用.NET客戶端模型的時候，Visual Studio可以在客戶端機器上。本節(jié)會講解如何在APS.NET網(wǎng)站里調(diào)用.NET客戶端模型。在開始編碼之前，需要在SharePoint和Visual Studio中做一些準備。

首先到SharePoint中，打開一個站點，創(chuàng)建一個通知列表，并且創(chuàng)建一些列表項，如圖3-1所示。

圖3-1 通知列表

然后準備Visual Studio環(huán)境。

.NET客戶端對象模型的API文件存儲在SharePoint服務(wù)器的C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI目錄下，找到Microsoft.SharePoint.Client.Runtime.dll和Microsoft.SharePoint.Client.dll，拷貝到客戶端機器上。

這里會以一個ASP.NET為宿主運行代碼，讀者也可以選擇Windows窗體程序或者控制臺程序。

打開Visual Studio，新建項目，選擇“ASP.NET Web應(yīng)用程序”，如圖3-2所示。

圖3-2 新建項目

在圖3-3中選擇空項目模板。

圖3-3 選擇空項目模板

這樣一個空的項目就創(chuàng)建出來了。下一步是添加對SharePoint DLL的引用。在解決方案窗體里，右擊“引用”，選擇添加引用，在彈出的窗體里，選擇“瀏覽”，并找到拷貝過來的兩個SharePoint DLL文件，如圖3-4所示。

圖3-4 添加引用

引入之后，選中引入的文件，在屬性窗體里，把“復(fù)制本地”改為True。這個選項能夠確保在發(fā)布站點的時候，引入的dll文件能一起發(fā)布，如圖3-5所示。

圖3-5 復(fù)制本地屬性

然后選中項目，右擊，選擇“添加”，在下一級菜單里選擇Web窗體，命名為SharePointWeb。新建好之后，選中這個Web窗體，右擊，選擇設(shè)置為起始頁，方便以后調(diào)試。

打開SharePointWeb.aspx.cs，加上對SharePoint客戶端命名空間的引用：

    using Microsoft.SharePoint.Client;

這樣開發(fā)環(huán)境就準備完畢了。

3.1.2 ClientContext

在.NET客戶端對象模型中，ClientContext是一切對象的入口，因此首先要初始化這個對象。ClientContext的初始化方法如下：

    ClientContext context = new ClientContext("http://mysiteurl");

傳給了ClientContext站點的URL還不夠，就像在瀏覽器里登錄SharePoint一樣，還需要提供用戶名密碼。

    context.Credentials = new NetworkCredential("username", "password", "domain");

然后就可以獲取Site和Web對象了，從而進一步獲取到List、ListItem。

.NET客戶端對象模型和服務(wù)器端對象模型的結(jié)構(gòu)是一樣的，但是在命名上去掉了SP前綴，表3-1是對照表：

表3-1 .NET客戶端對象模型和服務(wù)器端對象模型的比較

3.1.3 Site和Web對象

首先在SharePointWeb.apsx上面添加幾個Label控件，用來顯示站點信息：

    <body>
       <form id="form1" runat="server">
       <div>
       網(wǎng)站標題：<asp:Label runat="server" id="webTitle" ></asp:Label><br/>
   網(wǎng)站說明：<asp:Label runat="server" id="webDescription"></asp:Label><br/>
   </div>
      </form>
    </body>

1．獲取Site和Web對象

獲取Site的方法如下：

    Site site = context.Site;

在客戶端對象模型中，對網(wǎng)站集的操作是很弱的，基本上沒有什么功能，這也是出于安全考慮。

獲取網(wǎng)站集的頂層網(wǎng)站：

    Web web = site.RootWeb;

和服務(wù)器端對象模型不同，獲取Web對象不一定要先構(gòu)造Site對象，可以通過ClientContext對象直接獲取。

    Web web = context.Web;

下面的代碼演示如何獲取Web的標題和說明，并顯示在頁面上。

在SharePointWeb.aspx.cs的Page_Load方法里面，添加如下代碼：

    protected void Page_Load(object sender, EventArgs e)
    {
              ClientContext context = new ClientContext("http://mysiteurl");
              context.Credentials = new NetworkCredential("username", "pwd",
"domain");
              Web web = context.Web;
              context.Load(web);
              context.ExecuteQuery(); //只有執(zhí)行ExecuteQuery才會和SharePoint通信
              webTitle.Text = web.Title;
              webDescription.Text = web.Description;
    }

按F5鍵，運行結(jié)果如圖3-6所示：

圖3-6 查詢站點信息的運行結(jié)果

使用.NET客戶端對象模型，有以下幾點需要注意：

● 通過ClientContext獲取到的Site/Web對象，是不包含任何實際屬性的，需要先調(diào)用Load，再調(diào)用ExecuteQuery方法，才會去和SharePoint通信，獲取信息。

● Site和Web對象，不需要使用Using或者Dispose手動釋放。

● 為了減少給服務(wù)器造成的壓力，以及不必要的網(wǎng)絡(luò)數(shù)據(jù)傳輸，應(yīng)該盡量減少調(diào)用ExecuteQuery的次數(shù)，并且每次Load的時候只Load需要的信息。

在上面的例子里，Load了整個Web對象，但是實際上只使用了Title和Description兩個屬性，因此可以按照下面的代碼優(yōu)化，將context.Load(web)替換成：

    context.Load(web, w => w.Title, w => w.Description);

上面的代碼用到了Lambda表達式，因此要添加System.Linq的命名空間的引用。

2．更新站點屬性

下面的代碼演示如何更新Web對象的屬性：

    web.Title = "研發(fā)部門站點";
    web.Description = "這個是研發(fā)部門站點，可以在這里分享文檔和發(fā)起討論和查看通知。";
    web.Update();
    context.ExecuteQuery();

這里需要注意的是，在更新SharePoint對象（調(diào)用Update方法）時，必須要調(diào)用context.ExecuteQuery();方法才會起作用。

再次把標題和說明顯示在頁面上，如圖3-7所示：

圖3-7 更新站點信息后的運行結(jié)果

3．建新站點

創(chuàng)建新的站點需要WebCreationInformation對象。這個也是和服務(wù)器端對象模型不一樣的地方。下面的代碼添加一個新的站點，并顯示在頁面上：

    WebCreationInformation creation = new WebCreationInformation();
    creation.Url = "serverteam";
    creation.Title = "Server Team的站點";
    creation.Description = "這個是研發(fā)部門下屬Server小組的站點";
    Web newWeb = web.Webs.Add(creation);
    context.Load(newWeb, w => w.Title, w => w.Description);
    context.ExecuteQuery();
    webTitle.Text = newWeb.Title;
    webDescription.Text = newWeb.Description;

顯示結(jié)果如圖3-8所示：

圖3-8 添加站點的運行結(jié)果

3.1.4 List對象

仿照前面的步驟，添加一個名為SharePointList.aspx的窗體，并在SharePointList.aspx.cs中的命名空間部分添加對Microsoft.SharePoint.Client和System.Linq的引用。在SharePointList.aspx中添加兩個textbox：

    <body>
       <form id="form1" runat="server">
       <div>
       列表集合：<br/>
       <asp:TextBox runat="server" id="allLists"
          TextMode="MultiLine" Height="300" Width="220" >
       </asp:TextBox><br/>
        聯(lián)系人列表欄：<br/>
       <asp:TextBox runat="server" id="contactListFields"
          TextMode="MultiLine" Height="300" Width="220" >
       </asp:TextBox><br/>
       </div>
       </form>
    </body>

1．獲取列表信息

要獲取到列表對象，同樣需要先調(diào)用Load方法，在Load方法里面，指定需要獲取的屬性，比如標題，列表項個數(shù)，創(chuàng)建時間等，然后再調(diào)用context.ExecuteQuery();。

下面的代碼演示如何通過Web對象獲取站點里面的List的屬性并顯示在頁面上。

    Web web = context.Web;
    context.Load(web.Lists,
    lists => lists.Include(list => list.Title,
                        list => list.ItemCount,
                        list => list.Created));
    context.ExecuteQuery();
    foreach (List list in web.Lists)
    {
          allLists.Text +=list.Title + ":" + list.ItemCount+"\r\n";
    }

運行結(jié)果如圖3-9所示：

圖3-9 列表標題和列表項個數(shù)

2．新建列表

創(chuàng)建新的列表需要借助于ListCreationInformation對象。

下面的代碼演示如何新建一個聯(lián)系人列表：

    ListCreationInformation creationInfo = new ListCreationInformation();
           creationInfo.Title = "聯(lián)系人";
           creationInfo.TemplateType = (int)ListTemplateType.Contacts;
           List newlist = web.Lists.Add(creationInfo);
           newlist.Description = "查看本部門的聯(lián)系人信息";
           newlist.Update();
    context.ExecuteQuery();

同樣，在調(diào)用完newlist.Update()之后，要調(diào)用context.ExecuteQuery()才能把新建請求提交給SharePoint。

在SharePoint里面，可以看到新建了一個聯(lián)系人的列表，如圖3-10所示。

圖3-10 添加列表的運行結(jié)果

3．獲取列表欄的信息

下面的代碼演示如何獲取列表里面所有的欄的名字和類型：

    List contactlist = context.Web.Lists.GetByTitle("聯(lián)系人");
    context.Load(contactlist.Fields);
    context.ExecuteQuery();
    foreach (Field field in contactlist.Fields)
    {
         contactListFields.Text += field.Title + ":" + field.TypeDisplayName +
"\r\n";
    }

結(jié)果如圖3-11所示。

圖3-11 列表的欄和類型

4．添加新欄

下面的代碼演示如何給列表添加一個數(shù)字類型的欄，并且值的范圍為15~100：

    List contactlist = web.Lists.GetByTitle("聯(lián)系人");
    Field field = contactlist.Fields.AddFieldAsXml("<Field
    DisplayName='年齡' Type='Number' />",
                                                 true,
                                                 AddFieldOptions.DefaultValue);
              FieldNumber fldNumber = context.CastTo<FieldNumber>(field);
              fldNumber.MaximumValue = 100;
              fldNumber.MinimumValue = 15;
              fldNumber.Update();
              context.ExecuteQuery();

這里用到了CastTo方法，將Field基類的對象，轉(zhuǎn)換成具體的列表類型對象。

5．刪除列表

代碼如下：

    List list = web.Lists.GetByTitle("MyListTitle");
    list.DeleteObject();
    context.ExecuteQuery();

3.1.5 Listitem對象

對列表項的常見操作也是增刪改查。

1．查詢列表項

查詢列表項，要借助于CamlQuery對象來實現(xiàn)，下面的例子演示如何查詢前100個列表項：

    List contactlist = web.Lists.GetByTitle("聯(lián)系人");
    CamlQuery query = CamlQuery.CreateAllItemsQuery(100，new
string[]{"Title","Email"});
    Microsoft.SharePoint.Client.ListItemCollection items = list.GetItems(query);
    context.Load(items);
    context.ExecuteQuery();
    foreach (Microsoft.SharePoint.Client.ListItem listItem in items)
    {
                 allItems.Text += listItem["Title"] + "|" + listItem["Email"] +
"\r\n" ;
    }

此段代碼把前一百個聯(lián)系人的姓和郵箱顯示在頁面上，結(jié)果如圖3-12所示：

圖3-12 顯示列表項

在查詢列表項的時候，有以下幾點需要注意：

● 在CreateAllItemsQuery方法里定義返回條目數(shù)和欄（也可以使用CAML語言），以減少數(shù)據(jù)傳輸。

● 上面的代碼包含了列表項和文件夾（Team A是一個文件夾），以及所有子文件夾里面的列表項的。如果只想查詢特定的文件夾，需要給query.FolderServerRelativeUrl賦值。

● 可以使用CAML語言來定義查詢的篩選條件，排序等。

2．新建列表項

新建一個列表項需要借助ListItemCreationInformation類。還是以上面的聯(lián)系人列表為例：

    ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
    Microsoft.SharePoint.Client.ListItem newItem = list.AddItem(itemCreateInfo);
    newItem'"Title"' = "張";
    newItem'"FirstName"' = "三";
    newItem'"Email"' = "zhang.san@contoso.com";
    newItem.Update();
    context.ExecuteQuery();

這里要注意一點，欄的名字一定要用內(nèi)部名稱，而不是在頁面上看到的名稱。比如“姓氏”的內(nèi)部名稱是“Title”，而“名字”的內(nèi)部名稱是“FirstName”。

如何查看一個欄的內(nèi)部名字呢？進入到列表設(shè)置頁面，在欄的部分，選中一個欄，右鍵查看屬性，末尾的屬性就是內(nèi)部名稱，如圖3-13所示：

圖3-13 查看欄內(nèi)部名稱

3．更新列表項

代碼如下：

    listItem'"Company"' = "Contoso";
    listItem'"JobTitle"' = "Manager";
    listItem.Update();
    context.ExecuteQuery();

4．刪除列表項

代碼如下：

    listItem.DeleteObject();
    context.ExecuteQuery();

5．新建文件夾

新建文件夾的過程和新建列表項的類似，但是要指定UnderlyingObjectType為Folder:

    ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
    itemCreateInfo.UnderlyingObjectType = FileSystemObjectType.Folder;
    Microsoft.SharePoint.Client.ListItem newItem = list.AddItem(itemCreateInfo);
    newItem["Title"] = "Team A";
    newItem.Update();
    context.ExecuteQuery();

3.1.6 使用.NET客戶端對象模型的最佳實踐

● 在做任何操作之后，一定要調(diào)用context.ExecuteQuery()，才能把修改提交到SharePoint端。

● 不能使用沒有獲取到的屬性。

● 盡量減少和SharePoint交互的次數(shù)。

● 在請求SharePoint數(shù)據(jù)之前，限制查詢的范圍，比如只請求需要的屬性或者列表項。

官术网_书友最值得收藏!

SharePoint 2013 應(yīng)用開發(fā)實戰(zhàn)

3.1 .NET客戶端對象模型

3.1.1 環(huán)境準備

3.1.2 ClientContext

3.1.3 Site和Web對象

1．獲取Site和Web對象

2．更新站點屬性

3．建新站點

3.1.4 List對象

1．獲取列表信息

2．新建列表

3．獲取列表欄的信息

4．添加新欄

5．刪除列表

3.1.5 Listitem對象

1．查詢列表項

2．新建列表項

3．更新列表項

4．刪除列表項

5．新建文件夾

3.1.6 使用.NET客戶端對象模型的最佳實踐