At the heart of the core WSS architecture is the infrastructure for defining list types and provisioning list instances to store content. Document libraries, which play a vital role in creating WSS business solutions, can be seen as hybrid lists that leverage and extend the same mechanisms and storage model that are used by standard lists.

WSS ships with a variety of built-in list types that can solve many business needs without requiring custom development. These list types are visible on the standard WSS Create page, and they enable users to quickly create list instances on an ad hoc basis. Within the Create page, these built-in list types are broken out into sections including Libraries, Communications, Tracking, and Custom Lists.

At a lower level, WSS classifies list types using base types. Standard lists have a base type of 0, whereas document libraries have a base type of 1. There also are less frequently used base types for discussion forums (3), vote or survey lists (4), and issue lists (5). The base type defines a common set of columns, and all list types that are based on that base type automatically inherit those columns. For example, each of the built-in base types defines an ID field. This enables WSS to track each item in a list and to track each document in a document library behind the scenes with a unique integer identifier. WSS also adds several columns to the base type for document libraries that are not needed for standard list types.

List instances can be created either by users through the WSS user interface or by developers through the WSS object model. Let’s start with a basic code sample that demonstrates how to create a new list instance from one of the built-in list types.

Following sample provides the code to create a list instance. Before creating the list, the code checks to make sure a list of the same title doesn’t already exist. You will notice that the code enumerates through the lists within the current site, checking each list to see if there is a matching title. If a list with a matching title does not exist, the code in this application then creates a new instance of the Announcements list type and adds a link to the Quick Launch menu for easy access.

using System;

using Microsoft.SharePoint;

class Program {

  static void Main() {

    using (SPSite site = new SPSite("http://localhost")) {

      using (SPWeb web = site.OpenWeb()) {

        string listName = "Litware News";

        SPList list = null;

        foreach (SPList currentList in web.Lists) {

          if (currentList.Title.Equals(listName,

                                       StringComparison.InvariantCultureIgnoreCase)) {

            list = currentList;

            break;

          }

        }

        if (list == null) {

          Guid listID = web.Lists.Add(listName,

                                      "List for big news items",

                                      SPListTemplateType.Announcements);

          list = web.Lists[listID];

          list.OnQuickLaunch = true;

          list.Update();

        }

      }

    }

  }

}

Note the required call to the Update method on the SPList object at the end of this listing. This is required to save any changes you have made to list properties, such as, in this case, assigning a value of “true” to the OnQuickLaunch property.

Lists can also be accessed by using the GetList methods of the SPWeb class:

SPList announcementsList = web.GetList("/Lists/Announcements");

The GetList method takes a site-relative path to the list folder or a list form page as an argument. If the list instance is not found, the GetList method will throw an exception of type FileNotFoundException. The only way to check if a list exists without throwing an exception is to enumerate the site object’s lists and check for its existence.

After you have a reference to an SPList object for the list, you can create a new list item by adding an SPListItem to its Items collection. The SPListItem is a generic item with fields corresponding to the fields in the list. You can create and save a new list item by using the following code:

SPListItem newItem = list.Items.Add();

newItem ["Title"] = "Litware Goes Public!";

newItem ["Body"] = " We all live in exciting times.";

newItem["Expires"] = DateTime.Now + TimeSpan.FromDays(2);

newItem.Update();

The Update method of the SPListItem object commits the changes to the list. If you don’t call the Update method, the list item data will not be saved. The fields (columns) of the list are specified using the display name. They can also be accessed by the GUID identifier of the field or the zero-based index in the Fields collection. If a field is specified that is not in the Fields collection for the list, an ArgumentException will be thrown. In some scenarios, you may want to enumerate through the fields in a list by using a foreach construct to ensure the field you are looking for really exists.

foreach (SPField field in list.Fields) {

  if (!field.Hidden && !field.ReadOnlyField)

    Console.WriteLine(field.Title);

}

Enumerating through the fields also can be useful when enumerating list items. You can use the Fields collection to access data from the list item. To limit the fields displayed, you may want to display only user editable fields as shown in the following code example:

foreach (SPListItem item in list.Items) {

  foreach (SPField field in list.Fields) {

    if (!field.Hidden && !field.ReadOnlyField)

      Console.WriteLine("{0} = {1}", field.Title, item[field.Id]);

  }

}

Tags: