In addition to querying single lists, the SPQuery object can be used to query across two lists that are joined by a Lookup field and surfacing projected fields. The basics of list joins, lookups, and projected fields are covered in Chapter 8. This chapter simply presents the necessary information to query these lists.

For example, consider two lists named Instructors and Modules. The Instructors list is a simple list that contains contact information for classroom instructors. The Modules list is a custom list that contains information about training modules that will be taught in the classroom. The Modules list is joined to the Instructors list via a Lookup field that shows the FullName of the instructor. In addition, the instructor’s E-mail Address is available as a projected field. In this way, an instructor may be assigned a module to teach. Using an SPQuery object and CAML, you may create a query that returns fields from both of these lists, as shown in Example 9-3.

SPWeb site = SPContext.Current.Web;
SPList listInstructors = site.Lists["Instructors"];
SPList listModules = site.Lists["Modules"];

SPQuery query = new SPQuery;
query.Query = "<Where><Eq><FieldRef Name="Audience"/>" +
              "<Value Type="Text">Developer</Value></Eq></Where>";
query.Joins = "<Join Type="Inner" ListAlias="classInstructors">" +
              "<Eq><FieldRef Name="Instructor" RefType="Id" />" +
              "<FieldRef List="classInstructors" Name="Id" /></Eq></Join>";
query.ProjectedFields =
"<Field Name='Email' Type='Lookup' List='classInstructors' ShowField='Email'/>";
query.ViewFields = "<FieldRef Name="Title" /><FieldRef Name="Instructor" />" +
                   "<FieldRef Name="Email" />";

SPListItemCollection items = listModules.GetItems(query);

In Example 9-3, the Where clause is created to return training modules that are intended for a developer audience; this is similar to the simple example shown earlier. The Join property is new and defines the join between the two lists through the Lookup field. Remember that the query is being run on the Modules list, so it must be joined to the Instructors list. The ListAlias attribute defines an alias for the Instructors list that may be used in the join clause. The first FieldRef element refers to the name of the Lookup field in the Modules list and will always have a RefType equal to Id. The second FieldRef in the join clause uses the alias name for the Instructors list and will always have a Name equal to Id. The ProjectedFields property also uses the alias name for the Instructors list and refers to additional fields in the Instructors list that should be returned with the query.

While the SPQuery object is good for querying a single list or joined lists, if you want to query multiple lists within a site collection simultaneously, then you can make use of the Microsoft.SharePoint.SPSiteDataQuery object. Like the SPQuery object, the SPSiteDataQuery object has Query and ViewFields properties. In addition to these fields, the SPSiteDataQuery object also has Lists and Webs properties. The Lists property is used to specify the lists within the site collection that should be included in the query. The Webs property is used to determine the scope of the query. Example 9-4 shows a query that returns events from all calendars in the current site collection where the end date is later than today.

//Creates the query
SPSiteDataQuery query = new SPSiteDataQuery;

//Builds the query
query.Query = "<Where><Gt><FieldRef Name='EndDate'/>" +
              "<Value Type='DateTime'><Today OffsetDays="-1"/></Value></Gt>
                 </Where>";

//Sets the list types to search
query.Lists = "<Lists ServerTemplate='106' />";

//Sets the Fields to include in results
query.ViewFields = "<FieldRef Name='fAllDayEvent' />" +
                   "<FieldRef Name='Title' />" +
                   "<FieldRef Name='Location' />" +
                   "<FieldRef Name='EventDate' />" +
                   "<FieldRef Name='EndDate' />";

//Sets the scope of the query
query.Webs = @"<Webs Scope='SiteCollection' />";

//Execute the query
DataTable table = SPContext.Current.Site.RootWeb.GetSiteData(query);

The Lists property in Example 9-4 is a CAML fragment that can take several forms to specify the lists to include in the query. Setting the property to <Lists ServerTemplate=[value]/> limits the query to lists of a certain server template. For example, type 106 is a calendar. Table 9-2 shows all the possible values for the ServerTemplate attribute. Setting the property to <Lists BaseType=[value]/> limits the query to lists of a certain BaseType. Table 9-3 lists the possible values for the BaseType attribute. Setting the property to <Lists Hidden=’true’/> includes hidden lists in the query. Setting the property to <Lists MaxListLimit=[value]/> limits the query to considering no more than the specified number of lists.

The Webs property is a CAML fragment that must either be <Webs Scope=’SiteCollection’/> or <Webs Scope=’Recursive’/>. SiteCollection includes all lists in the site collection while Recursive includes only those lists in the current site or subsites beneath the current site.

Chapter 8 began to discuss the support that SharePoint offers for large lists. In particular, you learned that SharePoint allows administrators to throttle the number of items returned in a list view to prevent performance degradation caused by returning an excessive number of items. While these throttle settings apply to views created by users, they also apply to queries executed in custom code.

When executing queries, the number of results returned will be determined by the throttle settings for the given list and the rights of the current user. Throttle settings are set for the Web application in Central Administration. Rights for the current user that affect throttling include administration rights on the Web front-end server, administration rights in the Web application, and auditor rights in the Web application.

In the context of list throttling, users who have server administration rights on the Web front end where the query is run are known as server administrators. Users granted Full Read (auditors) or Full Control (administrators) permissions through the Web application policy in Central Administration are considered super users. Everyone else is termed a normal user.

The List View Threshold is set at the Web application level and specifies the maximum number of items that a database operation can involve at a single time. The default value for this setting is 5,000, which means that results returned from an SPQuery or SPSiteDataQuery object will be generally limited to 5,000 items for both super users and normal users. In addition, the List View Lookup Threshold specifies the maximum number of lookup, person/group, or workflow status fields that can be involved in the query. This value defaults to 6. Server administrators are normally not affected by the List View Threshold or List View Lookup Threshold settings.

Both the SPQuery and SPSiteDataQuery objects have a QueryThrottleMode property that can be set to one of the values in the Microsoft.SharePoint.SPQueryThrottleOption enumeration. The possible values for the property are Default, Override, and Strict. Setting the QueryThrottleMode property to Default causes query throttling to be implemented for both super users and normal users based on the List View Threshold and List View Lookup Threshold settings. Server administrators are not affected.

Setting the QueryThrottleMode property to Override allows super users to return the number of items up to the limit specified in the List View Threshold for the Auditors and Administrators setting so long as the Object Model Override setting is set to “Yes” for the current Web application. Normal users are still limited to returning the number of items specified in the List View Threshold and List View Lookup Threshold settings. Server administrators remain unaffected.

Setting the QueryThrottleMode property to Strict causes the limits specified by the List View Threshold and List View Lookup Threshold settings to apply to all users. In this case, it makes no difference what rights you have in the Web application or server. Example 9-5 shows the RenderContents method from a Web Part with configurable throttling returning query results from a list and demonstrating the concepts that have just been discussed.

protected override void RenderContents(HtmlTextWriter writer)
{
    SPWeb site = SPContext.Current.Web;
    SPList list = site.Lists[listName];
    SPUser user = SPContext.Current.Web.CurrentUser;
    SPQuery query = new SPQuery;

    //Throttle settings
    if (overrideThrottling)
        query.QueryThrottleMode = SPQueryThrottleOption.Override;
    else
        query.QueryThrottleMode = SPQueryThrottleOption.Strict;

    //Execute query
    query.Query = "</OrderBy>";
    query.ViewFields = "<FieldRef Name="Title" />";
    SPListItemCollection items = list.GetItems(query);

    //Show user role
    if(user.IsSiteAdmin || user.IsSiteAuditor)
        writer.Write("<p>You are a 'Super User'</p>");
    else
        writer.Write("<p>You are a regular user</p>");

    //Is throttling enabled?
    if(list.EnableThrottling)
        writer.Write("<p>Throttling is enabled</p>");
    else
        writer.Write("<p>Throttling is not enabled</p>");

    //Show count of items returned
    writer.Write("<p>" + items.Count + " items returned.</p>");

}

Regardless of the value set for the QueryThrottleMode property, no results will be throttled if the query is run within the time specified in the Daily Time Window For Large Queries. During this time period, all queries are allowed to run to completion. In addition, the EnableThrottling property of the list may be set to False to remove the list from any and all throttling restrictions. The EnableThrottling property can be set only by someone with Farm Administrator rights using a Microsoft Windows PowerShell script similar to the following.

$site = Get-SPWeb -Identity "http://intranet.wingtip.com/products"
$list = $site.Lists["Toys"]
$list.EnableThrottling = $false

The development of LINQ technology began in 2003. The goal of LINQ was to make it easier for developers to interact with Structured Query Language (SQL) and Extensible Markup Language (XML) because the programming models were so different. The result today is a query language that can work across a wide variety of sources, including SQL, XML files, arrays, and SharePoint lists, to name just a few.

While the vision for LINQ is to create a single query language that works regardless of the data source, there are several versions of LINQ today. The System.Linq namespace provides the core LINQ functionality, but it may be supplemented by other namespaces, such as System.Data.Linq for SQL access, System.Data.Entity for the Entity Framework, System.Xml.Linq for XML manipulation, or Microsoft.SharePoint.Linq for SharePoint list operations. In all cases, however, the objective is to write similar syntax regardless of the data source.

Each data source must have a LINQ provider. The LINQ provider for a data source implements the System.Linq.IQueryable interface. This interface is the foundation for the LINQ syntax. If a LINQ provider is not available for a data source, then it cannot be queried with LINQ.

As an example of how different data sources can be accessed with similar syntax, look at the code in Example 9-6. This listing shows access to processes, arrays, XML elements, a database, and a collection of objects. In each case, the LINQ query is very similar and straightforward using a syntax that is similar to a SQL statement.

//Processes
var q = from p in Process.GetProcesses
        orderby p.WorkingSet64 descending
        select new { p.ProcessName };

//Arrays
string[] names = { "Ted", "Scot", "Andrew"};

var q = from n in names
        orderby n
        select n;

//XML
string xml = "<Contacts>" +
             "<Contact FirstName="Scot" LastName="Hillier" />" +
             "<Contact FirstName="Ted" LastName="Pattison" />" +
             "<Contact FirstName="Andrew" LastName="Connell" />" +
             "</Contacts>";

XDocument d = XDocument.Parse(xml);

var q = from c in d.Descendants("Contact")
        select new { c.Attribute("FirstName").Value };

//SQL
using (MiniCRM dc =
       new MiniCRM("Data Source=(local);Initial Catalog=MiniCRM;Integrated
Security=True;"))
{

    MiniCRM_Names[] q = (from n in dc.MiniCRM_Names
                         select n).ToArray;

}

//Objects
List<Instructor> contacts = new List<Instructor>;
contacts.Add(new Instructor("Scot", "Hillier"));
contacts.Add(new Instructor("Andrew", "Connell"));
contacts.Add(new Instructor("Ted", "Pattison"));

var q = from c in contacts
        select new { c.FirstName };

To be able to write the LINQ queries shown in Example 9-6, several enhancements were made to the C# language. These enhancements were all targeted at simplifying and unifying how queries are written. Understanding these enhancements will help you create LINQ queries. The following sections cover the key enhancements made to C# and how they are used in LINQ.

List<Customer> customers = new List<Customer>;

Understanding Extension Methods

Extension methods are a language enhancement to C# that allows you to create new methods for a class without subclassing. For example, suppose that you wanted to create a new method for the string class called IsValidEmailAddress that can be used to see if the string contains an email address. To create the extension method, you must create a new static class that contains the extension method as a static method. The following code shows how this is done.

static void Main(string[] args)
{
    //Extension method
    string email = "[email protected]";
    Console.WriteLine(email.IsValidEmailAddress);
}

public static class ExtensionMethod
{
    public static bool IsValidEmailAddress(this string s)
    {
        Regex r = new Regex(@"^[w-.]+@([w-]+.)+[w-]{2,4}$");
        return r.IsMatch(s);
    }
}

Once the extension method is created, it becomes available as a method for the class. This method shows up in IntelliSense as if it were a standard method for the class. Figure 9-1 shows the extension method in Microsoft Visual Studio.

Figure 9-1. An extension method

Extension methods are critical to LINQ queries because they enable functionality in the query. The System.Linq namespace defines several extension methods for the IEnumerable interface that you can use right away. Perhaps the most important extension method is the Where method, which enables you to specify the items to return from a query. This method takes as an argument a delegate function to execute. Example 9-7 shows how the delegate function is defined and used in the Where method to find files that were created on the first day of the month.

Example 9-7. The Where extension method

Func<FileInfo, bool> whereMethod = CreatedOnFirstDay;

static void Main(string[] args)
{
    DirectoryInfo di = new DirectoryInfo("C:\");
    var q1 = di.GetFiles.Where(CreatedOnFirstDay);
}

static bool CreatedOnFirstDay(FileInfo info)
{
    return info.CreationTime.Day == 1;
}

Perhaps the most interesting part of the code in Example 9-7 is the syntax used by the Where method. Note that this syntax looks decidedly different from the LINQ queries shown earlier in the chapter. This is because the syntax in Example 9-7 uses method syntax, while the earlier code uses query syntax. Method syntax looks more like traditional code, while query syntax looks more like a SQL statement. Both method syntax and query syntax are equivalent, but query syntax is preferred because it is more readable. The following code shows the equivalent query syntax for finding files created on the first day of the month.

var q4 = from f in di.GetFiles
             where f.CreationTime.Day == 1
             select f;

var q2 = di.GetFiles.Where(delegate(FileInfo info){
                return info.CreationTime.Day == 1;
                });

var q3 = di.GetFiles.Where(info => info.CreationTime.Day == 1);

public class Person {
  public string FirstName { get; set; }
  public string LastName  { get; set; }
  public int    Age       { get; set; }
}

//Object Initializer
Contact c= new Contact{ FirstName="Gustavo", LastName="Achong" };
//Collection Initializer
List<Contact> contacts = new List<Contact>{
Contact c= new Contact{ FirstName="Gustavo", LastName="Achong" },
Contact c= new Contact{ FirstName="Cathy", LastName="Abel" },
Contact c= new Contact{ FirstName="Kim", LastName="Aber" },
};

var v= new { FirstName="Gustavo", LastName="Achong" };

var q = from p in Process.GetProcesses
        orderby p.WorkingSet64 descending
        select new { Name = p.ProcessName };

SharePoint list data is maintained in the content database. This means that the structure of the list and item data is based on relational tables. As a SharePoint developer, however, you do not need to understand the structure of these tables because the object model abstracts the structure into SPList and SPListItem objects. When you write a LINQ to SharePoint query, you should expect the same experience as when using the object model. List and item data should be abstracted so that you do not have to understand the content database schema.

LINQ to SharePoint provides an object layer abstraction on top of the content database through the use of entity classes. Entity classes are lightweight, object-relational interfaces to the list and item data in the content database. In addition, entity classes are used to track changes and provide optimistic concurrency during updates.

Entity classes are created using a command-line utility called SPMetal. SPMetal is located in the SharePoint system directory at C:Program FilesCommon FilesMicrosoft SharedWeb server extensions14Bin. As a best practice, you should update the PATH variable in your environment to include the path to SPMetal. This way, you can simply run the utility immediately after opening a command window.

Generating entity classes with SPMetal can be very simple. At a minimum, you must specify the site for which you want to generate entities and the name of the code file to create. Once the code file is created, you may immediately add it to a project in Visual Studio and start writing LINQ queries. The following code shows an example that will generate entity classes for all the lists and content types in a site.

SPMetal /web:http://intranet.wingtip.com /code:Entities.cs

While generating entity classes can be quite easy, you will likely want more control over which entities are created and how they are structured. SPMetal provides a number of additional arguments that you can use to alter code generation. Table 9-4 lists and describes all of the possible arguments for SPMetal.

If you examine the code file generated by SPMetal, you will see that there are two kinds of classes are created. First, a single class is created that inherits from Microsoft.SharePoint.Linq.DataContext. The DataContext class provides a connection to lists and change tracking for operations. You can think of the DataContext class as serving a purpose similar to the SqlConnection class in data access code. Second, multiple classes are generated that represent the various content types used by the lists on the site. Using the DataContextclass together with the entity classes allows you to write LINQ queries. Example 9-8 shows a simple LINQ query written to return all training modules contained in the Modules list using a DataContext class named Entities.

using (Entities dc = new Entities(SPContext.Current.Web.Url))
{
    var q = from m in dc.Modules
            orderby m.Title
            select m;

    foreach (var module in q)
    {
        moduleList.Items.Add(module.Title);
    }
}

<?xml version="1.0" encoding="utf-8"?>
<Web Class="Entities" AccessModifier="Public"
  xmlns="http://schemas.microsoft.com/SharePoint/2009/spmetal" >
  <List Name="Instructors" Member="Instructors">
    <ContentType Name="Contact" Class="Instructor">
      <Column Name="FullName" Member="FullName"/>
      <ExcludeOtherColumns/>
    </ContentType>
  </List>
  <List Name="Modules" Member="Modules" />
  <ExcludeOtherLists/>
</Web>

Once you have entities generated, then you can begin to write LINQ to SharePoint queries. Writing LINQ to SharePoint queries is very similar to writing LINQ queries for other data sources. You formulate a query using query syntax, receive the results into an anonymous type and then use the IEnumerable interface to iterate over the results. Example 9-4 earlier in the chapter shows a simple example.

LINQ to SharePoint also supports querying across lists that are joined by a Lookup field. Example 9-3, earlier in this chapter, showed how this is possible with CAML, but LINQ to SharePoint makes the syntax much simpler. The following code shows the equivalent LINQ query for the CAML shown in Example 9-3. Note how the join is done simply by using the dot operator to move easily from the Modules list to the joined Instructors list.

var q = from m in dc.Modules
        orderby m.ModuleID
        select new { m.Title, Presenter = m.Instructor.FullName, Email = m.Instructor.Email};

Not only does this code join two lists together, but it is also using a projection. The new keyword is creating a new set of anonymous objects whose field names have been set to Title, Presenter, and Email.

LINQ to SharePoint also allows you to perform query composition. Query composition is the ability to run a LINQ query on the results of a LINQ query. For example, the following code shows how to run a new query specifically looking for a training module named “Visual Studio 2010.”

var q1 = from m1 in dc.Modules
        orderby m1.ModuleID
        select new {
          m1.Title, Presenter = m1.Instructor.FullName,
          Email = m1.Instructor.Email
        };
var q2 = from m2 in q1
        where m2.Title.Equals("Visual Studio 2010")
        select m2;

Finally, LINQ to SharePoint supports a number of extension methods that you can use for aggregation, grouping, and returning specific entities. The methods are often used on the results of the query. The following code, for example, shows how to return the total number of training modules in the query results. The most commonly used extension methods are listed in Table 9-6.

var t = (from m in dc.Modules
         select m).Count;

Along with queries, you can also add, delete and update lists with LINQ to SharePoint. Adding and deleting items are accomplished using methods associated with the EntityList<T> property of the DataContext. The InsertOnSubmit method adds a single new item to a list; the InsertAllOnSubmit method adds a collection of new items to a list; the DeleteOnSubmit method deletes a single item from a list; and the DeleteAllOnSubmit method deletes a collection of items from a list. The RecycleOnSubmit method puts a single item into the Recycle Bin, and the RecycleAllOnSubmit method puts a collection of items in the Recycle Bin. The following code shows an example of adding a new item to the Modules list.

using (Entities dc = new Entities(SPContext.Current.Web.Url))
{
    ModulesItem mi = new ModulesItem;
    mi.Title = "LINQ to SharePoint";
    mi.Id = 301;
    dc.Modules.InsertonSubmit(mi);
    dc.SubmitChanges();
}

Updating items in lists is done by simply changing the property values in the item and then calling the SubmitChanges method of the DataContext. The following code shows a simple example of an update operation.

using (Entities dc = new Entities(SPContext.Current.Web.Url))
{
    var q = (from m in dc.Modules
            where m.Id==1
            select m).First;

    q.Title = "Revised Title for Module 1";
    dc.SubmitChanges();
}

When updating items, LINQ to SharePoint uses optimistic concurrency. The provider will check to see whether the items in the list have been changed since your LINQ query was run before it will attempt to update them. If a discrepancy is found for any of the submitted entities, then no changes are committed. All discrepancies must be resolved before any change in the current batch can be committed.

When discrepancies are found during the update process, LINQ to SharePoint throws a Microsoft.SharePoint.Linq.ChangeConflictException. In addition, the ChangeConflicts collection of the DataContext is populated with ObjectChangeConflict objects that contain data about fields in the item that are causing conflicts. The SubmitChanges method supports overloads that allow you to specify whether update attempts should continue after the first conflict or whether update attempts should stop. The ChangeConflicts collection will be populated only with information about failed attempts, so electing to stop after the first failure will not provide complete data on all conflicts. Regardless of whether or not you continue update attempts, remember that no changes will be saved if any conflict occurs. The purpose of continuing update attempts is to populate the ChangeConflicts collection completely.

The ChangeConflicts collection contains a MemberConflicts collection, which has detailed information about the actual values causing the conflict. In particular, the MemberConflicts collection is populated with MemberChangeConflict objects, each of which has OriginalValue, CurrentValue, and DatabaseValue properties. OriginalValue is the value of the column when the LINQ query was run. CurrentValue is the value that SubmitChanges is attempting to write to the content database. DatabaseValue is the current value of the column in the database. Trapping ChangeConflictException and using the MemberChangeConflict objects allows you to display the conflicts to the user. The code in Example 9-9 shows how to iterate the collection, build a list, and bind the list to a grid for display.

Try
{
    //Update code
}
catch (Microsoft.SharePoint.Linq.ChangeConflictException x)
{
    conflicts = new List<Conflict>;
    foreach (ObjectChangeConflict cc in dc.ChangeConflicts)
    {
        foreach (MemberChangeConflict mc in cc.MemberConflicts)
        {
            Conflict conflict = new Conflict;
            conflict.OriginalValue = mc.OriginalValue.ToString;
            conflict.CurrentValue = mc.CurrentValue.ToString;
            conflict.DatabaseValue = mc.DatabaseValue.ToString;
            conflicts.Add(conflict);
        }

    }
conflictGrid.DataSource = conflicts;
conflictGrid.DataBind;
}

Along with displaying the results, you can also resolve conflicts in code. After displaying the results to users in a grid, you can allow them to select whether the pending changes should be forced or lost. The Resolve method of the MemberChangeConflict class accepts a Microsoft.SharePoint.Linq.RefreshMode enumeration, which can have a value of KeepChanges, KeepCurrentValues, or OverwriteCurrentValues. KeepChanges accepts every pending change but gives the highest priority to the current user. KeepCurrentValues keeps only the changes made by the current user and loses all other changes. OverwriteCurrentValues loses the current changes and sets the values to what is in the database. After calling the Resolve method, you must call the SubmitChanges method again to complete the operation. The following code shows an example of keeping the current changes and losing all other changes.

foreach (ObjectChangeConflict cc in dc.ChangeConflicts)
{
    foreach (MemberChangeConflict mc in cc.MemberConflicts)
    {
        mc.Resolve(RefreshMode.KeepCurrentValues);
    }
}
dc.SubmitChanges;

Because a document library is a specialized list, you will find that the SPList object can be used to access document libraries as well as lists. This means that document libraries appear in the Lists collection of SPWeb objects just like any other list. The server-side object model supplements the functionality offered by the SPList through the Microsoft.SharePoint.SPDocumentLibrary object, which inherits from SPList and provides the additional functionality necessary to work with document libraries. If you have a reference to an SPList object, you can use the following code to see if the list is actually a document library.

public bool IsListAlsoDocumentLibrary(SPList list) {
  if (list is SPDocumentLibrary)
    return true;
  else
    return false;
}

Once you have a reference to a document library, you may access it through either the SPList object or the SPDocumentLibrary object. In many cases, you will start by working with the SPList object to access the individual SPListItem objects in the library and their associated metadata. You can subsequently use the SPListItem object to access the document associated with the item through the File property. The File property returns a Microsoft.SharePoint.SPFile object. The SPFile object may be used to manage the document and read and write content. The following code shows how to access the SPFile object from the SPListItem object and manipulate the file using the object model.

foreach (SPListItem item in docLib.Items)
{
  if (item.FileSystemObjectType == SPFileSystemObjectType.File) {
    SPFile file = item.File;
    //Check on number of versions
    int versionCount = file.Versions.Count;
    //Determine when document was checked out
    DateTime checkedOutDate = file.CheckedOutDate;
    //Open document for stream-based access
    using(Stream fileContents = file.OpenBinaryStream) {
      // program against stream to access document content
    }
  }
}

Along with documents, many libraries will also contain folders. Folders in a document library are stored as SPListItem objects, but they do not return files from the File property. This structure can be confusing because iterating over the items in a collection will simply return all items and folders in a flat table. If you instead want to access the documents in a particular folder, then you must use the Microsoft.SharePoint.SPFolder object.

The SPDocumentLibrary object has a RootFolder property, which in turn has a Files collection. The RootFolder property returns a SPFolder object, and the Files collection returns all the files that are in the root of the library. A SubFolders property on the SPFolder object allows you to work through the complete hierarchy of folders in the library. The code in Example 9-10 shows how to build a tree view of a document library recursively based on the underlying folder structure.

protected override void OnLoad(EventArgs e) {
  SPWeb site = SPContext.Current.Web;
  foreach (SPList list in site.Lists) {
    if (list is SPDocumentLibrary && !list.Hidden) {
      SPDocumentLibrary docLib = (SPDocumentLibrary)list;
      SPFolder folder = docLib.RootFolder;
      TreeNode docLibNode = new TreeNode(docLib.Title,
                                               docLib.DefaultViewUrl,
                                               @"\_layoutsimagesITDLSM.GIF");
      LoadFolderNodes(folder, docLibNode);
      treeSitesFiles.Nodes.Add(docLibNode);
    }
  }
  treeSitesFiles.ExpandDepth = 1;
}

protected void LoadFolderNodes(SPFolder folder, TreeNode folderNode) {
  foreach (SPFolder childFolder in folder.SubFolders) {
    if (childFolder.Name != "Forms") {
      TreeNode childFolderNode = new TreeNode(childFolder.Name,
                                                    childFolder.Name,
                                                    @"\_layoutsimagesFOLDER.GIF");

      LoadFolderNodes(childFolder, childFolderNode);
      folderNode.ChildNodes.Add(childFolderNode);
    }
  }
  foreach (SPFile file in folder.Files) {
    TreeNode fileNode;
    fileNode = new TreeNode(file.Name, file.Name, @"\_layoutsimagesICGEN.GIF");
    folderNode.ChildNodes.Add(fileNode);
  }
}

Along with managing metadata and viewing files, you will also want to add new files to document libraries. When adding new files to document libraries, it is important to recognize that the library is really just an abstraction on top of the SharePoint website. What this means is that when you add files to a document library, you are really just adding documents to a specific location on the SharePoint site. Therefore, the code for adding documents is found in the SPWeb object, not the SPDocumentLibrary object.

The SPWeb object has a Files property, which returns the SPFileCollection of files in the root of the site. The SPFileCollection object provides Add and Delete methods, which can be used to manage files on the site. The Add method has several overloads, but generally you will need the URL for the library and a Stream object for the file. Example 9-11 shows how to upload a simple text file to the root folder of the Shared Documents document library.

//Create stream and add document content
Stream documentStream = new MemoryStream;
StreamWriter writer = new StreamWriter(documentStream);
writer.Write("Some content for my simple text document");
writer.Flush;

//Add document into document library
string fileName = "MyFile.txt";
string url = "http://intranet.wingtip.com/Shared%20Documents/";
site.Files.Add(url + filename, documentStream, true);

A separate overload of the Add method can be used to add new metadata for a document when it is uploaded. When you use this method, you must create a Hashtable containing the metadata values assigned to properties of the library. Example 9-12 shows a complete file upload operation that sets metadata values.

//Create stream and add document content
Stream documentStream = new MemoryStream;
StreamWriter writer = new StreamWriter(documentStream);
writer.Write("Some content for my simple text document");
writer.Flush;

string fileName = "MyFile.txt";
string url = "http://intranet.wingtip.com/";

//Set metadata
Hashtable docProperties = new Hashtable;
docProperties["vti_title"] = "My Text File";

//Add document into document library
site.Files.Add(url + filename, documentStream, docProperties, true);

Note that in Example 9-12, the names of the document properties do not correspond to the display names of the metadata for the library. The names of the file properties must be the actual names maintained by the document itself. You can list all the metadata properties for a document using the following code.

SPList list = site.Lists["Shared Documents"];
foreach (SPListItem item in list.Items) {
  SPFile file = item.File;
  foreach (DictionaryEntry entry in file.Properties) {
    Console.WriteLine(entry.Key + ": " + entry.Value);
  }
  break;
}

When you are working with documents in SharePoint 2010, you will quite often be dealing with Microsoft Office documents. Therefore, it is important to understand how to create, modify, and manage these document types in your custom solutions. With Office 2007 and later, the file formats for all Office documents are based on an XML standard designed to be more extensible and interoperable than previous formats.

The idea behind the XML document specification is to create an open standard for document definitions so that they may be shared between tools and transformed between systems easily. For SharePoint developers, the Open XML formats are a real advantage because they allow the creation and manipulation of documents through standard XML programming techniques. Prior to Office 2007, the document formats were based on a proprietary binary format that was not documented. From a development perspective, the only way to manipulate a document was to use the object model through automation. This meant starting Microsoft Word, Microsoft Excel, or Microsoft PowerPoint programmatically and then executing operations against it to create documents or slideshows, import data, or print reports.

The problem with automating Word, Excel, and PowerPoint is that they were never intended to function as server products, but they often were deployed on servers to centralize the automation. Because the products were not server-ready, instances of Word, Excel, and PowerPoint often did not shut down properly. In many cases, these solutions required periodic rebooting of the server just to clear the stalled instances of the software. Fortunately, this kind of deployment is no longer necessary.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="../package/2006/relationships ">
  <Relationship Id="rId1"
                Type="../officeDocument/2006/relationships/officeDocument"
                Target="word/document.xml"/>
</Relationships>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
  <Default
     Extension="rels"
     ContentType="application/vnd.openxmlformats-
                  package.relationships+xml"/>
  <Default
     Extension="xml"
     ContentType="application/xml"/>
  <Override
   PartName="/word/document.xml"
   ContentType="application/vnd.openxmlformats-
                officedocument.wordprocessingml.document.main+xml "/>
</Types>

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;

namespace SimpleDocumentCreation
{
    class Program
    {
        static void Main(string[] args)
        {
            using (WordprocessingDocument package =
                WordprocessingDocument.Create(
                "C:\HelloOpenXML.docx",
                WordprocessingDocumentType.Document))
            {
                //Create content
                Body body = new Body(
                    new Paragraph(
                        new Run(
                            new Text("Hello, Open XML SDK!"))));

                //Create package
                package.AddMainDocumentPart;
                package.MainDocumentPart.Document = new Document(body);
                package.MainDocumentPart.Document.Save;
                package.Close;
            }
        }
    }
}

using System;
using System.Linq;
using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;

namespace SimpleDocumentRead
{
    class Program
    {
        static void Main(string[] args)
        {
            using (WordprocessingDocument package =
                WordprocessingDocument.Open(args[0], false))
            {
                var q = from t in package.MainDocumentPart.Document.Descendants<Text>
                        select t;
                foreach (var i in q)
                {
                    Console.WriteLine(i.Text);
                }
            }
        }
    }
}