4.3 文档库
4.3.1 文档库概述
文档库是与其他网站用户共享的 Windows SharePoint Services 3.0 上的文件集合。大多数 Windows SharePoint Services 3.0 文档管理功能都是通过文档库来传送的。作为文档管理规划的一部分，应确定最能满足组织需求的文档库。
Windows SharePoint Services 3.0 包括以下类型的文档库：
l 文档库——使用文档库可实现文档存储、文档协作和内容轻松共享；
l 图片库——使用图片库可共享、管理和重用数字图片。
在 Windows SharePoint Services 3.0 中，文档库可以包含多个类型的文档。可以将一个或多个内容类型与文档库关联，当将多个内容类型与一个库关联时，文档库的“新建”命令可让用户创建与此文档库关联的任何内容类型的新文档，并且文档库视图中将显示此库可包含的所有内容类型的元数据。
此外，文档库功能还包括：
（1）模板
可以设计模板并将其与文档库关联以标准化库中创建的文档。
（2）工作流程
通过使用自定义工作流程（请参阅规划工作流程 （Windows SharePoint Services）），可在文档上运行业务流程。例如，工作流程可以发送文档以供审阅。
（3）签入和签出
可以要求用户在编辑文档之前在文档库中签入和签出文档。
（4）版本控制
可以从3个版本控制选项中进行选择。
文档库是MOSS 2007最被广泛使用的功能之一，在本章下面的小节中，将详细地介绍关于文档库的基础功能开发。
4.3.2 建立文档库
在SharePoint中，文档库实际上是一种特殊类型的列表，它为开发人员提供了强大的功能和灵活的可扩展性。
由于文档库本质上是一种列表，因此Object Model中对列表和列表记录的操作功能同样适用于文档库。也就是说，可以把文档库当成SPList类的一个对象，而把文档库中的文档当成SPListItem的一个对象。当然也可以使用Object Model中专门针对文档库提供的类，比如，可以通过SPDocumentLibrary类去访问文档库，通过SPFile类去访问文档库中的文档。
在Object Model中专门针对文档库提供的类包括：
l SPFileCollection
l SPFile
l SPDocumentLibrary
l SPListItem
l SPFolderCollection
l SPFolder
其中，SPFile和SPFolder类是在进行文档库开发时最常用的两个类，下面就来详细地介绍一下这两个类的主要属性。
SPFile类的主要属性如表4-9所示。
表4-9 SPFile类的主要属性
|
属 性 |
说 明 |
|
Author |
该属性表示文档的创建者 |
|
CheckedOutBy |
该属性表示文档当前被哪个用户签出 |
|
CheckedOutDate |
该属性表示文档最后一次被签出的时间，如果该文档没有被签出，那么访问该属性会抛出异常 |
|
Comment |
该属性表示文档签入时，用户写的注释 |
|
CheckOutStatus |
该属性可以获取文档的签出状态（LongTerm、LongTermOffline、None、ShortTerm） |
|
Exists |
该属性表示文档是否存在 |
|
InDocumentLibrary |
该属性是一个布尔值，表示文档是否在文档库中 |
|
Item |
该属性表示文档库中的一个记录（即文档库中的一个文档） |
|
Length |
该属性表示文档的大小（单位是字节） |
|
Level |
该属性表示文档的发布级别（Checkout=255，Draft=2，Published=1） |
|
Name |
该属性表示文件名 |
|
ParentFolder |
该属性表示当前文件夹的父文件夹 |
|
Properties |
该属性可以获取文档的元数据信息 |
|
ServerRelativeUrl |
该属性可以获取文档的服务器端相对URL |
|
TimeCreated |
该属性表示文档的创建时间，该时间不同于文档上传到文档库的时间 |
|
Title |
该属性可以获取文档的标题 |
|
UniqueId |
该属性可以获取文档的GUID |
|
Url |
该属性可以获取文档的网站相对URL |
|
Versions |
该属性可以获取文档的所有历史版本信息 |
SPFolder类的主要属性如表4-10所示。
表4-10 SPFolder类的主要属性
|
属 性 |
说 明 |
|
ContainingDocumentLibrary |
该属性可以获取包含文件夹的文档库 |
|
Exists |
该属性表示文件夹是否存在 |
|
Files |
该属性可以返回文件夹包含的所有文件 |
|
Item |
该属性表示文档库中的一个文件夹记录 |
|
ParentFolder |
该属性返回当前文件夹的父文件夹，如果当前文件夹就在根目录下，那么就返回当前文件夹自身 |
|
ParentListId |
该属性返回文件夹所属列表的ID（即文档库的ID） |
|
ParentWeb |
该属性返回文件夹所属的网站 |
|
Properties |
该属性可以获取文件夹的元数据信息 |
|
ServerRelativeUrl |
该属性表示文件夹的服务器端相对URL |
|
SubFolders |
该属性可以获取当前文件夹的所有子文件夹 |
续表
|
属 性 |
说 明 |
|
UniqueId |
该属性可以获取文件夹的GUID |
|
ParentFolder |
该属性表示当前文件夹的父文件夹 |
|
Properties |
该属性可以获取文档的元数据信息 |
|
ServerRelativeUrl |
该属性可以获取文档的服务器端相对URL |
|
Url |
该属性可以获取文件夹的网站相对URL |
在SharePoint中文档库的创建是非常简单的，因为文档库是一种特殊的列表，因此文档库的创建和列表的创建是一样的，如下面的代码所示。
SPSite site = new SPSite("http://localhost/sites/Test");
SPWeb web = site.AllWebs[0];
Guid newListID = web.Lists.Add(listTitle,
listDescription, SPListTemplateType.DocumentLibrary);
// 设置文档库的其他属性.
SPList newList = web.Lists[newListID];
newList.OnQuickLaunch = true;
newList.EnableVersioning = true;
newList.Update();
从上面的代码可以看出，我们就是通过创建一个新的列表来创建文档库的，这个列表使用了文档库模板（SPListTemplateType.DocumentLibrary）。创建完文档库后，还可以设置文档库的一些其他属性，如OnQuickLaunch、EnableVersioning等。
实例4-7：使用Object Model实现将文档上传到文档库
建立了文档库后，最常见的应用就是向文档库中上传文档，下面通过一个例子来详细地介绍文档上传功能，让您更深入地理解文档库的开发。
该例子是一个ASP.NET应用程序，该程序的功能是将本地的文档上传到指定的SharePoint文档库中。该应用程序的基本流程是：
让用户输入SharePoint网站的地址和文档库的名称，确定把文档上传到哪个文档库中。
确认用户是否提供了要上传的文档信息，如果没有，则提示用户提供要上传的文档信息。
如果用户成功提供了要上传的文档信息，那么把文档内容读入到字节数组中。
将文档上传到指定的文档库。
该ASP.NET应用程序的后台代码如下：
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using Microsoft.SharePoint;
using System.IO;
public partial class _Default : System.Web.UI.Page
{
protected void cmdUploadFile_Click(object sender, EventArgs e)
{
try
{
lblErrorMsg.Visible = false;
SPSite site = new SPSite(txtSiteUrl.Text);
SPWeb web = site.AllWebs[txtWebName.Text];
SPList dl = web.Lists[txtDocLibName.Text];
SPFile file;
web.AllowUnsafeUpdates = true;
web.Lists.IncludeRootFolder = true;
if (FileUpload1.PostedFile.FileName != "")
{
// 将文档内容读入到字节数组中
Stream fStream;
Byte[] contents = new Byte[FileUpload1.PostedFile.InputStream.Length];
fStream = FileUpload1.PostedFile.InputStream;
fStream.Read(contents, 0, (int)fStream.Length);
fStream.Close();
// 上传文档
file = web.Files.Add(web.Url.ToString() + "/" + dl.Title.ToString() + "/" +
FileUpload1.FileName, contents);
file.Update();
}
else
{
lblErrorMsg.Text = "Please select a file to upload";
lblErrorMsg.Visible = true;
}
}
catch (Exception ex)
{
lblErrorMsg.Text = ex.Message;
lblErrorMsg.Visible = true;
}
}
}
从上面的代码中可以看到，当把要上传的文档内容转换为字节数组后，只需简单地调用SPFile对象的Add()方法即可完成文档的上传。另外，所有操作完成后，必须调用Update()方法，使所有变更操作生效。该程序还有一个问题要注意，那就是ASP.NET应用程序默认能传输的文件大小是4MB，如果要上传的文档超过了4MB，那么必须在ASP.NET应用程序的Web.config中修改maxRequestLength属性。
运行该应用程序后，结果如图4-12所示。
图4-12 录入网站信息
在该界面中输入SharePoint网站集URL、网站名称、文档库名称等信息，并选择要上传的文档，如图4-13所示。
图4-13 选择要上传的文档
选择要上传的文档Design.doc后，单击“Upload File”按钮，就可以完成文档的上传，文档成功上传后的结果如图4-14所示。
图4-14 文档上传成功后的结果
至此，完成了文档库的创建、文档上传等基本功能的介绍，在下面的小节中会继续介绍文档库的一些其他高级功能。
4.3.3 文档库版本管理
在企业中对于文档管理系统一个很重要的需求就是对文档版本的管理。有些企业会用一些传统的源代码管理系统进行文档版本管理，但传统的源代码管理系统在管理普通文件时还存在很大的问题。MOSS 2007的文档库则提供了强大的文档版本管理功能。
在SharePoint之前的版本中，版本管理是文档库特有的功能，而到了MOSS 2007，所有的列表记录都可以实现版本管理功能，并且在MOSS 2007中针对版本管理还提供了主版本、次版本这样一些新的特性。
我们先来看一下版本管理的两个基本功能：文档签出和文档签入。
1．文档签出
在SharePoint文档库中实现文档签出功能非常容易，只需要调用SPFile对象的CheckOut()方法就可以了。SPFile的CheckOut()方法有以下两种形式：
（1）CheckOut()
这是文档签出的默认方法，它只是将文档的状态改变为Checked Out。要注意的是，在文档签出时，您需要验证上下文的安全信息，这是因为在文档成功签出后，文档的CheckedOutBy属性要变更为您的用户名，而不能是其他的用户信息。
（2）CheckOut(Boolean, string)
该方法中的布尔值参数表示文档是否在本地签出，字符串参数表示一个UTC格式的日期和时间，这个日期和时间是该文档最后一次被修改的时间。
2．文档签入
在SharePoint文档库中实现文档签入功能只需要调用SPFile对象的CheckIn()方法就可以了。SPFile的CheckIn()方法也有两种形式：
（1）CheckIn(string)
该方法可以将文档签入到SharePoint的文档库中，并可以提供一个注释，字符串参数就表示这个注释。虽然在文档签入时提供注释信息并不是必需的，但在调用该方法时还是要提供注释信息。
（2）CheckIn(string, SPCheckinType)
该方法中字符串参数就表示签入的注释，而SPCheckinType类型的参数则表示文档签入的类型。SPCheckinType是一个枚举值，它包括：MajorCheckIn、MinorCheckIn、OverwriteCheckIn。这3个值分别表示文档签入时使用主版本号、文档签入时使用次版本号、文档签入时覆盖当前文档的版本号。在默认的情况下，文档签入的类型是使用次版本号，您也可以使用其他的类型，但要注意：如果要使用OverwriteCheckIn类型，一定要慎重考虑，因为这样做会覆盖当前文档的版本号。
实例4-8：使用Object Model实现文档的版本管理
下面通过文档版本管理功能的实际例子，来学习文档版本管理的使用。该应用程序代码如下：
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
namespace VersioningExample
{
class Program
{
static void Main(string[] args)
{
SPSite site = new SPSite("http://localhost");
SPWeb web = site.AllWebs["Test"];
SPList docLib = web.Lists["Doc"];
SPFolder folder = docLib.RootFolder;
SPFile theFile = folder.Files["Design.doc"];
Console.WriteLine("About to make changes to {0}", theFile.Name);
theFile.CheckOut();
theFile.SaveBinary(
ASCIIEncoding.Default.GetBytes("This file has been modified programmatically."));
theFile.Update();
theFile.CheckIn("File was modified programmatically.");
Console.ReadLine();
}
}
}
在上面的代码中实现了文档的签出和签入功能，我们对文档库中的文档Design.doc签出后进行修改（加入了注释），然后签入。运行该应用程序后，可以看到文档的版本更新信息，如图4-15所示。
图4-15 文档签入/签出历史记录
从图4-15中可以看出，文档的版本已经从1.0更新为2.0，注释也说明了该文档是通过应用程序进行了修改。
4.3.4 文件夹和文件管理
除了版本管理外，在SharePoint中也可以方便地对文档库的文件夹和文件进行管理，这些管理是通过SPFile类和SPFolder类提供的。
其中，SPFile类提供的主要方法如表4-11所示。
表4-11 SPFile类的主要方法
|
方 法 |
说 明 |
|
Approve |
当一个文件被提交后需要同意时，该方法可以同意该文件提交的内容 |
|
CheckIn |
该方法可以将一个文件签入 |
|
CheckOut |
该方法可以将一个文件签出 |
|
Convert |
该方法可以转换文件 |
|
CopyTo |
该方法可以将一个文件复制到指定的URL |
|
Delete |
该方法可以删除一个文件 |
|
Deny |
该方法可以拒绝需要内容审核的文档 |
|
MoveTo |
该方法可以将一个文件移动到指定的位置 |
|
OpenBinary |
该方法返回一个代表实际文件的字节数组 |
|
OpenBinaryStream |
该方法返回一个指向源文件的流 |
|
Publish |
该方法可以提交需要内容审核的文件 |
|
Recycle |
该方法将文件移到SharePoint网站的回收站中 |
|
SaveBinary |
该方法将文件内容的字节数组保存到SharePoint的存储系统中 |
|
UndoCheckOut |
该方法可以将处于签出状态的文件恢复到签入状态 |
|
UnPublish |
该方法将文件从需要内容审核的队列中移除 |
|
Update |
该方法可以保存对文件所做的更新 |
SPFolder类提供的主要方法如表4-12所示。
表4-12 SPFolder类的主要方法
|
方 法 |
说 明 |
|
CopyTo |
该方法可以将一个文件夹和文件夹中的内容复制到一个新文件夹中 |
|
Delete |
该方法可以删除一个文件夹 |
|
MoveTo |
该方法可以将一个文件夹和文件夹中的内容移动到一个新文件夹中 |
|
Recycle |
该方法将文件夹移到Sharepoint网站的回收站中 |
|
Update |
该方法可以保存对文件夹所做的更新 |
下面通过几个例子，来详细说明对文件夹和文件的管理。首先来看如何将一个文档从一个文档库复制到另外一个文档库。请看下面的代码：
SPSite site = new SPSite("http://localhost");
SPWeb web = site.AllWebs["Test"];
SPFile document = web.GetFile(“Doc/Design.doc”);
document.CopyTo(“http://localhost/Test/Doc2/Design2.doc”, true);
可以看到，通过简单地调用CopyTo()方法就可以实现文档的复制，但要注意该方法只能将文档复制到同一网站下的其他文档库中，而不能进行跨网站复制。将文档复制到新的文档库后，文档的创建者就是运行这段代码的用户账号，并且文档被复制到新的文档库中后，版本号不会变更。
接下来看一下移动文档的例子。请看下面的代码：
SPSite site = new SPSite("http://localhost");
SPWeb web = site.AllWebs["Test"];
SPFile document = web.GetFile(“Doc/Design.doc”);
document.MoveTo(“http://localhost/Test/Doc2/Design2.doc”, true);
可以看到，MoveTo()方法和CopyTo()方法的使用是完全一样的，移动文档实际的动作是删除源文档库中的文档，然后将该文档的所有元数据信息移动到新的文档库中。
事实上，我们还有其他的方式来实现文档的复制功能，可以通过SPFolder类中的Add()方法把一个文档从一个文件夹复制到另外一个文件夹中，代码如下所示。
using (SPSite sitecol = new SPSite("http://localhost"))
{
using (SPWeb site = sitecol.OpenWeb())
{
SPList list = site.Lists["Doc"];
SPWeb site = SPContext.Current.Web;
SPFile document = site.GetFile("Doc/Design.doc");
SPFile newdoc = list.RootFolder.Files.Add
(list.RootFolder.Url + "/" + document.Name,
document.OpenBinary(), document.Author,
document.ModifiedBy, document.TimeCreated,
document.TimeLastModified);
list.Update();
}
}
至此，就已经完整地介绍了文档库的基础功能的开发，您可以在这个基础之上开发出更高层和更个性化的应用。