Interface IXmlPropertySet

Namespace
ESRI.ArcGIS.Geodatabase
Assembly
ESRI.Server.Geodatabase.dll

Provides access to members that manage metadata.

[Guid("121BD4BC-2508-11D3-A641-0008C7D3AE50")]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IXmlPropertySet

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.

Properties

CountX[string]

Number of occurrances of an element in the metadata.

int CountX[string Name] { get; }

Parameters

Name string

Property Value

int

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.

 

IsNew

Indicates if a new XmlPropertySet was created on retrieving the metadata.

bool IsNew { get; }

Property Value

bool

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.

 

Methods

DeleteProperty(string)

Deletes the specified elements.

void DeleteProperty(string Name)

Parameters

Name string

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.

DeletePropertyByAttribute(string, string, bool)

Deletes the elements which have the specified attribute value.

void DeletePropertyByAttribute(string Attribute, string Value, bool deleteParent)

Parameters

Attribute string
Value string
deleteParent bool

GetPropertiesByAttribute(string, string, bool, out object, out object)

Returns the set of names and values for elements which have the specified attribute value.

void GetPropertiesByAttribute(string Attribute, string Value, bool noValues, out object Tags, out object Values)

Parameters

Attribute string
Value string
noValues bool
Tags object
Values object

Remarks

The Attribute parameter specifies the name of the attribute within the Xml metadata element. The Value parameter is the string the attribute is evaluated to or equals. For instance in the example <idinfo/citation/citeinfo/title Sync="TRUE"> the Sync Attribute has 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.

InitExisting()

Initializes an XmlPropertySet and adds the Esri group of elements.

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 InitExisting method.

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.

SaveAsFile(string, string, bool, ref string)

Transforms the metadata using an XSL stylesheet if specified, writes out the header if specified, and saves it in a file.

void SaveAsFile(string xslPath, string header, bool outputANSI, ref string outPath)

Parameters

xslPath string
header string
outputANSI bool
outPath string

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 header is placed before the root object. A placeholder (an empty string) is still necessary even if header is not included.

Unless the boolean parameter outputANSI is true the output file will be Unicode.  No differences are found between the two formats for XML, HTML, or Text documents. The outputANSI parameter is used for the FGDC utility MP which only supports ANSI.

The outPath defines the location for the files to be saved.  If a file already exists, it is overwritten.  A valid outPath string must be specified, otherwise output is not created.

 

SetAttribute(string, string, object, esriXmlSetPropertyAction)

Sets the attribute of the specified element.

void SetAttribute(string Name, string Attribute, object Value, esriXmlSetPropertyAction action)

Parameters

Name string
Attribute string
Value object
action esriXmlSetPropertyAction

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 Action parameter.  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

SetPropertyX(string, object, esriXmlPropertyType, esriXmlSetPropertyAction, bool)

Sets the value of the specified element.

void SetPropertyX(string Name, object Value, esriXmlPropertyType propType, esriXmlSetPropertyAction action, bool syncing)

Parameters

Name string
Value object
propType esriXmlPropertyType
action esriXmlSetPropertyAction
syncing bool

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.

SimpleGetProperty(string)

The values of the specified property.

string SimpleGetProperty(string Name)

Parameters

Name string

Returns

string

Remarks

The SimpleGetProperty method returns the value of the specified Name expression as string.

The Name expression uses XPath to locate and process items in XML documents. More information on XPath is available at IXmlPropertySet Interface.

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.

TransformImages(string, out object)

Transforms encoded thumbnail and image enclosures to files and links them into the metadata.

void TransformImages(string Path, out object fileNames)

Parameters

Path string
fileNames object

Remarks

Do NOT save metadata after applying the TransformImage method, 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. TransformImage is 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, Path is 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.