Class XmlPropertySetClass
- Namespace
- ESRI.ArcGIS.Geodatabase
- Assembly
- ESRI.Server.Geodatabase.dll
[ClassInterface(ClassInterfaceType.None)]
[Guid("99F50761-C137-11D2-9F83-00C04F8ED211")]
public class XmlPropertySetClass : XmlPropertySet, IPersistStreamInit, IPersist, IPropertySet, IXmlPropertySet, IXmlPropertySet2, ISupportErrorInfo, IClone, IXMLSerialize
- Inheritance
-
XmlPropertySetClass
- Implements
- Inherited Members
Constructors
XmlPropertySetClass()
public XmlPropertySetClass()
Explicit Interface Implementations
Assign(IClone)
Assigns the properties of src to the receiver.
virtual void Assign(IClone src)
Parameters
srcIClone
Clone()
Clones the receiver and assigns the result to *clone.
virtual IClone Clone()
Returns
Count
The number of properties contained in the property set.
virtual int Count { get; }
Returns
Remarks
The Count value will always be one when used with the esriGeodatabase.XmlPropertySet coclass. For more information, see the remarks for the XmlPropertySet coclass.
CountX[string]
Number of occurrances of an element in the metadata.
virtual int CountX[string Name] { get; }
Parameters
Namestring
Returns
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.
DeleteProperty(string)
Deletes the specified elements.
virtual void DeleteProperty(string Name)
Parameters
Namestring
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.
virtual void DeletePropertyByAttribute(string Attribute, string Value, bool deleteParent)
Parameters
DeletePropertyByNameAndAttribute(string, string, string, bool)
Deletes the specified elements which have the specified attribute value.
virtual void DeletePropertyByNameAndAttribute(string Name, string Attribute, string Value, bool deleteParent)
Parameters
Remarks
The DeletePropertyByNameAndAttribute method provides additional parameters to delete XML elements and their corresponding values from metadata documents. Similar actions can be accomplished through other methods (DeleteProperty, DeletePropertyByAttribute) and XPath strings. For instance the following lines of pseudocode accomplish the same action;
xmlPropertySet.DeletePropertyByNameAndAttribute("idinfo/keywords/theme/themekey", "new", "yes", False)
xmlPropertySet.DeleteProperty("idinfo/keywords/theme/themekey[@new='yes']")
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.
If children elements of the specified Name parameter exist, the DeletePropertyByNameAndAttribute method will also remove them from the XML Document.
The Attribute parameter must contain a valid string character. Otherwise the DeleteProperty method should be used for deleting elements without having to specify attributes.
By setting the attribute Value parameter to "", all elements that match the Name and Attribute parameter will be deleted. The DeletePropertyByAttribute method should be used to delete elements without specifying attribute values.
The deleteParent parameter is a Boolean expression that indicates if the parent element of the Name parameter should be deleted. Special attention should be made to this parameter when deleting a Thumbnail or Binary Enclosure. The parent of the Thumbnail element is the Enclosure element, which also happens to be a parent element of the Data element that holds the Binary information. If deleteParent is set to true when specifying the Data or Thumbnail tag, all Enclosures information will be removed.
Deserialize(IXMLSerializeData)
Deserializes an object from XML.
virtual void Deserialize(IXMLSerializeData data)
Parameters
dataIXMLSerializeData
GetAllProperties(out object, out object)
The name and value of all the properties in the property set.
virtual void GetAllProperties(out object names, out object values)
Parameters
Remarks
The GetAllProperties retrieves all names and values in the property set.
GetAttribute(string, string, out object)
Returns the set of values for the specified attribute from the specified elements.
virtual void GetAttribute(string Name, string Attribute, out object Value)
Parameters
Remarks
The GetAttribute method returns the attribute value of the specified metadata element.
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.
The Attribute must contain a valid string. If no string is declared (""), a run time error will occur.
GetClassID(out Guid)
virtual void GetClassID(out Guid pClassID)
Parameters
pClassIDGuid
GetProperties(object, out object)
The values of the specified properties.
virtual void GetProperties(object names, out object values)
Parameters
Remarks
The GetProperties method returns values from a PropertySet CoClass.
public Object GetServerProperty(IServerEnvironment3 server, string propertyName="ExtensionName")
{
Object propertyValue = null;
IPropertySet serverProps = server.Properties;
propertyValue = serverProps.GetProperty(propertyName);
return propertyValue;
}
GetPropertiesByAttribute(string, string, bool, out object, out object)
Returns the set of names and values for elements which have the specified attribute value.
virtual void GetPropertiesByAttribute(string Attribute, string Value, bool noValues, out object Tags, out object Values)
Parameters
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.
GetProperty(string)
The value of the specified property.
virtual object GetProperty(string Name)
Parameters
Namestring
Returns
GetSizeMax(out _ULARGE_INTEGER)
virtual void GetSizeMax(out _ULARGE_INTEGER pCbSize)
Parameters
pCbSize_ULARGE_INTEGER
GetXml(string)
Returns the XML corresponding to the specified element as a string.
virtual string GetXml(string Name)
Parameters
Namestring
Returns
Remarks
The GetXml method returns both the metadata element tag (including attributes/values pairs) and the corresponding value as string.
Specifying an XML element with children nodes will return all children elements and values also.
Because the return variable is of type string, specifying enclosures, images or pictures return the data encoded as Base64 inside of XML tags (unless TransformImages has been called).
If repeating elements are specified, i.e. "idinfo/keywords/theme/themekey", nothing will be returned. More detailed criteria are necessary when specifying the Name parameter. This can be achieved with an XPath query. More information on XPath can be found at the IXmlPropertySet documentation and through documentation below.
IXmlPropertySet2_CountX[string]
Number of occurrances of an element in the metadata.
virtual int IXmlPropertySet2_CountX[string Name] { get; }
Parameters
Namestring
Returns
Remarks
Documentation for this property can be found at the IXmlPropertySet::CountX description.
IXmlPropertySet2_DeleteProperty(string)
Deletes the specified elements.
virtual void IXmlPropertySet2_DeleteProperty(string Name)
Parameters
Namestring
Remarks
Documentation for this property can be found at the IXmlPropertySet::DeleteProperty description.
IXmlPropertySet2_DeletePropertyByAttribute(string, string, bool)
Deletes the elements which have the specified attribute value.
virtual void IXmlPropertySet2_DeletePropertyByAttribute(string Attribute, string Value, bool deleteParent)
Parameters
Remarks
Documentation for this property can be found at the IXmlPropertySet::DeletePropertyByAttribute description.
IXmlPropertySet2_GetPropertiesByAttribute(string, string, bool, out object, out object)
Returns the set of names and values for elements which have the specified attribute value.
virtual void IXmlPropertySet2_GetPropertiesByAttribute(string Attribute, string Value, bool noValues, out object Tags, out object Values)
Parameters
Remarks
Documentation for this property can be found at the IXmlPropertySet::GetPropertiesByAttribute description.
IXmlPropertySet2_InitExisting()
Initializes an XmlPropertySet and adds the Esri group of elements.
virtual void IXmlPropertySet2_InitExisting()
Remarks
Documentation for this property can be found at the IXmlPropertySet::InitExisting description.
IXmlPropertySet2_IsNew
Indicates if a new XmlPropertySet was created on retrieving the metadata.
virtual bool IXmlPropertySet2_IsNew { get; }
Returns
Remarks
Documentation for this property can be found at the IXmlPropertySet::IsNew description.
IXmlPropertySet2_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.
virtual void IXmlPropertySet2_SaveAsFile(string xslPath, string header, bool outputANSI, ref string outPath)
Parameters
Remarks
Documentation for this property can be found at the IXmlPropertySet::SaveAsFile description.
IXmlPropertySet2_SetAttribute(string, string, object, esriXmlSetPropertyAction)
Sets the attribute of the specified element.
virtual void IXmlPropertySet2_SetAttribute(string Name, string Attribute, object Value, esriXmlSetPropertyAction action)
Parameters
NamestringAttributestringValueobjectactionesriXmlSetPropertyAction
Remarks
Documentation for this property can be found at the IXmlPropertySet::SetAttribute description.
IXmlPropertySet2_SetPropertyX(string, object, esriXmlPropertyType, esriXmlSetPropertyAction, bool)
Sets the value of the specified element.
virtual void IXmlPropertySet2_SetPropertyX(string Name, object Value, esriXmlPropertyType propType, esriXmlSetPropertyAction action, bool syncing)
Parameters
NamestringValueobjectpropTypeesriXmlPropertyTypeactionesriXmlSetPropertyActionsyncingbool
Remarks
Documentation for this property can be found at the IXmlPropertySet::SetPropertyX description.
IXmlPropertySet2_SimpleGetProperty(string)
The values of the specified property.
virtual string IXmlPropertySet2_SimpleGetProperty(string Name)
Parameters
Namestring
Returns
Remarks
Documentation for this property can be found at the IXmlPropertySet::SimpleGetProperty description.
IXmlPropertySet2_TransformImages(string, out object)
Transforms encoded thumbnail and image enclosures to files and links them into the metadata.
virtual void IXmlPropertySet2_TransformImages(string Path, out object fileNames)
Parameters
Remarks
Documentation for this property can be found at the IXmlPropertySet::TransformImages description.
InitExisting()
Initializes an XmlPropertySet and adds the Esri group of elements.
virtual 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.
InitGeneric(string)
Initializes an XmlPropertySet without adding the Esri group of elements.
virtual void InitGeneric(string rootName)
Parameters
rootNamestring
Remarks
The InitGeneric method initializes an XmlPropertySet without adding the ESRI group of elements.
This method is available to the XmlProperty CoClass through the IXmlPropertySet2 Interface.
InitNew()
virtual void InitNew()
InterfaceSupportsErrorInfo(ref Guid)
virtual void InterfaceSupportsErrorInfo(ref Guid riid)
Parameters
riidGuid
IsDirty()
virtual void IsDirty()
IsEqual(IClone)
Indicates if the receiver and other have the same properties.
virtual bool IsEqual(IClone other)
Parameters
otherIClone
Returns
IsEqual(IPropertySet)
True if the property set is the same as the input property set.
virtual bool IsEqual(IPropertySet PropertySet)
Parameters
PropertySetIPropertySet
Returns
Remarks
This method indicates whether two property sets are equal.
Note that it will always return false if the property set is an esriGeodatabase.XmlPropertySet (for metadata). See the XmlPropertySet coclass' documentation for more information.
IsIdentical(IClone)
Indicates if the receiver and other are the same object.
virtual bool IsIdentical(IClone other)
Parameters
otherIClone
Returns
IsNew
Indicates if a new XmlPropertySet was created on retrieving the metadata.
virtual bool IsNew { get; }
Returns
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.
Load(IStream)
virtual void Load(IStream pStm)
Parameters
pStmIStream
OverwriteSyncAttribute
Indicates if the Sync attribute will be ignored when setting an element's value.
virtual bool OverwriteSyncAttribute { get; set; }
Returns
Remarks
By default the OverwriteSyncAttribute property is set to false. If the property is changed it remains true for the time the object is held in memory. Once the object is released, the OverwriteSyncAttribute is set back to false.
The OverwriteSyncAttribute property is set for an entire property set and not individual properties.
When the property is set to true, the syncing parameter used and the SetPropertyX methods is ignored. The SetPropertyX action, determined by the esriXmlSetPropertyAction, is then carried out. Otherwise if the OverwriteSyncAttribute property remains false, the esriXmlSetPropertyAction and value of the syncing parameter in the SetPropertyX determine the action.
A complete understanding of the syncing parameter is recommended when setting and getting the OverwriteSyncAttribute property. See the documentation for IXmlPropertySet.SetPropertyX for more information.
RemoveProperty(string)
Removes a property from the set.
virtual void RemoveProperty(string Name)
Parameters
Namestring
Save(IStream, int)
virtual void Save(IStream pStm, int fClearDirty)
Parameters
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.
virtual void SaveAsFile(string xslPath, string header, bool outputANSI, ref string outPath)
Parameters
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.
Serialize(IXMLSerializeData)
Serializes an object to XML.
virtual void Serialize(IXMLSerializeData data)
Parameters
dataIXMLSerializeData
SetAttribute(string, string, object, esriXmlSetPropertyAction)
Sets the attribute of the specified element.
virtual void SetAttribute(string Name, string Attribute, object Value, esriXmlSetPropertyAction action)
Parameters
NamestringAttributestringValueobjectactionesriXmlSetPropertyAction
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 |
SetProperties(object, object)
The values of the specified properties.
virtual void SetProperties(object names, object values)
Parameters
Remarks
Using the Name parameter to locate the specified element, the SetProperties method populates the elements, or adds an new element if it already exists, and sets the value to the coorseponding Values parameter.
The Name parameter uses XSL Patterns to specify metadata elements. Additional information on XSL can be found in the the IXmlPropertySet documentation.
esriXmlSetPropertyAction constants are NOT available to handle situations where an element value already exists. Upon encountering elements that already have values, the new values will replace or add values to existing elements. For more control dealing with elements the IXmlPropertySet::SetPropertyX should be used.
In order to populated nodes further along in the Xml tree, nodes necessary to navigate must first be established. For instance in order to populate the "idinfo/ptcontact/cntinfo/cntperp/cntorg" node each subsequent nodes, "idinfo", "idinfo/ptcontact", "idinfo/ptcontact/cntinfo" and "idinfo/ptcontact/cntinfo/cntperp" must already be in place.
SetProperty(string, object)
The value of the specified property.
virtual void SetProperty(string Name, object Value)
Parameters
Remarks
The Name parameter uses XSL Patterns to specify metadata elements. Additional information on XSL can be found in the the IXmlPropertySet documentation.
SetPropertyX(string, object, esriXmlPropertyType, esriXmlSetPropertyAction, bool)
Sets the value of the specified element.
virtual void SetPropertyX(string Name, object Value, esriXmlPropertyType propType, esriXmlSetPropertyAction action, bool syncing)
Parameters
NamestringValueobjectpropTypeesriXmlPropertyTypeactionesriXmlSetPropertyActionsyncingbool
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.
SetXml(string)
Replaces existing metadata with the content defined in the XML.
virtual void SetXml(string xml)
Parameters
xmlstring
Remarks
The SetXML method replaces the entire metadata document with the Xml string supplied in the XML parameter.
To target specific XML elements, the SetPropertyX method should be used.
SimpleGetProperty(string)
The values of the specified property.
virtual string SimpleGetProperty(string Name)
Parameters
Namestring
Returns
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.
virtual void TransformImages(string Path, out object fileNames)
Parameters
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.