SharePoint user profile properties now writable with CSOM

One of the highly requested capabilities for the SharePoint client side object model (CSOM) has been the capability to update user profile properties. This has been supported for remote operations using web services (UserProfileService.asmx), but since web service interfaces area already deprecated, having this capability natively in the CSOM has been frequently requested.

We have listened and are happy to announce native support for this in the Office 365, using the latest version of the CSOM package (3rd of Sep 2014 or newer). These required methods have been available for a while in the redistributable library and now the capability has been enabled also in service for each tenant. This means that you can start using these new capabilities in your Office 365 development immediately.

Introduction to new methods

Even though from functionality perspective this is huge, actual changes in the CSOM API are relatively simple. These new capabilities are available from the Microsoft.SharePoint.Client.UserProfiles.dll assembly (16 version targeted to cloud) and more precisely as follows.

  • Microsoft.SharePoint.Client.UserProfiles.PeopleManager::SetSingleValueProfileProperty()
  • Microsoft.SharePoint.Client.UserProfiles.PeopleManager::SetMultiValuedProfileProperty()

When this post was written, official documentation in MSDN had not yet been updated, but you will find the updated method signatures in the MSDN at some point. You can download the showed code from this blog post from the Office 365 Developer Patterns and Practices. See more details further down on this blog post.

You need to provide at least Write permission for the user profile service, so that the app will have the right oAuth permissions to perform the required actions, like in below picture.

image

Notice also that when we update the user profile properties, all typical user profile property configurations are still valid. This means for example that you will need to ensure that properties are marked to be editable in the user profile service application. You can access these settings from the SharePoint Admin CenterUser ProfilesManage User Properties – [property] – Edit – Edit Settings.

image

Updating single value property

Here’s a simple example on how to update single value property using these new methods in user profile CSOM. This code is updating the AboutMe property with the updated value.

    1: var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
    2:  
    3: using (var clientContext = spContext.CreateUserClientContextForSPHost())
    4: {
    5:     // Get the people manager instance for current context to get account name
    6:     PeopleManager peopleManager = new PeopleManager(clientContext);
    7:     PersonProperties personProperties = peopleManager.GetMyProperties();
    8:     clientContext.Load(personProperties, p => p.AccountName);
    9:     clientContext.ExecuteQuery();
   10:  
   11:     // Convert entry to html
   12:     string updatedValue = (txtAboutMe.Text).Replace(
   13:                                 Environment.NewLine, "<br />");
   14:  
   15:     // Update the AboutMe property for the user using account name from profile
   16:     peopleManager.SetSingleValueProfileProperty(
   17:                         personProperties.AccountName, "AboutMe", updatedValue);
   18:     clientContext.ExecuteQuery();
   19:  
   20: }

 

Updating multi-value property

Here’s a simple example on how to update multi-value property using these new methods in user profile CSOM. This sample is updating the SPS-Skills property with some new entries.

    1: var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
    2:  
    3: using (var clientContext = spContext.CreateUserClientContextForSPHost())
    4: {
    5:     // Get the people manager instance for current context to get account name
    6:     PeopleManager peopleManager = new PeopleManager(clientContext);
    7:     PersonProperties personProperties = peopleManager.GetMyProperties();
    8:     clientContext.Load(personProperties, p => p.AccountName);
    9:     clientContext.ExecuteQuery();
   10:  
   11:     // Collect values for profile update
   12:     List<string> skills = new List<string>();
   13:     for (int i = 0; i < lstSkills.Items.Count; i++)
   14:     {
   15:         skills.Add(lstSkills.Items[i].Value);
   16:     }
   17:  
   18:     // Update the SPS-Skills property for the user using account name from profile.
   19:     peopleManager.SetMultiValuedProfileProperty(
   20:                             personProperties.AccountName, "SPS-Skills", skills);
   21:     clientContext.ExecuteQuery();
   22:  
   23: }

 

What about just getting the property values?

Here’s also sample code for CSOM for getting user property values as a reference. This capability has been available for a quite a while, but just for a reference together with the update methods. This code is loading all the properties and outputting them to text box in provider hosted app.

    1: var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
    2:  
    3: using (var clientContext = spContext.CreateUserClientContextForSPHost())
    4: {
    5:     // Get the people manager instance and load current properties
    6:     PeopleManager peopleManager = new PeopleManager(clientContext);
    7:     PersonProperties personProperties = peopleManager.GetMyProperties();
    8:     clientContext.Load(personProperties);
    9:     clientContext.ExecuteQuery();
   10:  
   11:     // just to output what we have now to text box
   12:     txtProperties.Text = "";
   13:     foreach (var item in personProperties.UserProfileProperties)
   14:     {
   15:         txtProperties.Text += string.Format("{0} - {1}{2}", 
   16:                         item.Key, item.Value, Environment.NewLine);
   17:     }
   18: }

 

What about on-premises?

Right now this capability was released only to the Office 365 side, but we are actively listening input from the customers and partners for following other actions. You can still continue using user profile web service in the on-premises deployments. It’s important to notice that even though this web service is deprecated, it is still fully supported for on-premises deployments as well. This statement is also valid for Office 365 Dedicated customers (different service than typical Office 365).

Please use the Office Developer User Voice to provide your feedback on the needed capabilities. Having this capability now exposed through CSOM is good example of the changes which were introduced based on the feedback and input from the field (customers and partners).

 

Office 365 Developer Patterns and Practices

Office365PnPLogoRed_thumb1Techniques showed in this blog post are part of the UserProfile.Manipulation.CSOM sample in the Office 365 Developer Patterns and Practices guidance, which contains more than 80 samples and solutions demonstrating different patterns and practices related on the app model development together with additional documentation related on the app model techniques. We are already working on new versions of other samples which are using user profile capabilities and have been using the legacy web service interface.

Check the details directly from the GitHub project at https://aka.ms/OfficeDevPnP. Please join us on sharing patterns and practices for the community.

“From the community for the community” – “Sharing is caring”