本节将会介绍SharePoint中最为常用的一些对象模型,以及如何使用这些对象模型来访问和操作网站中的数据。几乎所有的SharePoint服务器端开发都会涉及到这些内容,因此应着重掌握本节中所介绍的基本对象模型的使用方法。由于篇幅所限,在介绍每种对象的时候只能阐述一些最为常用和重要的属性及方法,以及一些容易混淆或出错的内容。更加完整的属性、方法的定义、介绍和代码示例片段,请参考SDK中类库索引中相关章节。
网站中一些常用对象的结构大概如下图所示(从SharePoint 2003起,这部分内容在结构上未曾发生根本性的变动):
(一)网站集(SPSite)和网站(SPWeb)
网站是SharePoint基本对象模型之一,由于SharePoint的数据基本上全部都容纳在网站中,因此绝大多数的SharePoint程序都要先从获取网站开始。
SPSite 对应的是站点集 (sitecollection),站点集只能总管理中心创建, 从某种程度上来说,也可以理解为根站点;
SPWeb对应的是站点(Site), 站点是从当前站点创建的,站点下面还可以包括站点;
如果你是学习开发,那么这段代码是你常用的:
using(SPSite oSiteCollection = new SPSite("http://Server_Name"))
{
using(SPWeb oWebsite = oSiteCollection.OpenWeb("Website_URL"))
{
SPList list=oWebsite.Lists["mylist"];
...
}
}
更多的内容请参考 SDK:http://msdn.microsoft.com/zh-cn/library/microsoft.sharepoint.spsite.aspx
1、网站集和网站的关系
网站集(Site Collection)顾名思义,是网站的集合,每个网站集中必须有一个顶级网站(或称为首要网站),而每个网站可以有0至多个子网站,从而构成一棵网站结构树,在这棵树上的所有网站构成了整个网站集。在SharePoint中,网站集几乎只是一个被架空的概念,其作用只是将一个相对完整的整体性应用集中组织起来,控制应用中的母版页、Web部件、网站集功能等配置。网站集这个本身不储存任何数据,诸如Web部件、母版页、列表模板、网站模板、网站集解决方案等均存储在网站集的顶级网站中。在SharePoint对象模型中,网站集使用SPSite对象表示,SPSiteCollection(SPSiteCollection包含在Microsoft.SharePoint.Administration这个命名空间中,而本节涉及到的其他类均包含在Microsoft.SharePoint命名空间中)表示网站集的集合。
网站是SharePoint中最经常使用到的对象模型之一,网站中包含的列表、文档库、文件等内容都是在SharePoint开发过程中最经常涉及到的对象。网站使用SPWeb对象表示,SPWebCollection表示网站的集合。请注意在对象模型中“网站的集合”(SPWebCollection)与“网站集”(SPSite)这几个概念的关系和区别。
2、网站集的获取
在控制台程序等运行在服务器上的客户端程序中,由于没有IIS的上下文(Context)环境,必须要通过绝对路径获取网站集对象,再获得其中的网站对象。
网站集的获取使用SPSite的构造函数进行,一般来说,经常使用的一个重载如下(假设我们的网站地址为:http://sp2010/book,一个子网站):
1: SPSite site = new SPSite("http://sp2010/book");
在该构造函数中,必须要使用完整的绝对Url路径,但该Url不一定要限制为网站的根路径,可以为该网站下的任何一个路径(甚至是不存在的文件地址),例如使用Url:“http://sp2010/book/chapters/part1/ch02.docx”作为参数,同样可以返回同一个网站集,即使后面的文档库、文件夹或文件都不存在也没有关系(但并不建议这样使用)。
3、网站的获取
当获取到一个网站集的SPSite对象之后,有三种方式获取到其中的网站:(1)RootWeb属性;(2)AllWebs属性;(3)OpenWeb方法。
(1)RootWeb属性返回网站集中的根网站,即顶级网站。
(2)AllWebs属性是SPWebCollection类型,返回网站集中的所有网站。当要获取到其中某一个网站的时候,可以使用3种索引器:
- AllWebs[idx]:int型索引器,根据下标顺序获取,几乎很少使用这种方式;
- AllWebs[id]:Guid型索引器,根据网站Guid获取;
- AllWebs[url]:string型索引器,根据网站的相对路径(相对根网站的路径)获取。
(3)OpenWeb方法按照参数类型不同的重载,也有如下的使用方式:
- OpenWeb():无参数。返回构造SPSite时所使用的Url所对应的网站,这是一种比较常用的方法,如果使用的是顶级网站的Url构造SPSite,则该方法返回的就是顶级网站;如果使用的是子网站的Url构造SPSite,则该方法返回的就是相应的子网站。
- OpenWeb(Guid id):使用网站的Guid返回网站。
- OpenWeb(string url):使用网站的相对路径(相对服务器路径或相对顶级网站的路径)返回网站。
例如,可以使用如下的方法来获取网站:
1: SPSite site1 = new SPSite("http://sp2010/book");
2: SPWeb web1 = site1.OpenWeb(),
3: theSameAsWeb1 = site1.AllWebs["book"];
4:
5: SPSite site2 = new SPSite("http://sp2010");
6: SPWeb web2 = site2.OpenWeb(),
7: theSameAsWeb2 = site1.RootWeb,
8: anotherWeb1 = site2.OpenWeb("book");
(这部分代码并不完整,详见后面的说明)
4、特殊的网站和网站集获取方法
之前所介绍的一些获取方法可以随时使用,但是当程序运行在IIS进程中时(比如Web页面、Web部件、一些类型的事件处理程序、工作流等),由于有上下文(Context)的存在,可以很方便的获取到程序所在的当前网站集和当前网站:
1: SPSite currentSite = SPContext.Current.Site;
2: SPWeb currentWeb = SPContext.Current.Web;
5、网站集和网站的常用属性
SPSite的常用属性:
名称 | 类型 | 说明 |
AllWebs | SPWebCollection | 网站集中的所有网站 |
RootWeb | SPWeb | 网站集的根网站(顶级网站) |
Url | string | 网站集的绝对路径(实际上就是顶级网站的绝对路径) |
SPWeb的常用属性:
名称 | 类型 | 说明 |
RootFolder | SPFolder | 网站的根目录 |
Site | SPSite | 网站所在的网站 |
Title | string | 网站标题 |
Name | string | 相对父网站的Url(不是网站名称,不要被这个属性的名字迷惑) |
Url | string | 网站的绝对路径 |
Webs | SPWebCollection | 网站的子网站(不包含孙网站) |
由于几乎所有常用的对象模型都是依附于网站的,这些对象的访问也基本都以SPWeb作为起点,因此涉及到SPWeb中包含的其他对象操作访问的属性和方法,将在后文具体介绍到相应对象的时候再做详细说明。
6、网站集和网站的释放
由于SPSite和SPWeb的一些内部属性中,使用到了非托管资源,而这些非托管资源不受.NET的垃圾回收机制控制,因此在使用完SPSite和SPWeb对象之后,一个良好的习惯是手动将其释放掉,释放的方法是调用其Dispose方法。例如:
1: SPSite site = new SPSite("http://sp2010/book");
2: SPWeb web = site.OpenWeb();
3: // use the web and site
4: web.Dispose();
5: site.Dispose();
当然,更方便的一种方式是使用C#中的using关键字,从而在使用完之后自动调用其Dispose方法。因此,一般而言,常用的写法是下面这种形式:
1: using(SPSite site = new SPSite("http://sp2010/book"))
2: {
3: using(SPWeb web = site.OpenWeb())
4: {
5: // use the web and site
6: }
7: }
在SharePoint应用中,几乎所有返回的SPSite和SPWeb对象都需要上述释放过程。但是使用SPContext.Current方式获取的SPSite和SPWeb不可以释放!否则会触发一些意外情况,SharePoint运行时会自动控制这两个对象的生命周期。