SPSiteDataQuery使用说明
2010-08-03 11:24
369 查看
“ 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>
<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里该列将呈现空白。 .
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>" ;
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%20s)
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 子句
当我们使用 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>
<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里该列将呈现空白。 .
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>" ;
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%20s)
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 子句
相关文章推荐
- SPSiteDataQuery使用说明
- 深入浅出SharePoint—使用SPSiteDataQuery 查询多个List中的数据
- CAML之SPSiteDataQuery使用实例
- SPSiteDataQuery不完全使用手册
- 学习:SPSiteDataQuery不完全使用手册(转)
- 在sharepoint中 使用SPSiteDataQuery来进行跨列表查询
- SPSiteDataQuery不完全使用手册
- 在sharepoint中 使用SPSiteDataQuery来进行跨列表查询
- SPSiteDataQuery不完全使用手册
- ?使用SPSiteDataQuery和SPQuery查询不到数据
- SPSiteDataQuery不完全使用手册
- SPSiteDataQuery不完全使用手册(转)
- SPSiteDataQuery不完全使用手册
- 使用SPSiteDataQuery中的一些问题。
- SPSiteDataQuery不完全使用手册
- 使用SPSiteDataQuery和SPQuery查询不到数据
- MOSS 关于SPQuery 和SPSiteDataQuery的区别好用法!
- BeetlSql 单表操作工具(Query)使用说明
- SPSiteDataQuery详细说明
- Query对象和DOM对象使用说明