Programming with the Microsoft.SharePoint and Microsoft.SharePoint.Administration namespaces

Major top-level classes

The Microsoft.SharePoint and Microsoft.SharePoint.Administration namespaces provide types and members for working with lists and sites, as well as for managing a server or collection of servers running Microsoft® Windows® SharePoint™ Services. These namespaces have four major top-level classes:

• SPGlobalAdmin
• SPVirtualServer
• SPSite
• SPWeb

From these classes you can gain access to all the other classes to work with lists and Web sites, or to manage one or more servers. Starting with one of these classes, you can work through the object model to the class that you need to use. The following table briefly describes these four classes.

In order to perform actions on data within a SharePoint site, you must first obtain an SPWeb object, which serves as the starting point for accessing lists, items, documents, users, alerts, etc. For example, to return a collection of lists for a site within an HTTP context, first obtain the Web object by passing the current System.Web.HttpContext object to the GetContextWeb method of the SPControl class: SPWeb myWeb = SPControl.GetContextWeb(Context) . Then use myWeb.Lists to get the collection of lists for the site. Similarly, myWeb.Title returns the title of the site, and Web.Users returns the users on the site.

Objects

Most classes in the Microsoft.SharePoint and Microsoft.SharePoint.Administration namespaces start with SP. Generally, classes in the Windows SharePoint Services assembly that don't start with this prefix represent Web form controls.

Windows SharePoint Services typically does not save modifications of object properties to the database until you call the Update method on the object. The following example shows how to change the title and description for the Tasks list:

SPList myList = myWeb.Lists[“Tasks�];
myList.Title=“New_Title�;
myList.Description=“List_Description�;
myList.Update();

Collections

Just as lists are at the center of a SharePoint site, so are collections at the center of its object models. You can use each collection to add, delete, enumerate, and update a type of object. Collection classes generally share the following traits:

• Has a name that ends in "Collection."
• Implements the System.Collections.ICollection interface.
• Has a Count property of type Int32.
• Has an Int32 indexer that can be used to get the nth item in the collection.
• Has an indexer that takes an item identifier.
• Has Add and Delete methods.

Calling the Add method for a collection usually updates the database on the back-end server with the appropriate data, except when additional information is required in order to update data. In this case, using the Add method returns an object that you can use to gather the information. For example, to add an item to a list, first use the Add method of the SPListItemCollection class to return an SPListItem object, assign values to appropriate properties of the object, and then call the Update method to effect changes within the content database.

Indexers

Indexers provide a useful means for accessing individual items in collections. To return an item, use square brackets ([]) in C# or parentheses (()) in Visual Basic .NET to contain either an index or a string that identifies the item within the collection.

For example, if myWeb represents an instance of the SPWeb class, then SPList myList = myWeb.Lists["Announcements"] returns the Announcements list in C#, while Dim myList As SPList = myWeb.Lists("Announcements") returns the same list in Visual Basic .NET. You can then use the Items property for the list object to return all the list items in the list (in C#, SPListItemCollection myItems = myList.Items). To return only a subset of items from the list, you can call one of the list object's GetItems methods and pass an SPQuery object to specify the subset: SPListItemCollection myItems = myList.GetItems(myQuery).

You can use an indexer to return a specific field from a list (for example, myList.Items["Field_Name"]). You can also specify a field name in an indexer and iterate through the collection of items in a list in order to return values from the field. This example displays the Due Date, Status, and Title values for each item in a list:

foreach(SPListItem myItem in myItems)
{
    Response.Write(SPEncode.HtmlEncode(myItem["Due Date"].ToString()) + "<BR>");
    Response.Write(SPEncode.HtmlEncode(myItem["Status"].ToString()) + "<BR>");
    Response.Write(SPEncode.HtmlEncode(myItem["Title"].ToString()) + "<BR>");
}

The next example shows how to return all Title and Status values for the Tasks list on a SharePoint site.

SPWeb myWeb = SPControl.GetContextWeb(Context);
			
SPList myTasks = myWeb.Lists["Tasks"];
SPListItemCollection myItems=myTasks.Items;

foreach(SPListItem myItem in myItems)
{
    Response.Write(SPEncode.HtmlEncode(myItem["Title"].ToString()) + "  " +
        SPEncode.HtmlEncode(myItem["Status"].ToString()) + "<BR>");
}

You can also use indexers to modify values in a list. In the following example, a new list item is added to a collection and the values for a URL column are assigned to the item:

SPListItem myNewItem = myList.Items.Add();

myNewItem["URL_Field_Name"] ="URL, Field_Description";

myNewItem.Update();

Note  The URL field type is unique because it involves two values (separated by a comma and a space), and in the above example these values are both assigned to the new item through a single indexer.

The following example sets the Status and Title values for a list item.

SPListItem myItem = myItems[0];

myItem["Status"]="Not Started";
myItem["Title"]="Task Title";

myItem.Update();

Note An indexer throws an ArgumentOutOfRange exception if it does not find the specified item.