Show All

# Embedding Custom XML in a DatadiagramML File

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

You can embed custom XML in a DatadiagramML file in two ways:

- As unknown XML, which is XML that Visio does not understand, but will round-trip with a DatadiagramML 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 by using the SolutionXML element 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.

It is recommended that you supply a user namespace and 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 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.

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

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

Validation on Save

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.

Caution Incorrectly editing the registry may severely damage your operating system, requiring you to reinstall it. Microsoft cannot guarantee that problems resulting from editing the registry incorrectly can be resolved. Before editing the registry, back up any valuable data. For the most recent information about using and protecting your computer's registry, see Microsoft Windows Help.
©2003-2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp