Class TaxonomyExtensions

Class for taxonomy extension methods

Inheritance
System.Object
TaxonomyExtensions
Namespace: Microsoft.SharePoint.Client
Assembly: PnP.Framework.dll
Syntax
public static class TaxonomyExtensions : object

Fields

TaxonomyGuidLabelDelimiter

The default Taxonomy Guid Label Delimiter

Declaration
public const string TaxonomyGuidLabelDelimiter = null
Field Value
System.String

Methods

AddTermToTermset(Site, Guid, String)

Adds a term to a given termset

Declaration
public static Term AddTermToTermset(this Site site, Guid termSetId, string term)
Parameters
Site site

The current site
Guid termSetId

The ID of the termset
System.String term

The label of the new term to create
Returns
Term

Returns Term object

AddTermToTermset(Site, Guid, String, Guid)

Adds a term to a given termset

Declaration
public static Term AddTermToTermset(this Site site, Guid termSetId, string term, Guid termId)
Parameters
Site site

The current site
Guid termSetId

The ID of the termset
System.String term

The label of the new term to create
Guid termId

The ID of the term to create
Returns
Term

Returns Term object

CreateTaxonomyField(List, TaxonomyFieldCreationInformation)

Can be used to create taxonomy field remotely in a list.

Declaration
public static Field CreateTaxonomyField(this List list, TaxonomyFieldCreationInformation fieldCreationInformation)
Parameters
List list

List to be processed
TaxonomyFieldCreationInformation fieldCreationInformation

Creation information of the field
Returns
Field

New taxonomy field

CreateTaxonomyField(Web, TaxonomyFieldCreationInformation)

Can be used to create taxonomy field remotely to web.

Declaration
public static Field CreateTaxonomyField(this Web web, TaxonomyFieldCreationInformation fieldCreationInformation)
Parameters
Web web

Site to be processed - can be root web or sub site
TaxonomyFieldCreationInformation fieldCreationInformation

Creation Information of the field
Returns
Field

New taxonomy field

CreateTermGroup(TermStore, String, Guid, String)

Creates a new term group, in the specified term store.

Declaration
public static TermGroup CreateTermGroup(this TermStore termStore, string groupName, Guid groupId = null, string groupDescription = null)
Parameters
TermStore termStore

the term store to use
System.String groupName

Name of the term group
Guid groupId

(Optional) ID of the group; if not provided a random GUID is used
System.String groupDescription

(Optional) Description of the term group
Returns
TermGroup

The created term group

DenormalizeName(String)

Denormalizes a Taxonomy name

Declaration
public static string DenormalizeName(string name)
Parameters
System.String name

Returns
System.String

EnsureLabel(Term, Int32, String, Boolean)

Ensures the specified label for the specified lcid exists.

Declaration
public static void EnsureLabel(this Term term, int lcid, string labelName, bool isDefault)
Parameters
Term term

The term to ensure the label for
System.Int32 lcid

The LCID of the label to ensure
System.String labelName

The name of the label to ensure
System.Boolean isDefault

Determines if the label should be the default

EnsureTermGroup(Site, String, Guid, String)

Ensures the named group exists, returning a reference to the group, and creating or updating as necessary.

Declaration
public static TermGroup EnsureTermGroup(this Site site, string groupName, Guid groupId = null, string groupDescription = null)
Parameters
Site site

Site connected to the term store to use
System.String groupName

Name of the term group
Guid groupId

(Optional) ID of the group; if not provided the parameter is ignored, a random GUID is used if necessary to create the group, otherwise if the ID differs a warning is logged
System.String groupDescription

(Optional) Description of the term group; if null or not provided the parameter is ignored, otherwise the group is updated as necessary to match the description; passing an empty string will clear the description
Returns
TermGroup

The required term group

EnsureTermSet(TermGroup, String, Guid, Nullable<Int32>, String, Nullable<Boolean>, String, String)

Ensures the named term set exists, returning a reference to the set, and creating or updating as necessary.

Declaration
public static TermSet EnsureTermSet(this TermGroup parentGroup, string termSetName, Guid termSetId = null, int? lcid = null, string description = null, bool? isOpen = null, string termSetContact = null, string termSetOwner = null)
Parameters
TermGroup parentGroup

Group to check or create the term set in
System.String termSetName

Name of the term set
Guid termSetId

(Optional) ID of the term set; if not provided the parameter is ignored, a random GUID is used if necessary to create the term set, otherwise if the ID differs a warning is logged
System.Nullable<System.Int32> lcid

(Optional) Default language of the term set; if not provided the default of the associate term store is used
System.String description

(Optional) Description of the term set; if null or not provided the parameter is ignored, otherwise the term set is updated as necessary to match the description; passing an empty string will clear the description
System.Nullable<System.Boolean> isOpen

(Optional) Whether the term store is open for new term creation or not
System.String termSetContact

(Optional) E-mail address for term suggestions and feedback
System.String termSetOwner

Owner of termset
Returns
TermSet

The required term set

ExportAllTerms(Site, Boolean, String)

Exports the full list of terms from all termsets in all termstores.

Declaration
public static List<string> ExportAllTerms(this Site site, bool includeId, string delimiter = "|")
Parameters
Site site

The site to process
System.Boolean includeId

if true, Ids of the the taxonomy items will be included
System.String delimiter

if specified, this delimiter will be used. Notice that IDs will be delimited with ;# from the label
Returns
List<System.String>

Returns list of Term strings

ExportTermSet(Site, Guid, Boolean, String, Int32)

Exports the full list of terms from all termsets in all termstores.

Declaration
public static List<string> ExportTermSet(this Site site, Guid termSetId, bool includeId, string delimiter = "|", int lcid = 0)
Parameters
Site site

The site to process
Guid termSetId

The ID of the termset to export
System.Boolean includeId

if true, Ids of the the taxonomy items will be included
System.String delimiter

if specified, this delimiter will be used. Notice that IDs will be delimited with ;# from the label
System.Int32 lcid

if specified, retrieve terms in the specificed language
Returns
List<System.String>

Returns list of Termset strings

ExportTermSet(Site, Guid, Boolean, TermStore, String, Int32)

Exports the full list of terms from all termsets in all termstores.

Declaration
public static List<string> ExportTermSet(this Site site, Guid termSetId, bool includeId, TermStore termStore, string delimiter = "|", int lcid = 0)
Parameters
Site site

The site to export the termsets from
Guid termSetId

The ID of the termset to export
System.Boolean includeId

if true, Ids of the the taxonomy items will be included
TermStore termStore

The term store to export the termset from
System.String delimiter

if specified, this delimiter will be used. Notice that IDs will be delimited with ;# from the label
System.Int32 lcid

if specified, retrieve terms in the specificed language
Returns
List<System.String>

Returns list of Termset strings

GetDefaultKeywordsTermStore(Site)

Returns the default keywords termstore for the current site

Declaration
public static TermStore GetDefaultKeywordsTermStore(this Site site)
Parameters
Site site

Site to be processed
Returns
TermStore

Returns TermStore object

GetDefaultSiteCollectionTermStore(Site)

Returns the default site collection termstore

Declaration
public static TermStore GetDefaultSiteCollectionTermStore(this Site site)
Parameters
Site site

Site to be processed
Returns
TermStore

Returns TermStore object

GetTaxonomyItemByPath(Site, String, String)

Returns a taxonomy item by it's path, e.g. Group|Set|Term

Declaration
public static TaxonomyItem GetTaxonomyItemByPath(this Site site, string path, string delimiter = "|")
Parameters
Site site

The current site
System.String path

The path of the item to return
System.String delimiter

The delimeter separating groups, sets and term in the path. Defaults to |
Returns
TaxonomyItem

Returns TaxonomyItem object

GetTaxonomySession(Site)

Returns a new taxonomy session for the current site

Declaration
public static TaxonomySession GetTaxonomySession(this Site site)
Parameters
Site site

Site to be processed
Returns
TaxonomySession

Returns TaxonomySession object

GetTermByName(Site, Guid, String)

Gets a Taxonomy Term by Name

Declaration
public static Term GetTermByName(this Site site, Guid termSetId, string term)
Parameters
Site site

The site to process
Guid termSetId

Guid of a TermSet
System.String term

Term name
Returns
Term

Returns Term object

GetTermGroupById(Site, Guid)

Finds a termgroup by its ID

Declaration
public static TermGroup GetTermGroupById(this Site site, Guid termGroupId)
Parameters
Site site

The current site
Guid termGroupId

The ID of the termgroup
Returns
TermGroup

Returns TermGroup object

GetTermGroupByName(Site, String)

Finds a termgroup by name

Declaration
public static TermGroup GetTermGroupByName(this Site site, string name)
Parameters
Site site

The current site
System.String name

The name of the termgroup
Returns
TermGroup

Returns TermGroup object

GetTermGroupByName(TermStore, String)

Gets the named term group, if it exists in the term store.

Declaration
public static TermGroup GetTermGroupByName(this TermStore termStore, string groupName)
Parameters
TermStore termStore

The term store to use
System.String groupName

Name of the term group
Returns
TermGroup

The requested term group, or null if it does not exist

GetTermSetsByName(Site, String, Int32)

Finds a termset by name

Declaration
public static TermSetCollection GetTermSetsByName(this Site site, string name, int lcid = 1033)
Parameters
Site site

The current site
System.String name

The name of the termset
System.Int32 lcid

The locale ID for the termset to return, defaults to 1033
Returns
TermSetCollection

Returns collection of TermSet

GetWssIdForTerm(Web, Term)

Returns the Id for a term if present in the TaxonomyHiddenList. Otherwise returns -1;

Declaration
public static int GetWssIdForTerm(this Web web, Term term)
Parameters
Web web

Term term

Returns
System.Int32

ImportTerms(Site, String[], Int32, String, Boolean)

Imports an array of | delimited strings into the deafult site collection termstore. Specify strings in this format: TermGroup|TermSet|Term

E.g. "Locations|Nordics|Sweden"

Declaration
public static void ImportTerms(this Site site, string[] termLines, int lcid, string delimiter = "|", bool synchronizeDeletions = false)
Parameters
Site site

The current site
System.String[] termLines

Array of TermLines
System.Int32 lcid

Locale identifier (LCID) for the language
System.String delimiter

delimeter which seperates terms
System.Boolean synchronizeDeletions

Remove tags that are not present in the import

ImportTerms(Site, String[], Int32, TermStore, String, Boolean)

Imports an array of | delimited strings into the deafult site collection termstore. Specify strings in this format: TermGroup|TermSet|Term

E.g. "Locations|Nordics|Sweden"

Declaration
public static void ImportTerms(this Site site, string[] termLines, int lcid, TermStore termStore, string delimiter = "|", bool synchronizeDeletions = false)
Parameters
Site site

The current site
System.String[] termLines

Array of TermLines
System.Int32 lcid

Locale identifier (LCID) for the language
TermStore termStore

The termstore to import the terms into
System.String delimiter

delimeter which seperates terms
System.Boolean synchronizeDeletions

Remove tags that are not present in the import

ImportTermSet(TermGroup, Stream, Guid, Boolean, Nullable<Boolean>, String, String)

Imports terms from a term set stream, updating with any new terms, in the same format at that used by the web interface import ability.

Declaration
public static TermSet ImportTermSet(this TermGroup termGroup, Stream termSetData, Guid termSetId = null, bool synchroniseDeletions = false, bool? termSetIsOpen = null, string termSetContact = null, string termSetOwner = null)
Parameters
TermGroup termGroup

Group to create the term set within
Stream termSetData

Stream containing the data to import
Guid termSetId

GUID to use for the term set; if Guid.Empty is passed then a random GUID is generated and used
System.Boolean synchroniseDeletions

(Optional) Whether to also synchronise deletions; that is, remove any terms not in the import file; default is no (false)
System.Nullable<System.Boolean> termSetIsOpen

(Optional) Whether the term set should be marked open; if not passed, then the existing setting is not changed
System.String termSetContact

(Optional) Contact for the term set; if not provided, the existing setting is retained
System.String termSetOwner

(Optional) Owner for the term set; if not provided, the existing setting is retained
Returns
TermSet

The created, or updated, term set
Remarks

The format of the file is the same as that used by the import function in the web interface. A sample file can be obtained from the web interface.

This is a CSV file, with the following headings: 

Term Set Name,Term Set Description,LCID,Available for Tagging,Term Description,Level 1 Term,Level 2 Term,Level 3 Term,Level 4 Term,Level 5 Term,Level 6 Term,Level 7 Term

The first data row must contain the Term Set Name, Term Set Description, and LCID, and should also contain the first term.

It is recommended that a fixed GUID be used as the termSetId, to allow the term set to be easily updated (so do not pass Guid.Empty).

In contrast to the web interface import, this is not a one-off import but runs synchronisation logic allowing updating of an existing Term Set. When synchronising, any existing terms are matched (with Term Description and Available for Tagging updated as necessary), any new terms are added in the correct place in the hierarchy, and (if synchroniseDeletions is set) any terms not in the imported file are removed.

The import file also supports an expanded syntax for the Term Set Name and term names (Level 1 Term, Level 2 Term, etc). These columns support values with the format "Name|GUID", with the name and GUID separated by a pipe character (note that the pipe character is invalid to use within a taxomony item name). This expanded syntax is not required, but can be used to ensure all terms have fixed IDs.

ImportTermSet(TermGroup, String, Guid, Boolean, Nullable<Boolean>, String, String)

Imports terms from a term set file, updating with any new terms, in the same format at that used by the web interface import ability.

Declaration
public static TermSet ImportTermSet(this TermGroup termGroup, string filePath, Guid termSetId = null, bool synchroniseDeletions = false, bool? termSetIsOpen = null, string termSetContact = null, string termSetOwner = null)
Parameters
TermGroup termGroup

Group to create the term set within
System.String filePath

Local path to the file to import
Guid termSetId

GUID to use for the term set; if Guid.Empty is passed then a random GUID is generated and used
System.Boolean synchroniseDeletions

(Optional) Whether to also synchronise deletions; that is, remove any terms not in the import file; default is no (false)
System.Nullable<System.Boolean> termSetIsOpen

(Optional) Whether the term set should be marked open; if not passed, then the existing setting is not changed
System.String termSetContact

(Optional) Contact for the term set; if not provided, the existing setting is retained
System.String termSetOwner

(Optional) Owner for the term set; if not provided, the existing setting is retained
Returns
TermSet

The created, or updated, term set
Remarks

The format of the file is the same as that used by the import function in the web interface. A sample file can be obtained from the web interface.

This is a CSV file, with the following headings: 

Term Set Name,Term Set Description,LCID,Available for Tagging,Term Description,Level 1 Term,Level 2 Term,Level 3 Term,Level 4 Term,Level 5 Term,Level 6 Term,Level 7 Term

The first data row must contain the Term Set Name, Term Set Description, and LCID, and should also contain the first term.

It is recommended that a fixed GUID be used as the termSetId, to allow the term set to be easily updated (so do not pass Guid.Empty).

In contrast to the web interface import, this is not a one-off import but runs synchronisation logic allowing updating of an existing Term Set. When synchronising, any existing terms are matched (with Term Description and Available for Tagging updated as necessary), any new terms are added in the correct place in the hierarchy, and (if synchroniseDeletions is set) any terms not in the imported file are removed.

The import file also supports an expanded syntax for the Term Set Name and term names (Level 1 Term, Level 2 Term, etc). These columns support values with the format "Name|GUID", with the name and GUID separated by a pipe character (note that the pipe character is invalid to use within a taxomony item name). This expanded syntax is not required, but can be used to ensure all terms have fixed IDs.

NormalizeName(String)

Normalizes a Taxonomy name

Declaration
public static string NormalizeName(string name)
Parameters
System.String name

Returns
System.String

RemoveTaxonomyFieldById(Web, Guid)

Removes a taxonomy field (site column) and its associated hidden field by id

Declaration
public static void RemoveTaxonomyFieldById(this Web web, Guid id)
Parameters
Web web

Web object were the field (site column) exists
Guid id

Guid representing the id of the taxonomy field (site column) to be removed

RemoveTaxonomyFieldByInternalName(Web, String)

Removes a taxonomy field (site column) and its associated hidden field by internal name

Declaration
public static void RemoveTaxonomyFieldByInternalName(this Web web, string internalName)
Parameters
Web web

Web object were the field (site column) exists
System.String internalName

Internal name of the taxonomy field (site column) to be removed

SetFieldValueByLabelGuidPair(TaxonomyField, ListItem, String, Boolean)

Sets a value of a taxonomy field. Value parameter is one or more label GUID pairs: Single value field (TaxonomyFieldType) - term label|term GUID Multi value field (TaxonomyFieldTypeMulti) - term label|term GUID;term label|term GUID;term label|term GUID...

Declaration
public static void SetFieldValueByLabelGuidPair(this TaxonomyField taxonomyField, ListItem item, string value, bool systemUpdate = false)
Parameters
TaxonomyField taxonomyField

The field to set
ListItem item

The item to process
System.String value

The value to set on the taxonomy field
System.Boolean systemUpdate

If set to true, will do a system udpate to the item. Default value is false.

SetTaxonomyFieldDefaultValue(Field, TaxonomyItem, String, Boolean)

Sets the default value for a managed metadata field

Declaration
public static void SetTaxonomyFieldDefaultValue(this Field field, TaxonomyItem taxonomyItem, string defaultValue, bool pushChangesToLists = false)
Parameters
Field field

Field to be wired up
TaxonomyItem taxonomyItem

Taxonomy TermSet or Term
System.String defaultValue

default value for the field
System.Boolean pushChangesToLists

push changes to lists

SetTaxonomyFieldValue(ListItem, Guid, String, Guid, Boolean)

Sets a value of a taxonomy field. To set an empty value set label to an empty string and termGuid to an empty GUID.

Declaration
public static void SetTaxonomyFieldValue(this ListItem item, Guid fieldId, string label, Guid termGuid, bool systemUpdate = false)
Parameters
ListItem item

The item to process
Guid fieldId

The ID of the field to set
System.String label

The label of the term to set
Guid termGuid

The id of the term to set
System.Boolean systemUpdate

If set to true, will do a system udpate to the item. Default value is false.

SetTaxonomyFieldValueByTermPath(ListItem, String, Guid, Boolean)

Sets a value in a taxonomy field

Declaration
public static void SetTaxonomyFieldValueByTermPath(this ListItem item, string TermPath, Guid fieldId, bool systemUpdate = false)
Parameters
ListItem item

The item to set the value to
System.String TermPath

The path of the term in the shape of "TermGroupName|TermSetName|TermName"
Guid fieldId

The id of the field
System.Boolean systemUpdate

If set to true, will do a system udpate to the item. Default value is false.

SetTaxonomyFieldValues(ListItem, Guid, IEnumerable<KeyValuePair<Guid, String>>, Boolean)

Sets a value of a taxonomy field that supports multiple values

Declaration
public static void SetTaxonomyFieldValues(this ListItem item, Guid fieldId, IEnumerable<KeyValuePair<Guid, String>> termValues, bool systemUpdate = false)
Parameters
ListItem item

The item to process
Guid fieldId

The ID of the field to set
IEnumerable<KeyValuePair<Guid, String>> termValues

The key and values of terms to set
System.Boolean systemUpdate

If set to true, will do a system udpate to the item. Default value is false.

WireUpTaxonomyField(List, Field, String, String, Boolean)

Wires up MMS field to the specified term set.

Declaration
public static void WireUpTaxonomyField(this List list, Field field, string mmsGroupName, string mmsTermSetName, bool multiValue = false)
Parameters
List list

List to be processed
Field field

Field to be wired up
System.String mmsGroupName

Taxonomy group
System.String mmsTermSetName

Term set name
System.Boolean multiValue

Allow multiple selection

WireUpTaxonomyField(List, Field, Term, Boolean)

Wires up MMS field to the specified term.

Declaration
public static void WireUpTaxonomyField(this List list, Field field, Term anchorTerm, bool multiValue = false)
Parameters
List list

List to be processed
Field field

Field to be wired up
Term anchorTerm

Taxonomy Term
System.Boolean multiValue

Allow multiple selection

WireUpTaxonomyField(List, Field, TermSet, Boolean)

Wires up MMS field to the specified term set.

Declaration
public static void WireUpTaxonomyField(this List list, Field field, TermSet termSet, bool multiValue = false)
Parameters
List list

List to be processed
Field field

Field to be wired up
TermSet termSet

Taxonomy TermSet
System.Boolean multiValue

Term set name

WireUpTaxonomyField(List, Guid, String, String, Boolean)

Wires up MMS field to the specified term set.

Declaration
public static void WireUpTaxonomyField(this List list, Guid id, string mmsGroupName, string mmsTermSetName, bool multiValue = false)
Parameters
List list

List to be processed
Guid id

Field ID to be wired up
System.String mmsGroupName

Taxonomy group
System.String mmsTermSetName

Term set name
System.Boolean multiValue

Allow multiple selection

WireUpTaxonomyField(Web, Field, String, String, Boolean)

Wires up MMS field to the specified term set.

Declaration
public static void WireUpTaxonomyField(this Web web, Field field, string mmsGroupName, string mmsTermSetName, bool multiValue = false)
Parameters
Web web

Site to be processed - can be root web or sub site
Field field

Field to be wired up
System.String mmsGroupName

Taxonomy group
System.String mmsTermSetName

Term set name
System.Boolean multiValue

If true, create a multivalue field

WireUpTaxonomyField(Web, Field, Term, Boolean)

Wires up MMS field to the specified term.

Declaration
public static void WireUpTaxonomyField(this Web web, Field field, Term anchorTerm, bool multiValue = false)
Parameters
Web web

Site to be processed - can be root web or sub site
Field field

Field to be wired up
Term anchorTerm

Taxonomy Term
System.Boolean multiValue

If true, create a multivalue field

WireUpTaxonomyField(Web, Field, TermSet, Boolean)

Wires up MMS field to the specified term set.

Declaration
public static void WireUpTaxonomyField(this Web web, Field field, TermSet termSet, bool multiValue = false)
Parameters
Web web

Site to be processed - can be root web or sub site
Field field

Field to be wired up
TermSet termSet

Taxonomy TermSet
System.Boolean multiValue

If true, create a multivalue field

WireUpTaxonomyField(Web, Guid, String, String, Boolean)

Wires up MMS field to the specified term set.

Declaration
public static void WireUpTaxonomyField(this Web web, Guid id, string mmsGroupName, string mmsTermSetName, bool multiValue = false)
Parameters
Web web

Site to be processed - can be root web or sub site
Guid id

Field ID to be wired up
System.String mmsGroupName

Taxonomy group
System.String mmsTermSetName

Term set name
System.Boolean multiValue

If true, create a multivalue field