“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的大家带来一些帮助。
此元素的属性只有一个:Scope。能赋予它的值有3个吧,尽管MSDN上说只有2个…..
① "<Webs Scope='SiteCollection' />",包含当前网站所在的网站集(Site)下所有网站(Web)以及子网站(Web)
② "<Webs Scope='Recursive' />",包含当前网站(Web)以及其下的所有子网站(Web)
③ 缺省,仅仅包含当前网站(Web)
不得不指出的是,正如前面所提到的,参数的设置出现错误时,SPSiteDataQuery是不会抛出异常的(比如说"<Webs Scope='recursive' />"(大小写异常))。而且有趣的是,当赋予Scope的值异常时,SPSiteDataQuery只会检索当前网站(Web)(同缺省)。所以不知道缺省是MS设定的一个既定值呢,还是一个错误….
此元素将定义你在文档库(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(链接见文末)
此元素定义返回哪些Fields(列表的列)也就是说定义了作为搜索结果的DataTable将包含哪些列(Column)。比如:
<ViewFields>
<FieldRef Name="Title" Nullable="TRUE" />
</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里该列将呈现空白。
在这个属性里可以设置检索条件以及为结果排序。这个属性的功能就像一个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>";
定义返回行数。
例:
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のBlog
XXX
http://blog.thekid.me.uk/archive/2007/02/27/spsitedataquery-samples-for-wss-v3.aspx