Chapter 8
Working with Document Libraries and Files

IN THIS CHAPTER

• Document Library Basics
• Working with the Document Library Object Model
• Working with Versioning
• Manipulating Folders and Files

Document management is one of SharePoint’s key features. Many organizations that use Microsoft Office SharePoint Server (MOSS) might choose to ignore the vast majority of SharePoint’s features but will still utilize its document management facilities.

SharePoint includes incredibly powerful features for storing, indexing, manipulating, versioning, and retrieving documents. As with just about every other aspect of SharePoint, you can utilize all of this power within your applications or your Web Parts. This chapter provides a description of the various ways in which you can write code to access and manipulate documents within SharePoint—everything from checking files in and out to navigating a nested hierarchy of folders and files within a document library.

Document Library Basics

A document library is really just a list with some added functionality on top. Many developers assume that document libraries aren’t very powerful because they are just specialized lists. Although it is true that they are specialized lists, document libraries are also extremely powerful and flexible and your code can benefit greatly from being able to treat document libraries like standard lists when the need arises.

The first thing that developers might find helpful about document libraries is that the entire object model for lists and list items applies to document libraries and documents, respectively. You can treat a document as an instance of SPListItem and you can treat a document library as an instance of SPList.

If you don’t need that kind of generic access, you can access document libraries with the SPDocumentLibrary class and you can manipulate files with the SPFile class.

Uploading a document to a document library causes SharePoint to store the document’s raw data internally within Microsoft SQL Server. This means that you can use the application programming interface (API) to get at the document itself rather than having to hunt around on shared drives for files.

SharePoint lists (which include document libraries) can be version controlled, and the SPFile class provides multiple methods for dealing with version control. All of these powerful features are explored throughout this chapter.

Working with the Document Library Object Model

The SharePoint object model has robust support for document libraries. That support is provided by several key classes:

• SPFileCollection
• SPFile
• SPDocumentLibrary
• SPListItem
• SPFolderCollection
• SPFolder

Classes such as SPFile and SPFolder provide a great deal of functionality as well as many properties that can be used to examine a considerable amount of information pertaining to files and folders.

Tables 8.1 and 8.2 provide an overview of some of the most commonly used properties on the SPFile and SPFolder classes.

Table 8.1. Common SPFile Properties

Table 8.2. Common SPFolder Properties

Building a Document Library Explorer Sample

The best way to get a feel for how all of the document, file, and folder classes relate to each other is to look at a hands-on example. This section walks you through building a sample document library explorer. This application illustrates how to get a list of document libraries on a site, how to recursively obtain a list of all folders within the library, and how to retrieve a list of all files contained within a given folder.

To get started, create a new Windows Forms application and make sure you add a reference to the Microsoft.SharePoint.dll Assembly.

Add a text box called siteName, a text box called siteUrl, and a button called exploreButton. Then add a TreeView (folderTree) and a ListView (documentList). With that in place, modify the code behind the form to match the code in Listing 8.1. You’ll need to double-click the Explore button to create a click-handler stub and create an event-handler stub for the TreeView’s AfterSelect property.

Listing 8.1. Form1.cs (Document Library Explorer)

An interesting thing to note in Listing 8.1 is that the Folders property of the SPDocumentLibrary class actually returns an SPListItemCollection instead of an SPFolderCollection. It’s not that big of an inconvenience, however. When using an instance of an SPListItem, you can use the Folder property to get back an instance of the corresponding folder. Conversely, when using an instance of SPFolder, you can get at the corresponding list item with the Item property.

Take a look at the lines of code in Listing 8.1 that loop through the contents of the Folders collection on the selectedLib.Folders collection. Notice that there is logic in there to make sure that only items that belong directly to the root folder appear. This is because the Folders collection of a document library actually contains all of that library’s folders, regardless of their position within the hierarchy. This can be a help or a hindrance, depending on what you need to accomplish.

Add a second form called DocLibPicker.cs to the project. On the form, add a ListBox called docLibList and a button called selectButton. Add three columns to docLibList: File Name, Version, and Author. Double-click the selectButton to create an event handler. If you don’t feel like going through all those steps manually, you can always get the code directly from the code download for this book.

Listing 8.2 shows the code for the dialog box that presents the user with a list of document libraries from which they can choose. This illustrates the inheritance hierarchy that allows you to use the is and as operators with the SPList and SPDocumentLibrary classes.

Listing 8.2. DocLibPicker.cs (Document Library Explorer)

Figure 8.1 shows this application in action.

Figure 8.1. Document Library Explorer application.

The sample Document Library Explorer application shows how you can navigate folder hierarchies within document libraries, tell the difference between regular lists and document libraries, and how to get a listing of files belonging to a given folder.

Working with Versioning

Versioning only applied to document libraries in previous versions of SharePoint. In the new version, any list item anywhere within SharePoint can be versioned. Not only do all items now have versioning support, they all have support for both major and minor version numbers—another new addition with MOSS 2007.

One of the most common reasons behind a company’s need for a document management solution is the need for document revision control. Using traditional source code control systems to manage document revisions often fails miserably when applied to regular documents. SharePoint is optimized for document revision control.

Checking Files Out

There are two overloads to the CheckOut() method on the SPFile class:

• CheckOut()—This is the default method for checking files out. It simply changes the file’s status to checked out. Note that if you want to check a file out, you need to have a valid security context. This means that the security context under which the CheckOut() method executes is also the user who will show up in the file’s CheckedOutBy property.
• CheckOut(Boolean,  string)—The Boolean indicates whether the file should be checked out locally, and the string parameter is a UTC-formatted date/time stamp indicating the time and date the item was last modified.

Checking Files In

Checking files in to SharePoint is just as easy as checking them out. You can check files in with the following two overloads of the CheckIn() method:

• CheckIn(string)—This method checks a file in to SharePoint with the specified comment. Even though check-in comments are optional within the SharePoint UI, you must still include a comment with this method call.
• CheckIn(string,  SPCheckinType)—This method checks a file in to SharePoint with the specified comment and indicates the type of check-in. By default, check-ins are minor revision check-ins, but you can override that with the SPCheckinType enumeration: MajorCheckIn, MinorCheckIn, or OverwriteCheckIn. Make sure you use the last option only when you’re sure that’s what you need because it will overwrite the current version in SharePoint.

The code in Listing 8.3 illustrates how to locate a file, check it out, make changes, and then check the file back in to SharePoint.

Listing 8.3. Versioning Demonstration Code

Although it might make sense that the root folder of a document library would be located in the first element of the Folders property of the document library, that isn’t the case. Remember that the Folders property contains all folders belonging to the document library regardless of their hierarchy level. As such, you need to use the RootFolder property of the document library to get the SPFolder instance that corresponds to the document library’s root folder.

Figure 8.2 shows the version history for the sample text file modified in Listing 8.3 after executing the application a few times.

Figure 8.2. Version history for sample text file.

Figure 8.3 shows the contents of the latest version of the file—the string that was passed as a parameter to the SaveBinary() method of the SPFile object.

Figure 8.3. Contents of a programmatically modified file in a document library.

Manipulating Folders and Files

SharePoint allows virtually any list to have folders and subfolders and you can even create content types for folders within lists. Despite the ubiquity of folders in SharePoint lists, the most common use for folders is to organize files within document and picture libraries (a picture library is a specialized form of a document library).

A small sample of what you can do with folders and files was illustrated in Listing 8.3. Tables 8.3 and 8.4 provide a good reference list of some of the more commonly used methods on the SPFolder and SPFile classes.

Table 8.3. Common SPFolder Methods

Table 8.4. Common SPFile Methods

Summary

Document libraries are the foundation of the document management functionality within SharePoint. This chapter covered the basics of document libraries, working with version-controlled documents, modifying documents, and navigating through nested hierarchies of folders within document libraries.

Using the information contained in this chapter, you should be well equipped to perform virtually any task that involves a document library, folder, or file.