Embedding Custom XML in a DatadiagramML File

  • Article

You can include custom XML data that is specific to your solution within your DatadiagramML file, provided that the data contains well-formed XML that complies with the DatadiagramML schema and the internal rules of Microsoft® Visio®.

There are two ways that you can embed custom XML in a DatadiagramML file:

  • As unknown XML, which is XML that Visio does not understand, but can round-trip with a DatadiagramML file when the XML is contained in particular elements. Visio uses this method to round-trip documents between Visio 2010 and older versions of Visio (specifically, Microsoft Office Visio 2003 and Microsoft Office Visio 2007).

  • As solution XML, which is well-formed XML that is contained within a SolutionXML element that provides a standardized way to persist solution data.At the document level, you can store XML data by using the SolutionXML element that is contained immediately within the VisioDocument element. You can manipulate the document-level XML data in your solution at run time by using Automation.

    At the cell level, you can store well-formed XML data in selected cells by using a string value within a SolutionXML element. When you work with XML data in cells in the ShapeSheet spreadsheet or by using Automation, you can retrieve your XML data as you would any string value in a cell.

    We recommend that you supply a user namespace and that you prefix all non-Visio elements with the explicit namespace.

Unknown XML

Unknown XML is XML that Visio does not understand. If it is well-formed XML, and if it is 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 more information about the log file, see Error and Warning Messages.

Visio also round-trips any foreign attributes that it finds on any of the previously mentioned elements.

All DatadiagramML files must create DatadiagramML elements in the default namespace. To instruct Visio to validate a VDX file against the Visio schema, declare the following as the default namespace.

xmlns="https://schemas.microsoft.com/office/visio/2010/extension"

If you add unknown XML to a VDX file, prefix the new elements with an explicit namespace. Any non-DatadiagramML elements must be placed within their own non-default namespace. To make sure that your files are valid XML files, you must declare any namespace prefixes that the file contains. If you do not prefix unknown XML in its own namespace, it is likely that the VDX file will not validate.

Solution XML stored with a document

You can store Solution XML data at the document level by 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, we recommend that you use a namespace to mark non-Visio elements.

Immediate children of the VisioDocument element must occur in the order that is specified by the schema (and reflected in the 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 use Automation to create SolutionXML elements by writing code similar to the following.

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

Solution XML stored in a cell

You 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 that are 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. Visio recognizes that the string is XML and stores the string in an unparsed form. Visio recognizes the element as a SolutionXML element if the string value begins with the following.

<SolutionXML>

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

<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 that contains 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 the XML is not contained within a SolutionXML element or if the XML is not well-formed, Visio outputs a string value with entity references similar to the following.

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

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

Validation on Save

Beginning with Microsoft Office Visio 2003, you can test the validity of changes that you make to SolutionXML elements in a VDX file without having to reload the file in Visio by turning on the XMLValidateOnSave registry key. This key is not present by default, so you must create it before you can turn it on. To create and enable the key, use the following procedure.

  1. Open the registry editor and navigate to the following location.

    HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Visio\Application\

  2. In the folder list, right-click the Application folder, point to New, and then click String Value.

  3. Name the key XMLValidateOnSave.

  4. Right-click the key and click Modify.

  5. In the Value data box, type "1", and then click OK.

  6. Close the registry editor.

Warning

Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall the operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.