IN THIS CHAPTER
User profiles in Microsoft Office SharePoint Server (MOSS) 2007 not only provide a means by which basic information can be stored about individual users, but user profiles also provide features for community building, social networking, and much more.
This chapter shows you how to create, update, and manipulate user profiles and user profile properties using the object model.
Accessing user profiles with the object model involves a few simple steps. First, your code must have references to the Microsoft.SharePoint
, Microsoft.Office.Server
, and System.Web
Assemblies. With those references available, you can use the SPSite
class and the UserProfileManager
class as entry points into the user profile subsystem within MOSS.
The following sections provide samples of the various ways that you can access user profiles.
Retrieving user profiles can be done one of two ways. The first way is done simply by enumerating through the entire list of user profiles stored on a given farm. The second way is by retrieving the profile of an individual user. Note that there are two ways to get a user profile into the system. The first is by manually creating the user profile through SharePoint administrative tools. User profiles are created automatically the first time a user navigates to their My Site. In other words, you cannot guarantee that the system will have a stored user profile even if the account in question is a valid Active Directory account.
Listing 12.1 shows how to enumerate profiles as well as retrieve individual profiles.
Listing 12.1. Retrieving User Profiles
On the test system, the output of the preceding code produces the following block of text:
Each profile has a stock set of properties that are defined by SharePoint and come with every installation of the product such as first name, last name, email address, and so on. In addition to the stock set of properties, you can create custom profile properties that store information relevant to your organization.
Listing 12.2 illustrates code that will retrieve the properties configured in SharePoint for a given user profile.
Listing 12.2. Retrieving Profile Properties
On the test server on which this code was written, the output of the preceding code is as follows:
Modifying a user profile after you have a reference to it is actually quite easy. Most of the modifications to a user profile involve modifying the user profile properties. You can modify the property using a reference to the predefined property name constants, as shown in this snippet:
profile[PropertyConstants.HomePhone].Value = "555-555-1212";
Or, you can modify them using the names of your own custom created profile properties:
profile["FavoriteColor"] = "Blue";
Be careful not to use names of properties that have not been added to the user profile, or SharePoint will throw an exception indicating that the given indexer was out of range.
Make sure that you call the Commit
method when you are finished making changes to the profile:
profile.Commit();
In addition to making changes to user profiles, you can also obtain the change log history for any given user profile. The code for retrieving and enumerating through the change list for a given user profile is shown in Listing 12.3.
You can specify a change log query that can narrow or broaden the search for modifications.
Listing 12.3. Getting Recent Changes from the Change Log
When the preceding code is executed, it will show output similar to the following (varying, of course, on the user examined and the changes that have occurred on your own system):
Although many programming tasks related to user profiles can be accomplished by accessing user profiles and reading and writing profile properties, you can also programmatically manipulate the user profile store by creating new profiles and profile properties.
This section of the chapter contains code samples illustrating creating user profiles, simple profile properties, and complex profile properties such as multivalued properties and choice list properties.
To create a user profile, you just need to supply the account name on which the profile will be based to the CreateUserProfile
method on the UserProfileManager
class, as shown in the following code block:
To create a new user profile property, you will need to call the Create
method on the ProfilePropertyCollection
class, as shown in the following code snippet that creates a new profile property for storing the user’s favorite color:
Keep in mind that profile properties created like this can be accessed, read, and updated using the code shown earlier in the chapter. There is no difference between the code to manipulate built-in properties and custom created profile properties.
Two additional types of user profile properties store values slightly more complex than the scalar values (string, integer, Boolean) shown previously: multivalued properties and choice list properties.
The multivalued property is extremely easy to create. You simply need to set the IsMultiValued
property of a profile property to true
, as follows:
p.IsMultiValued = true;
To create a user profile property that allows selections from a choice list, you just add values to the ChoiceList
property of the user profile property object:
Depending on what you’re using a given user profile property for, you might want to create new properties with alternate value delimiters, or you might want to modify the value separator for an existing property. You can do this by modifying the Separator
property of a user profile property object:
property.Separator = MultiValueSeparator.Comma;
The MultiValueSeparator
enumeration has the following values: Comma
, Newline
, Semicolon
, Unknown
.
User profiles are far more than just repositories for information about individual people. They also provide community-building and social networking features through group memberships. You can create custom groups dynamically using code and you can add individual user profiles to those groups, as shown in the following code snippet:
The final argument to the CreateMemberGroup
method is called sourceEntry
. The source entry argument indicates the directory entry of the distribution list from Active Directory, or the SPWeb
or SPSite
object depending on the MemberGroup
and the configuration of shared services.
In an effort to provide enhanced social networking features for user profiles in MOSS, you can now programmatically obtain a list of commonalities among user profiles by using several methods for retrieving common data:
GetCommonMemberships
—Method called on the MembershipManager
class for retrieving common memberships among profilesGetCommonManager
—Method called on the UserProfile
class for retrieving a common managerThe following code snippet shows how to obtain and enumerate commonalities among user profiles. (Note that this code will only work if there is a common manager found.)
This chapter provided an overview and many code samples illustrating how you can write code to interact with the powerful user profile store in MOSS 2007. Using custom profile properties, advanced profile properties, social networking features, and much more, you can write code for the SharePoint object model that does extremely powerful and useful things with the user profile store.