Provides access to members that manage metadata.
Members
| Name | Description | |
|---|---|---|
 |
CountX | Number of occurrances of an element in the metadata. |
 |
DeleteProperty | Deletes the specified elements. |
|
DeletePropertyByAttribute | Deletes the elements which have the specified attribute value. |
|
GetPropertiesByAttribute | Returns the set of names and values for elements which have the specified attribute value. |
|
InitExisting | Initializes an XmlPropertySet and adds the Esri group of elements. |
|
IsNew | Indicates if a new XmlPropertySet was created on retrieving the metadata. |
|
SaveAsFile | Transforms the metadata using an XSL stylesheet if specified, writes out the header if specified, and saves it in a file. |
|
SetAttribute | Sets the attribute of the specified element. |
|
SetPropertyX | Sets the value of the specified element. |
|
SimpleGetProperty | The values of the specified property. |
|
TransformImages | Transforms encoded thumbnail and image enclosures to files and links them into the metadata. |
IXmlPropertySet.CountX Property
Number of occurrances of an element in the metadata.
Public Function get_CountX ( _
ByVal Name As String _
) As Integer
public int get_CountX (
string Name
);
Description
The Name parameter uses XPath to describe the location and condition of XML nodes in metadata. More information on XPath can be found at the IXmlPropertySet documentation.
Remarks
The CountX property is the number of times the specified metadata element occurs within the XML document. For example, this could be used to find out how many Theme Keywords have been added or whether a specific theme keyword exists.
IXmlPropertySet.DeleteProperty Method
Deletes the specified elements.
Public Sub DeleteProperty ( _
ByVal Name As String _
)
public void DeleteProperty (
string Name
);
Description
The DeleteProperty method removes the specified XML element(s) within an XML document, including all elements contained by the specified elements.
Remarks
The Name parameter uses XPath to describe the location and condition of XML nodes in metadata. XPath includes a set of expressions, allowing for more defined queries and filters. More information on XPath can be found in the IXmlPropertySet documentation.
IXmlPropertySet.DeletePropertyByAttribute Method
Deletes the elements which have the specified attribute value.
Public Sub DeletePropertyByAttribute ( _
ByVal Attribute As String, _
ByVal Value As String, _
ByVal deleteParent As Boolean _
)
public void DeletePropertyByAttribute (
string Attribute,
string Value,
bool deleteParent
);
Description
If true,the Boolean deleteParentparameter removes of the metadata parent element.
As an example, calling this method on XML similar to that shown below with the parameters "approved", "no", and true would not only delete the "idinfo/timeperd/timeinfo/sngdate/caldate" element, but would also delete the parent "idinfo/timeperd/timeinfo/sngdate" element.
IXmlPropertySet.GetPropertiesByAttribute Method
Returns the set of names and values for elements which have the specified attribute value.
Public Sub GetPropertiesByAttribute ( _
ByVal Attribute As String, _
ByVal Value As String, _
ByVal noValues As Boolean, _
ByRef Tags As Object, _
ByRef Values As Object _
)
public void GetPropertiesByAttribute (
string Attribute,
string Value,
bool noValues,
ref object Tags,
ref object Values
);
Description
The GetPropertiesByAttributemethod returns the set of metadata elements where the specific XML attribute has the specified value.
Remarks
The Attributeparameter specifies the name of the attribute within the Xml metadata element. The Valueparameter is the string the attribute is evaluated to or equals. For instance in the example <idinfo/citation/citeinfo/title Sync="TRUE"> the Sync Attributehas a Value of "TRUE".
When used to retrieve a property of type esriXPTBinaryEnclosure or esriXPTImage, the file is extracted from the metadata to a temporary directory and the path of the file is returned as the value. With properties of type esriXPTPicture, the value is an IPicture.
The noValues parameter is currently reserved and has no effect.
IXmlPropertySet.InitExisting Method
Initializes an XmlPropertySet and adds the Esri group of elements.
Public Sub InitExisting ( _
)
public void InitExisting (
);
Remarks
The InitExisting method can be used to add ESRI elements MetaID, CreaDate, CreaTime, and SyncOnce to existing non-ESRI metadata and XML documents. XML documents created outside ArcCatalog won't ever have these elements, unless you call the InitExistingmethod.
Upon synchronization, SyncOnce is replaced with SyncDate and SyncTime. Automatic updates and other editing operations in the user interface, or programmatic updates through the IXmlPropertySetEdit::SetProperty, will add ModDate and ModTime.
Anytime ArcGIS creates metadata, automatic or not, theses ESRI elements will be added.
IXmlPropertySet.IsNew Property
Indicates if a new XmlPropertySet was created on retrieving the metadata.
Public ReadOnly Property IsNew As Boolean
public bool IsNew {get;}
Remarks
The IsNew Boolean property reflects the initial state of the XML metadata document when accessed. If no metadata document exists when accessed, a new metadata document is created containing the ESRI defined tags (these are used by ArcCatalog to maintain the metadata document) "ESRI, MetaID, CreaDate, CreaTime, SyncOnce", and the Boolean attribute IsNew is set to "True". If an XML metadata file exists when initially accessed, the Boolean property is False.
Even if the options to automatically create metadata (available though the user interface from the Tools Menu > Option Command > Metadata Tab) have been unchecked, metadata is still created when accessed programmatically.
IXmlPropertySet.SaveAsFile Method
Transforms the metadata using an XSL stylesheet if specified, writes out the header if specified, and saves it in a file.
Public Sub SaveAsFile ( _
ByVal xslPath As String, _
ByVal header As String, _
ByVal outputANSI As Boolean, _
ByRef outPath As String _
)
public void SaveAsFile (
string xslPath,
string header,
bool outputANSI,
ref string outPath
);
Errors Returned
A known bug exists that occurs when adding a header string. At times additional characters are added to the beginning of the saved file. The characters appear in HTML files, but do no affect viewing. The characters cause an error when viewing XML files. If these extra characters are found, XML files should be edited to remove the characters.
Remarks
The xslPath__parameter is the path of the stylesheet to use when creating output. The stylesheet determines the type of file created by this method (examples are HTML and text files).
If included, the string headeris placed**before the root object. A placeholder (an empty string) is still necessary even if header**is not included.
Unless the boolean parameter outputANSIis true the output file will be Unicode.No differences are found between the two formats for XML, HTML, or Text documents. The outputANSIparameter is used for the FGDC utility MP which only supports ANSI.
The outPathdefines the location for the files to be saved. If a file already exists, it is overwritten. A valid outPathstring must be specified, otherwise output is not created.
IXmlPropertySet.SetAttribute Method
Sets the attribute of the specified element.
Public Sub SetAttribute ( _
ByVal Name As String, _
ByVal Attribute As String, _
ByVal Value As Object, _
ByVal action As esriXmlSetPropertyAction _
)
public void SetAttribute (
string Name,
string Attribute,
object Value,
esriXmlSetPropertyAction action
);
Remarks
The SetAttribute method adds or replaces XML attributes and sets the attribute value.
If the Name expression defines repeating elements, the SetAttribute method will change all elements that satisfy the XPath pattern. For instance "idinfo/keywords/theme/themekey" locates all theme keywords. For more information on XPath, see the IXmlPropertySet interface.
The Action parameter is a esriXmlSetPropertyAction constant. These constants allow several options when encountering different scenarios in metadata. Possible scenarios range from metadata elements which already exist and have attribute value to non-existent metadata elements. How to handle the different cases is determined by the Actionparameter. The esriXmlSetPropertyAction constants work differently depending on the presence/absence of the XML element as well as the presence/absence of the attribute. It is important to be familiar with the different actions. For instance, if the Name expression fails to located the specified XML element, all esriXmlSetPropertyAction constants, except "Replace If Exist", will Add the XML element, attribute, and attribute value. The table below better explains the action constants:
| Action Constant | Element and Attribute Exist | Element exists, Attribute does not | Element does not exist |
|---|---|---|---|
| esriXSPAAddOrReplace | Replaces attribute value | Adds attribute and value | Adds element, attribute and value |
| esriXSPAAddIfNotExists | Nothing happens | Nothing happens | Adds element, attribute and value |
| esriXSPAReplaceIfExists | Replaces attribute value | Adds attribute and value | Nothing happens |
| esriXSPAAddDuplicate | Adds additional element, attribute and value | Adds additional element, attribute and value | Adds element, attribute and value |
IXmlPropertySet.SetPropertyX Method
Sets the value of the specified element.
Public Sub SetPropertyX ( _
ByVal Name As String, _
ByVal Value As Object, _
ByVal propType As esriXmlPropertyType, _
ByVal action As esriXmlSetPropertyAction, _
ByVal syncing As Boolean _
)
public void SetPropertyX (
string Name,
object Value,
esriXmlPropertyType propType,
esriXmlSetPropertyAction action,
bool syncing
);
Description
The SetPropertyX method uses uses XPath to specify metadata elements. The method then adds or replaces the element value.
Remarks
The Name parameter uses XPath to specify metadata elements. Additional information on XPath can be found in the IXmlPropertySet documentation. The Value parameter is the property the will be set to.
The propType parameter is a required esriXmlPropertyType constant. By selecting the constant, the type of data stored within the metadata element (normal text, generic binary enclosures, images, links, picture object, binary enclosures containing an image) is set.
The Action parameter is a esriXmlSetPropertyAction constant. These constants allows several options when encountering different scenarios in metadata. The esriXmlSetPropertyAction constants work differently depending on the presence/absence of the XML element. It is important to be familiar with the different actions. For instance, if the Name expression fails to located the specified XML element, all esriXmlSetPropertyAction constants (except esriXSPAReplaceIfExists) will add the XML element. The table below better explains the action constants:
| Action Constant | Element Exists | Element Does Not Exist |
|---|---|---|
| esriXSPAAddOrReplace | Replaces element | Adds a new element |
| esriXSPAAddIfNotExists | Nothing happens | Adds a new element |
| esriXSPAReplaceIfExists | Replaces element | Nothing happens |
| esriXSPAAddDuplicate | Adds an additional element | Adds a new element |
The Boolean syncing parameter provides an additional degree of control when creating or modifying an element. The parameter indicates whether or not synchronization is taking place. The parameter's setting can override the action parameter. When creating a new element, if the parameter is true, the element is given a Sync attribute with a value of "TRUE". When modifying an existing element, if the syncing parameter is false the element is always modified, and if it has a Sync attribute, the attribute is removed. If the syncing parameter is true when modifying an element, the element's Sync attribute is first inspected; if it has a value of "TRUE", modification occurs, but if it has another value (or no Sync attribute) the modification will not occur.
More information can be found in the white paper "Synchronization in ArcCatalog" May. 2001.
IXmlPropertySet.SimpleGetProperty Method
The values of the specified property.
Public Function SimpleGetProperty ( _
ByVal Name As String _
) As String
public string SimpleGetProperty (
string Name
);
Remarks
The SimpleGetProperty method returns the value of the specified Nameexpression as string.
The Nameexpression uses XPath to locate and process items in XML documents. More information on XPath is available at IXmlPropertySetInterface.
Requesting a property which contains other properties will return the name of one of the child properties.
Using this method to locate Enclosures and Images will extract the files to a temporary directory (if not already extracted) and return the path to the temporary files. Using it to request a property of type Picture will return an IPicture reference.
IXmlPropertySet.TransformImages Method
Transforms encoded thumbnail and image enclosures to files and links them into the metadata.
Public Sub TransformImages ( _
ByVal Path As String, _
ByRef fileNames As Object _
)
public void TransformImages (
string Path,
ref object fileNames
);
Remarks
Do NOT save metadata after applying the TransformImagemethod, otherwise the img tags will be saved and the enclosures themselves will be lost. To further explore this, open the metadata file in a Browser that supports XML, an XML editor, or text editor. At the same time look at the file in ArcCatalog with the XML stylesheet. Search for the element Binary, then notice the differences in the documents as they appear in ArcCatalog.
Thumbnails and image enclosures are not stored in the Binary/Thumbnail/Data and Binary/Enclosure/Data elements respectively. TransformImageis used to decode Thumbnails and images and save them to files, then replace the original elements with HTML <img> tags that contain links to those files. For example, ArcCatalog applies this method to the metadata each time it is opened, this lets you see Thumbnails and Image Enclosures in ArcCatalog.
Path names are created using the supplied string, Path. In the example below, Pathis set to "c:\temp\", while the file name is "_expImg" (_an incremental number is added to the file name for each transformation; expImg0, expImg1, expImg2, etc). The appropriate file extension is added. If no Path is supplied, images are written to temp directory location determined by user environment variables.
Classes that implement IXmlPropertySet
| Classes | Description |
|---|---|
| XmlPropertySet | Esri XML PropertySet object. |
Remarks
This interface uses XPath, a way to select a node or groups of nodes that match a selection criteria, as parameters in several methods and properties (CountX property, DeleteProperty method, SetAttribute method, SetPropertyX method, and SimpleGetProperty method). XPath provides a simple query language for identifying nodes in an XML document based on attribute, name, and values.
An important point when using XPath is that the names of properties and attributes, as well as the values of both, are case sensitive. Also, because metadata always has a <metadata> root node, it can be omitted from patterns used with this interface. For example, "/metadata/node/subnode" should just be "node/subnode".
Some basic examples of XPath include:
- node: Finds all node elements.
- parent/child: Finds all child elements within parent elements.
- parent/*: Finds all elements within parent elements.
- parent[child = "val1"]: Finds all parent elements with a child element that has a value of "val1".
- node[@Sync]: Finds all node elements with a Sync attribute.
- node[@Sync = "TRUE"]: Finds all node elements with a Sync attribute that has a value of "TRUE".
- node[@Sync != "TRUE"]: Finds all node elements with a Sync attribute that has a value other than "TRUE".
- desc[. = "myDesc"]: Finds all desc elements that have a value of "myDesc".
- attr[5]: Finds the 6th attr element (the indexer is zero-based).
For more examples of XPath, see the MSDN article, XPath Examples.
When using this interface on a newly-created XmlPropertySet, the property set should be cast to the IXmlPropertySet2 interface and the InitGeneric method should be called. See the XmlPropertySet coclass documentation for more information.