Enterprise Keywords management in Office 365 via CSOM

Overview

SharePoint 2013 has introduced Microsoft.SharePoint.Client.Taxonomy namespace for metadata management via CSOM. Since Taxonomy API also allows to manage Keywords, i would like to demonstrate how to get/set Enterprise Keywords field values in this post.

Adding Enterprise Keywords column into List

The first example demonstrates how to add Enterprise Keywords column into List:

private static void AddTaxkeywordFieldInList(List list)
{
var ctx = list.Context as ClientContext;
var taxKeywordField = ctx.Site.RootWeb.Fields.GetByInternalNameOrTitle("TaxKeyword");
var taxKeywordFieldInList = list.Fields.Add(taxKeywordField);
ctx.ExecuteQuery();
}

Setting  Enterprise Keywords field value

The below example demonstrates how to set Enterprise Keywords field value:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.Taxonomy;
namespace SharePoint.Client.Taxonomy
{
/// <summary>
/// Enterpise Keyword Manager
/// </summary>
public class KeywordsManager
{
/// <summary>
/// Set Enterprise Keyword Value
/// </summary>
/// <param name="item">List Item</param>
/// <param name="values">Keyword values</param>
public static void SetTaxKeywordValue(ListItem item,string[] values)
{
var ctx = item.Context;
var list = item.ParentList;
var field = list.Fields.GetByInternalNameOrTitle(TaxKeywordFieldName);
var taxKeywordField = ctx.CastTo<TaxonomyField>(field);
var keywords = values.Select(value => EnsureKeyword(taxKeywordField, value)).ToList();
taxKeywordField.SetFieldValueByValueCollection(item, new TaxonomyFieldValueCollection(ctx, GetTermsString(keywords), taxKeywordField));
}
/// <summary>
/// Ensure Keyword
/// </summary>
/// <param name="taxField"></param>
/// <param name="name"></param>
/// <returns></returns>
private static Term EnsureKeyword(TaxonomyField taxField, string name)
{
var ctx = taxField.Context;
var taxSession = TaxonomySession.GetTaxonomySession(ctx);
var termStore = taxSession.GetDefaultKeywordsTermStore();
var keywords = termStore.KeywordsTermSet.GetAllTerms();
var result = ctx.LoadQuery(keywords.Where(k => k.Name == name));
ctx.ExecuteQuery();
var keyword = result.FirstOrDefault();
if (keyword != null)
{
return keyword;
}
keyword = termStore.KeywordsTermSet.CreateTerm(name, DefaultLanguage, Guid.NewGuid());
ctx.Load(keyword);
ctx.ExecuteQuery();
return keyword;
}
/// <summary>
/// Retrieve formatted Term string
/// </summary>
/// <param name="term"></param>
/// <returns></returns>
private static string GetTermString(Term term)
{
return string.Format("-1;#{0}{1}{2}", term.Name, TaxonomyGuidLabelDelimiter,term.Id);
}
private static string GetTermsString(IEnumerable<Term> terms)
{
var termsString = terms.Select(GetTermString).ToList();
return string.Join(";#", termsString);
}
private const string TaxKeywordFieldName = "TaxKeyword";
private const int DefaultLanguage = 1033;
private const string TaxonomyGuidLabelDelimiter = "|";
}
}

view raw
KeywordsManager.cs
hosted with ❤ by GitHub

Key points:

  • The operation of setting Enterprise Keywords field value consists of two steps, first one to resolve Keyword in Managed Metadata service application (MMS), this what  EnsureKeyword method is intended for.  After Keyword has been retrieved or created if it not existed, the value of Enterprise Keyword field is set (TaxonomyFieldValueCollection type).
Usage
using (var ctx = new ClientContext(webUri))
{
ctx.Credentials = CreateSPOCredentials(userName, password);
var list = ctx.Web.Lists.GetByTitle(listTitle);
var item = list.GetItemById(itemId);
KeywordsManager.SetTaxKeywordValue(item,new []{"2013","2010"});
item.Update();
ctx.ExecuteQuery();
}
public static SharePointOnlineCredentials CreateSPOCredentials(string userName,string password)
{
var securePassword = new SecureString();
foreach (var ch in password)
{
securePassword.AppendChar(ch);
}
return new SharePointOnlineCredentials(userName, securePassword);
}

Results

DocumentsWithTaxKeyword TermStore_Keywords