Embedding custom XML in an XML for Visio file

  • Article

Embedding custom XML in an XML for Visio file

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

You can include custom XML data within your XML for Visio file, provided the data contains well-formed XML that complies with the XML for Visio schema and the internal rules of Visio.

You can embed custom XML in an XML for Visio file in two ways:

  • As unknown XML, which is XML that Visio does not understand, but will round-trip with an XML for Visio file when contained in particular elements.
  • As solution XML, which is well-formed XML contained within a SolutionXML element that provides a standardized means of persisting solution data.
  • At the document level you can store XML data using the
  • SolutionXML
  • element contained immediately within the
  • VisioDocument
  • element. You can manipulate the document-level XML data in your solution at run time through Automation.
  • At the cell level, you can store well-formed XML data in selected cells using a string value within a
  • SolutionXML
  • element. When you work with XML data in cells through the ShapeSheet spreadsheet or Automation, you can retrieve your XML data as you would any string value in a cell.

It is recommended that you supply a user namespace and prefix all non-Visio elements with the explicit namespace.

Unknown XML is XML that Visio does not understand. If it is well-formed XML, and an immediate child of one of the following elements—VisioDocument, DocumentSheet, PageSheet, Shape, or StyleSheet—the data is stored and round-tripped with the file.

The following is an example of unknown XML stored in the PageSheet element:

  <PageSheet ID='0' xmlns:x='myXML'>
<x:myXML>
...
</x:myXML>
</PageSheet>

If unknown XML is found in any other location in the file, it is discarded and a warning message is logged to the log file. For information about the log file, see Error and warning messages.

Visio also round-trips any foreign attributes found on any of the previously mentioned elements.

All XML for Visio files must create XML for Visio elements in the default namespace. To instruct Visio to validate a VDX file against the Visio schema, you should declare the default namespace as xmlns='x-schema:your visio-path\visio-schema.xdr'.

If you add unknown XML to a VDX file, the new elements should be prefixed with an explicit namespace. Any non-XML for Visio elements must be placed within their own non-default namespace. To be a valid XML file, any namespace prefix must be declared. If you don't prefix unknown XML in its own namespace, it is likely that the VDX file will fail to validate.

Solution XML data can be stored at the document level using the SolutionXML element as an immediate child of the VisioDocument element. A VisioDocument element can have zero or more SolutionXML elements, each with the Name attribute, which is a string that is unique among the SolutionXML elements in the file.

For example:

  <VisioDocument>
...
<SolutionXML Name='SomeName' xmlns:mysol='sol'>
<mysol:myXML> value </mysol:myXML>
</SolutionXML>
...
</VisioDocument>

When you add a SolutionXML element to a Visio document, it is recommended that you use a namespace to mark non-Visio elements.

Immediate children of the VisioDocument element must occur in the order specified by the schema (and reflected in this document's tag hierarchy). If your SolutionXML element is in the wrong order, it is ignored and a warning message is logged to the log file.

To access the SolutionXML element in a document at run time, you can use the SolutionXMLElement, SolutionXMLElementCount, SolutionXMLElementExists, and SolutionXMLElementName properties and the DeleteSolutionXMLElement method.

For example, you can create SolutionXML elements through Automation using code similar to the following:

docObj.SolutionXMLElement("SomeName") = _
    "<SolutionXML Name='SomeName' xmlns:mysol='sol'> _
        <mysol:myXML> value </mysol:myXML></SolutionXML>"

A developer can store solution XML at the cell level within a SolutionXML element as a child of one of the following elements—the A, B, C, and D elements contained in a Scratch element, or the Value element contained in a User or Prop element.

Unlike document-level XML, SolutionXML elements maintained in a cell do not require a Name attribute. (In a cell, there are no uniqueness semantics for SolutionXML elements that use a Name attribute.) However, we recommend that you supply a namespace to mark non-Visio elements within a SolutionXML element in a cell.

SolutionXML data in a cell element is simply a string value that happens to be a chunk of valid XML. The Visio engine recognizes that the string is XML and stores the string in an unparsed form. The engine recognizes the element as a SolutionXML element if the string value begins with <SolutionXML>.

There are several legal ways that you can create a formula using the SolutionXML element. A cell can have a formula that matches one of the patterns shown here:

  <SolutionXML> well-formed XML </SolutionXML>
<SolutionXML well-formed XML > well-formed XML </SolutionXML>
<SolutionXML well-formed XML />

For example:

"<SolutionXML xmlns:x='y'>
<x:MyData>Data</x:MyData></SolutionXML>"

or

"<SolutionXML xmlns:x='y' x:MyData='Data'/>"

The following example shows a Scratch element containing SolutionXML stored in the A element:

  <Scratch>
<A Unit='STR'>
<SolutionXML xmlns:mycellsol='mycellsol'>
<mycellsol:myelement> value </ mycellsol:myelement>
</SolutionXML>
</A>
</Scratch>

If a cell contains XML, but it is not contained within a SolutionXML element, or if the XML is not well-formed, Visio outputs a string value with entity references:

  <Scratch>
<A Unit='STR'>
&lt;MyXML&gt;&lt;Data&gt;ABC&lt;/Data&gt;&lt;/MyXML&gt;
</A>
</Scratch>

Visio treats cells with SolutionXML elements differently from other cells only when a document is saved in XML for Visio file format. When you work with XML data in cells through the ShapeSheet spreadsheet or Automation, you can store and retrieve your XML data as you would any string value in a cell.