SPSiteDataQuery不完全使用手册

引用请注明出处，谢谢！ by. 阿米巴原虫

“SPSiteDataQuery”，可以用来进行跨站多列表混合查询，检索同一个网站集的或者指定网站中符合某项条件的所有列表项的集合。每个SPWeb对象都包含一个GetSiteData方法，通过传递一个SPSiteDataQuery实例作为方法的参数，返回一个DataTable类型的结果。

当我们使用SPSiteDataQuery查询数据时，主要涉及到下面几个参数，Lists，Query，Webs，和ViewFields。

…… (￣(エ)￣)ゞ恩…在进入正题之前，有一件事情需要事先提醒一下大家。如果不小心在Webs或者Lists参数的设置上出错了，例如XML格式上有错误或者某个参数的值错误之类的，SPSiteDataQuery是不会抛出异常的！！预先知道这个或许能帮你在调试的时候节省一点点时间，所以，一开始就确信你使用的参数是正确的～哟！￠( °°)ノ°

下面看一看查询的基本格式吧

SPSiteDataQuery q = new SPSiteDataQuery();

string sQuery = "<Where>" +

"<Gt>" +

"<FieldRef Name='ID' />" +

"<Value Type='Number'>0</Value>" +

"</Gt>" +

"</Where>";

q.Lists = "<Lists BaseType='1'/>";

q.Query = sQuery;

q.Webs = "<Webs Scope='SiteCollection' />";

q.ViewFields = "<FieldRef Name='Title' />" +

"<FieldRef Name='ID' />";

q.RowLimit = 10;

只需要对SPSiteDataQuery查询参数的值进行适当的修改，就可以得到你想要的结果。

鉴于SPSiteDataQuery过于复杂，下面在能力范围内做一个不完全介绍。希望能给学习SharePoint的大家带来一些帮助。

The Webs Property

此元素的属性只有一个：Scope。能赋予它的值有3个吧，尽管MSDN上说只有2个…..

① "<Webs Scope='SiteCollection' />"，包含当前网站所在的网站集(Site)下所有网站(Web)以及子网站(Web)

② "<Webs Scope='Recursive' />"，包含当前网站(Web)以及其下的所有子网站(Web)

③ 缺省，仅仅包含当前网站(Web)

不得不指出的是，正如前面所提到的，参数的设置出现错误时，SPSiteDataQuery是不会抛出异常的（比如说"<Webs Scope='recursive' />"(大小写异常)）。而且有趣的是，当赋予Scope的值异常时，SPSiteDataQuery只会检索当前网站(Web)（同缺省）。所以不知道缺省是MS设定的一个既定值呢，还是一个错误….

The Lists Property

此元素将定义你在文档库(Document Libraries)或者列表(Lists)里的搜索范围。
属性有4个：BaseType、ServerTemplate、Hidden、MaxListLimit
此外，子元素有两个：List、WithIndex。使用子元素可以将搜索条件限制在比较小的范围之内。
下面是关于属性的介绍。

① BaseType (例："<Lists BaseType='1'/>")
定义检索范围，上例为搜索所有的文档库，其他可以设定的值还有

Value	检索范围	说明
0	Generic list	除文档库(Document library)以外的所有列表(Lists)
1	Document library	仅仅查询文档库
3	Discussion forum	--
4	Vote or Survey	--
5	Issues list	--

（'2'是隐藏属性吗… (-"-;) ？？）
必须要注意的是这个属性的默认值为"<Lists BaseType='0'/>",也就是说缺省或者该属性设置出错时会查询文档库以外的所有列表。

② ServerTemplate (例： "<Lists ServerTemplate='850'/>")
搜索指定类型的列表（850为页面库列表类型）。这个属性的值出错时会以默认值进行查询。
关于ServerTemplate的值，参考附录1

③ Hidden (例："<Lists ServerTemplate='850' Hidden='TRUE'/>")
设定能否搜索隐藏列表。默认是搜索所有非隐藏的列表。

④ MaxListLimit (例："<Lists BaseType='1' MaxListsLimit='500'/>")
定义搜索的列表的总数，当超过这个数字时，SPSiteDataQuery会抛出一个SPException的例外。这个属性的默认值为1000。当把此属性设置为0时，那么搜索的列表数目将不会受到限制。
（关于这个属性，有人说默认值是2000，也有人说SP1的时候已经把这个问题修正过来了，具体怎么样有待考证….）

至于子元素个人不是很了解，也不常用。简单的介绍一下好了。

①    子元素List
（例：<Lists>
                    <List ID="7A9FDBE6-0841-430a-8D9A-53355801B5D5" />
                    <List ID="3D18F506-FCA1-451e-B645-2D720DC84FD8" />
        </Lists>）
仅仅搜索在ID属性内指定的列表。只有知道搜索列表的Guid时才可以使用哦～。

②    子元素WithIndex
（例：<Lists>
                    <WithIndex FieldId="D4819257-6B69-41F1-82C8-A91615BFF500" Type="Text" Value="Complete" />
        </Lists>）
为搜索指定一个索引列。Type属性的值必须是“Text”，Value为该列的值。
搜索将会被限制在拥有指定Field的列表内。（可以把一个Field理解为列表的一个列名）
WithIndex有3个属性FieldId, Value, Type。并且Type属性的值必须是“Text”。在上面的例子里，SPSiteDataQuery会搜索出那些指定列的值为“Complete”的列表内Item。
//不知道怎么用，以后补充吧，具体请参考MSND(链接见文末)

The ViewFields property

此元素定义返回哪些Fields（列表的列）也就是说定义了作为搜索结果的DataTable将包含哪些列（Column）。比如：
<ViewFields>

</ViewFields>

① Name (例：<FieldRef Name="Title" />)

这里的"Name"并不是那些我们列表中能看到的列名，而是该列的内部命。

    何为内部名？
        内部名就是MOSS内部使用的名字，外部是看不到的。(^.^)
    那么怎么知道这个列的内部名是什么呢？

        不知道。
        ……….所以自力更生做了个.exe。把源代码也公开一下，由于能力有限，应该会有几个bug。望各位不吝赐教。
        （输入列表的URL和结果文件的保存地址（输出为.csv文件，可用Excel(推荐)和写字板打开））
      /Files/Kenr/ViewFieldsInSPList.zip

需要注意的是，就像早期的SQL、能用在Where里的列必须是已经出现在select后面的，SPSiteDataQuery也一样，能在Query 属性（下一节介绍）里使用的列，必须是已经在ViewFields属性里引用过的。（SP1以后这个问题被修正了）

② Nullable (例：<FieldRef Name="Title" Nullable="TRUE" />)。

Nullable属性为可选项。我们知道在MOSS里并不是所有的列表都包含了相同的列。比如SPSiteDataQuery在查询一个列表时，发现ViewFields里指定的某个列在列表里并不存在，那么这个列表将被忽略。而当指定了" Nullable "为"TRUE"时则可以避免这种情况，不管有没有这个列，该类表都会被查询，只是在返回的DataTable里该列将呈现空白。

The Query Property

在这个属性里可以设置检索条件以及为结果排序。这个属性的功能就像一个SQL语句。讲起来要讲半天。还是让我们来看几个例子，有SQL基础的应该很快能够领会。（语法参照附录2）

① 日期查询

SPSiteDataQuery q = new SPSiteDataQuery();

string sLastWeek = SPUtility.CreateISO8601DateTimeFromSystemDateTime(DateTime.Today.AddDays(-1));

q.Query = "<Where>" +

"<Gt>" +

"<FieldRef Name='Created' />" +

"<Value Type='DateTime'>" + sLastWeek + "</Value>" +

"</Gt>" +

"</Where>";

② 为结果排序。按照Title的内容以（Z--A）的顺序输出

q.Query = "<OrderBy>" +

"<FieldRef Name='Title' Ascending='FALSE'>" +

"</OrderBy>";

③ 上面两个的合体

q.Query = "<Where>" +

"<Gt>" +

"<FieldRef Name='Created' />" +

"<Value Type='DateTime'>" + sLastWeek + "</Value>" +

"</Gt>" +

"</Where>"+

"<OrderBy>" +

"<FieldRef Name='Title' Ascending='FALSE'>" +

"</OrderBy>";

④　仅仅查找“文档”类型的文件(也就是说文件夹以外的东西.......吧)

q.Query = "<Where>" +

"<Gt>" +

"<FieldRef Name='Created' />" +

"<Value Type='DateTime'>" + sLastWeek + "</Value>" +

"</Gt>" +

"<Neq>" +

"<FieldRef Name=""FSObjType"" />" +

"<Value Type=""Lookup"">1</Value>" +

"</Neq>" +

"</Where>"+

"<OrderBy>" +

"<FieldRef Name='Title' Ascending='FALSE'>" +

"</OrderBy>";

The RowLimit Property

定义返回行数。
例：

SPSiteDataQuery q = new SPSiteDataQuery();

q.RowLimit = 10;

最后，别忘记设定RowLimit哦，否则，有那么一种可能，你会得不到任何结果。

附录1

如何确定ServerTemplate的值。

1. 在 WSS3.0 的 SDK 的 Lists 属性主题里，你可以找到可用列表的一系列类型。

2. 查找feature文件下相应List的模板文件，查看Type属性的值。
例如通过下面的文件，就可以查看Announcements list的ServerTemplate为104：
（C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\AnnouncementsList\ListTemplates\Announcements.xml）

3. 参照下表（至2009-5-1）
(http://www.sharepointdevwiki.com/display/public/Reserved+List+Template+(ServerTemplate)+ID's)

ServerTemplate	ListName
100	Generic list
101	Document library
102	Survey
103	Links list
104	Announcements list
105	Contacts list
106	Events list
107	Tasks list
108	Discussion board
109	Picture library
110	Data sources
111	Site template gallery
113	Web Part gallery
114	List template gallery
115	XML Form library
120	Custom grid for a list
200	Meeting Series list
201	Meeting Agenda list
202	Meeting Attendees list
204	Meeting Decisions list
207	Meeting Objectives list
210	Meeting text box
211	Meeting Things To Bring list
212	Meeting Workspace Pages list
300	Portal Sites list.
1100	Issue tracking
2002	Personal document library
2003	Private document library

附录2

元素	说明
And	并且
BeginsWith	以某字符串开始的
Contains	包含某字符串
Eq	等于
FieldRef	一个字段的引用 (在GroupBy 中使用)
Geq	大于等于
GroupBy	分组
Gt	大于
IsNotNull	非空
IsNull	空
Leq	小于等于
Lt	小于
Neq	不等于
Now	当前时间
Or	或
OrderBy	排序
Today	今天的日期
TodayIso	今天的日期（ISO格式）
Where	Where子句

参考：
MSDN）SPSiteDataQuery Properties (Microsoft.SharePoint)
http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.spsitedataquery_properties.aspx
XXXのBlog

http://blog.thekid.me.uk/archive/2007/02/27/spsitedataquery-samples-for-wss-v3.aspx

posted on 2009-06-02 09:57 阿米巴原虫阅读(2271) 评论(2) 编辑收藏举报