Class TaxonomyExtensions
Class for taxonomy extension methods
Inheritance
Namespace: Microsoft.SharePoint.Client
Assembly: PnP.Framework.dll
Syntax
public static class TaxonomyExtensions : objectFields
TaxonomyGuidLabelDelimiter
The default Taxonomy Guid Label Delimiter
Declaration
public const string TaxonomyGuidLabelDelimiter = nullField 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 TermThe 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 TermThe 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 |