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 mySite = SPControl.GetContextWeb(Context) (in Visual Basic .NET, use Dim mySite as SPWeb = SPControl.GetContextWeb(Context)). Then use mySite.Lists to get the collection of lists for the site. Similarly, mySite.Title returns the title of the site, and mySite.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:

[Visual Basic .NET]

Dim myList As SPList = myWeb.Lists("Tasks")
myList.Title = "New_Title"
myList.Description = "List_Description"
myList.Update()

[C#]

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

Note  An exceptional case is when a document is checked out from a document library. Metadata for the document cannot be modified using the Update method of the SPListItem object.

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 mySite represents an instance of the SPWeb class, then SPList myList = mySite.Lists["Announcements"] returns the Announcements list in C#, while Dim myList As SPList = mySite.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, or in Visual Basic .NET, Dim myItems As SPListItemCollection = 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) (in Visual Basic .NET, Dim myItems As SPListItemCollection = myList.GetItems(myQuery)).

You can use an indexer to return a specific field from a list (for example, myList.Items["Field_Name"] in C#, or myList.Items("Field_Name") in Visual Basic .NET). 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:

[Visual Basic .NET]

Dim myItem As SPListItem

For Each 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>")

Next myItem

[C#]

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>");
}

Note  In addition to requiring a using directive (Imports in Visual Basic .NET) for the Microsoft.SharePoint namespace, the previous example requires a directive for the Microsoft.SharePoint.Utilities namespace.

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

[Visual Basic .NET]

Dim myWeb As SPWeb = SPControl.GetContextWeb(Context)
Dim myTasks As SPList = myWeb.Lists("Tasks")
Dim myItems As SPListItemCollection = myTasks.Items
Dim myItem As SPListItem

For Each myItem In  myItems

    Response.Write(SPEncode.HtmlEncode(myItem("Title").ToString()) + " :: " _
        & SPEncode.HtmlEncode(myItem("Status").ToString()) + "<BR>")

Next myItem

[C#]

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

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

Note  In addition to requiring a using directive (Imports in Visual Basic .NET) for the Microsoft.SharePoint namespace, the previous example requires a directive for the Microsoft.SharePoint.Utilities namespace.

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:

[Visual Basic .NET]

Dim myNewItem As SPListItem = myList.Items.Add()

myNewItem("URL_Field_Name") = "URL, Field_Description"

myNewItem.Update() 

[C#]

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.

[Visual Basic .NET]

Dim myItem As SPListItem = myItems(0)

myItem("Status") = "Not Started"
myItem("Title") = "Task Title"

myItem.Update() 

[C#]

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.

For information about specific data formats used for list items in Windows SharePoint Services, see the SPListItem class.