Overview of SharePoint Portal Server Object Model

This article provides a general overview of the SharePoint Portal Server object model. The Microsoft Office SharePoint Portal Server object model encompasses a number of namespaces—about 50 in total—that provide a way to manipulate SharePoint Portal Server configuration and information.

The object model is so large, it cannot possibly be fully covered here; however, this article will discuss the most important and frequently used namespaces, classes, and methods. It will provide an overview of these components and provide samples useful for developers.

Out of the approximately 50 namespaces provided in the SharePoint Portal Server object model, only 16 of them are supported. The remaining namespaces are reserved for Microsoft’s internal use.

The Microsoft.SharePoint.Portal Namespace
All code and references in the SharePoint Portal Server object model stem from the Microsoft.SharePoint.Portal namespace. The definition for this namespace is found in Microsoft.SharePoint.Portal.dll. When creating projects, you will need to reference this file. The Microsoft.SharePoint.Portal.dll file contains the code for most namespaces under Microsoft.SharePoint.Portal. The following namespaces are not included in this assembly:

Microsoft.SharePoint.Portal.Admin.Search
Microsoft.SharePoint.Portal.SingleSignOn
Microsoft.SharePoint.Portal.SingleSignOn.Security


Included in the Microsoft.SharePoint.Portal namespace are two very important classesPortalApplication and PortalContext. These two classes are the basis for any code written against the SharePoint Portal Server object model.
The PortalContext object is extremely important because it is the entry point for using almost every other object in the SharePoint Portal Server object model.
The PortalApplication class provides functions that can get a PortalContext object.

The following code shows how to get a PortalContext object from an HTTP Context object:
PortalContext context = PortalApplication.GetContext(Context);

Microsoft.SharePoint.Portal.Topology

The Microsoft.SharePoint.Portal.Topology namespace provides functions for interacting with a SharePoint Portal server farm. Using this namespace, you can add servers to a farm, change the configuration database, get a listing of servers in the farm, and in fact build a farm completely through the functions in this namespace. You can also use objects in this namespace to get Microsoft Windows SharePoint Services objects in the Microsoft.SharePoint.Administration namespace. For example, you can get a collection of VirtualServer objects that the farm uses and then perform Windows SharePoint Services operations on those VirtualServer objects to add a Web Part to all virtual servers in the farm.

Another crucial function that the Microsoft.SharePoint.Portal.Topology namespace provides is allowing you to get a PortalContext object from a Console application or a Windows Forms application. For this, you would use the TopologyManager object to get a specific PortalSite object for the portal site you want to connect to. The following code snippet demonstrates how to get a PortalContext object from a console or Windows Forms application:

TopologyManager topology = new TopologyManager();
PortalSite portal = topology.PortalSites[new Uri(http://test-server)];
PortalContext context = PortalApplication.GetContext(portal);

It is important to remember that the URI you pass as an indexer in the preceding sample must be the default portal site URL. For example, if you have a portal site available at http://test-server and the URL http://192.168.0.1 also points to that site, you can only use http://test-server in the code example. Otherwise, the code will throw an exception since the object model gets the reference of the site from the database, and only the default URL is stored.

Microsoft.SharePoint.Portal.UserProfiles
The Microsoft.SharePoint.Portal.UserProfiles namespace is one of the most useful namespaces for Windows Forms and Console applications. It is often used to perform administrative functions. For example, if you do not have Active Directory to import user profiles from, you could use the namespace to import user profiles from any other directory service. You could also pre-create My Sites, otherwise known as Personal Sites, for all users with this namespace so that the server does not have a load spike in production when a user clicks to create a My Site. Creating My Sites are expensive in terms of processor time because they are the same as creating a new Site collection, so it can be beneficial to expend the processor time to create these before the servers go into production.

With this namespace, you can also work with a user’s profile and My Site. You can add properties to the profile, add links to all users’ My Sites, or create reports to see how many users are using their My Site. This namespace provides excellent functionality for administrative functions. This namespace provides administrative functions.

The following code snippet demonstrates how to import user profiles from a text file. It assumes that each property is delimited by a colon (:) character.

public static void Import (string filename)
{
TopologyManager topology = new TopologyManager();
PortalSite portal = topology.PortalSites[new Uri(http://test-server/)];
PortalContext context = PortalApplication.GetContext(portal);
//initialize user profile config manager object
UserProfileManager profileManager = new UserProfileManager(context);
//Open Text File containing user information
System.IO.FileInfo file = new FileInfo(filename);
System.IO.StreamReader fs = file.OpenText();
string read;
while ((read = fs.ReadLine()) != null)
{
//parse line
string[] userInfo = read.Split(":".ToCharArray());
//create user profile if it doesn't exist
string userAccount = userInfo[0];
if (!profileManager.UserExists(userAccount))
profileManager.CreateUserProfile(userAccount);
//Get the userprofile so it can be changed
UserProfile userProfile = profileManager.GetUserProfile(userAccount);
// Set users Preferred name to their first + last name.
userProfile["PreferredName"] = userInfo[2] + " " + userInfo[1];
userProfile["WorkEmail"] = userInfo[0] + "@domain.com";
userProfile.Commit();
}
fs.Close();
}
The next example demonstrates how to add the corporate Web site URL to every user’s Links Web Part. This Web Part is shown on the users’ My Site. You can use this code to add any links that you deem necessary for all users. The sample code is a function that adds the passed URL and title to the “Corporate” category. With modifications, you could also use the code to add certain links to specific sets of users.

public static void Add(string url, string title, bool IsPublic)
{
TopologyManager topology = new TopologyManager();
PortalSite portal = topology.PortalSites[new Uri(http://test-server/)];
PortalContext context = PortalApplication.GetContext(portal);
//initialize user profile config manager object
UserProfileManager profileManager = new UserProfileManager(context);
foreach (UserProfile profile in profileManager)
{
profile.QuickLinks.Add(title, url, "Corporate", IsPublic);
}
}
The next example shows how to create My Sites for all users in the profile database in one shot. It is often useful to create sites for all users before the SharePoint farm goes live to save the performance hit of creating the site during peak times.

public static void Create()
{
//Connect to the portal and get the portal context.
TopologyManager topology = new TopologyManager();
PortalSite portal = topology.PortalSites[new Uri(http://test-server)];
PortalContext context = PortalApplication.GetContext(portal);

//initialize user profile config manager object
UserProfileManager profileManager = new UserProfileManager(context);
foreach (UserProfile profile in profileManager)
{
Console.Write("Creating a Personal Site for " + profile["PreferredName"] + "..." );
try
{
profile.CreatePersonalSite();
Console.Write("Success!\n");
}
catch (PersonalSiteExistsException)
{
Console.Write("Site already exists!\n");
}
catch
{ // Write code to Log or Display Error }
}
}
This final example will create a report which displays all users in the profile database and the URL of their My Site. It will display “None” for the URL if the user does not have a My Site. It will also display the total number of users who have already created a My Site. This report could easily be modified to calculate the size of each user’s My Site and the total size of all My Sites, among other useful information.

public static void Report()
{
int usersWithProfiles = 0, usersWithoutProfiles = 0;
//Connect to the portal and get the portal context.
TopologyManager topology = new TopologyManager();
PortalSite portal = topology.PortalSites[new Uri(http://test-server)];
PortalContext context = PortalApplication.GetContext(portal);
//initialize user profile config manager object
UserProfileManager profileManager = new UserProfileManager(context);
foreach (UserProfile profile in profileManager)
{
Microsoft.SharePoint.SPSite personalSite = profile.PersonalSite;
if (personalSite == null)
{
Console.WriteLine(profile["PreferredName"] + " : " + "NONE");
usersWithoutProfiles++;
}
else
{
Console.WriteLine(profile["PreferredName"] + " : " + personalSite.Url);
usersWithProfiles++;
}
}
Console.WriteLine("Users with Personal Site: " + usersWithProfiles.ToString());
Console.WriteLine("Users without Personal Sites: " + usersWithoutProfiles.ToString());
}

Microsoft.SharePoint.Portal.WebControls
The Microsoft.SharePoint.Portal.WebControls namespace provides several base classes for Web Parts and for interacting exclusively with a portal site. You would not use this namespace from a Console or Windows Forms application because it can only be used from Microsoft ASP.NET. The classes in this namespace are incredibly useful because they take a significant amount of work out of developing repeatedly used functions such as a cacheable Web Part.
Description of Classes in the Microsoft.SharePoint.Portal.WebControls
AudiencePicker : This class provides the same graphical audience picker that is used when targeting content to particular audiences.
BaseAreaWebPart : This class is an inheritable base class that acts like an area. It creates a Web Part that is cacheable, increasing its performance. The Web Parts in the default areas inherit from this Web Part.
BreadCrumbTrail : This class provides a hierarchical view of where the user is in relation to other areas. It will show the parent area and subareas.
CategoryNavigationWebPart : This Web Part implements the top horizontal navigation bar for the portal site and the side navigation bar.
CacheableWebPart : This class provides a base class for a Web Part that implements output caching. Output caching is important to achieve high performance for Web Parts that do not change frequently.
CategoryPicker : This class provides a graphical category hierarchy. It is very similar to the Portal Site Map, provided with SharePoint Portal Server, allowing you to see a list of areas.
HtmlMenu : This class implements an HTML menu much like the drop-down menu SharePoint sites use in many lists.
HtmlMenuButton : This class implements the drop-down button that will display an HtmlMenu class when clicked on.
HtmlMenuItem : This class represents a particular item on an HtmlMenu class.
SearchBox : This class implements a text box and the search functionality behind that box. If you want to develop a more advanced search, this class would be the starting point.
SearchResults : This class implements the SharePoint Portal Server Search Results Web Part. If you want to develop a more advanced search results part, this class would be the starting point.
TextEditor : This class implements the rich text editor control used throughout SharePoint sites.

Microsoft.SharePoint.Portal.Admin.Search.

This namespace provides functions for interacting with the search catalogs. You can manage the catalogs by adding or removing content sources, forcing propagation of the catalogs, and forcing a type of crawl (Full, Incremental, and so on) on a specific search catalog. This namespace, however, does not let you work with individual content sources, only full search catalogs, so you cannot crawl a particular content source directly using the functions, only a particular catalog, such as Portal_Content.

Microsoft.SharePoint.Portal.Search.

The Microsoft.SharePoint.Portal.Search namespace provides only one single class—QueryProvider. With this class, you can call the search service. Although this class does provide the search ability, it is better to use the Search Web service. The Search Web service is more robust and easier to use, plus the code that calls the QueryProvider class can only be run on the local server running SharePoint Portal Server.

Microsoft.SharePoint.Portal.Search.ObjectModel.

This namespace provides classes and functions for manipulating search scopes. With the namespace, you can add, remove, move, update, and list the search scopes on a particular portal site.

Microsoft.SharePoint.Portal.Search.WebQueryService.

This namespace implements the Search Web service, the SPSQueryService class. Using the Search Web service explicitly instead of going through this class is generally easier and allows your code to be run from remote machines.

Microsoft.SharePoint.Portal.SingleSignOn.

This namespace contains classes and functions required for accessing the Single Sign-On service provided with SharePoint Portal Server. You can add different applications, set up the credentials systems, and request credentials from this namespace.

Microsoft.SharePoint.Portal.SingleSignOn.Security.

This namespace contains classes for managing access to the Single Sign-On credentials.

Microsoft.SharePoint.Portal.Security.

This namespace contains functions for working with security in the portal sites. It contains the classes for users, roles, and permissions. If you want to use code to create roles or add users to roles, you would use this namespace.

Microsoft.SharePoint.Portal.Audiences.

This namespace contains functions for working with SharePoint Portal Server audiences. You can get users in particular audiences, create audiences, and rebuild audiences with this namespace. You can use the functions in this namespace to build a Web Part that tailors its information based on audience membership, giving you more flexibility than just targeting a Web Part.

Microsoft.SharePoint.Portal.Alerts.

The Microsoft.SharePoint.Portal.Alerts namespace and its subnamespaces, Microsoft.SharePoint.Portal.Alerts.Types and Microsoft.SharePoint.Portal.Alerts.NotificationTypes, allow you to work with alerts. You can change alerts, remove alerts, add alerts, and enable/disable alerts programmatically.

Microsoft.SharePoint.Portal.SiteData.

The Microsoft.SharePoint.Portal .SiteData namespace provides functions for working with areas. It contains the code for creating areas, removing areas, applying certain area templates, and associating keywords with areas. With this namespace, you can also associate audiences with areas and work with area listings. If you want to manipulate areas through code, you would work with this namespace. It is faster and easier to perform the functions exposed here through the SharePoint Portal Server user interface.