Embedding Custom XML in a DatadiagramML File

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 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 DatadiagramML files must create DatadiagramML 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="http://schemas.microsoft.com/visio/2003/core".

If you add unknown XML to a VDX file, the new elements should be prefixed 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 the file contains. If you don't prefix unknown XML in its own namespace, it is likely that the VDX file will fail to be validated.

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, 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 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>"

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 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 <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 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 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:

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

Beginning with Microsoft Office Visio 2003, you can test the validity of changes 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 will need to create it before you can turn it on. To create and enable the key, follow this procedure:

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

   HKEY_CURRENT_USER\Software\Microsoft\Office\11.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.