10 tips for developers working with the Visio VSDX file format

The new Visio introduces a new XML-based file format, VSDX. In a previous post, we provided an overview of the new file format. One benefit of the new file format is its interoperability: it is now much easier to work with the default file format outside of Visio. In this post, we provide some tips for working with the new file format programmatically.

Overview

Even in the short time since releasing the new Visio, we have written a number of documents, articles and blog posts on the new file format. The goal of this post is to provide a small, but diverse, collection of information that might otherwise be buried in these longer articles. These tips are all based on questions we’ve received from early file format developers and, in some cases, represent places where they went awry when working with the VSDX file format.

Tip #1: Finding documentation on the new file format

Most of the developer documentation produced by the Visio team can be found here:

http://msdn.microsoft.com/en-us/library/office/fp161226(v=office.15).aspx

If you are programmatically working with the file format, you will probably be most interested in the following content:

• Introduction to the Visio 2013 file format (.vsdx)
• How to: Manipulate the Visio 2013 file format programmatically
• Visio 2013 File Format reference

We also produced a specification of how the file format interacts with Visio Services on SharePoint:

• [MS-VSDX]: Visio Graphics Service VSDX File Format

In addition, the following blog posts might be helpful:

• VSDX: the new Visio file format
• What IT Pros need to know about the new VSDX file format in Visio 2013

Tip #2: Viewing the VSDX file outside Visio

Before you start creating your own VSDX files, take a look at some VSDX files generated from Visio. There are a number of ways to do this:

• Change the extension of a VSDX file to ZIP and then open the file using Windows File Explorer or another ZIP utility. From Windows, double-click on the ZIP file to see its contents.
• Use the Open XML Package Editor Power Tool for Visual Studio 2010 to open the VSDX file. This is a cool tool that lets you parse and edit Open Packaging Conventions files. Unfortunately, the tool only works with Visual Studio 2010 and only recognizes the following extensions: XPS, PPTX, XLSX and DOCX. This means you need to change the extension of your VSDX file to one of the above before using the tool.
• Use the pkgVisio - Visio 2013 (beta) XML manipulation tool created by one of our Visio MVPs, Al Edlund.

The image to the right shows a VSDX file open the Open XML Package Editor Power Tool for Visual Studio 2010.

The Visio file format uses a ZIP archive package as defined by the Open Packaging Conventions standard (ISO/IEC 29500-2:2008), so many other applications that read the ZIP format can also be used to view VSDX files.

Tip #3: Editing VSDX programmatically

Developers familiar with editing Office files programmatically often turn to the Office Open XML SDK to attempt to edit VSDX files. This will not work.

The Open XML SDK is designed specifically for file formats that use the Office Open XML File Formats (the ECMA-376, Second Edition and ISO/IEC 29500 standards). The XML in the new Visio file format is not defined by this standard.

It’s not that hard, however, to work with the Visio file format, since it is based on two known concepts: the ZIP package and XML contents.

The MSDN help topic “How to: Manipulate the Visio 2013 file format programmatically” provides an excellent overview to working with Visio files programmatically using System.IO.Packaging and XDocument.

Tip #4: Debugging your files in Visio

If you create a tool for modifying or creating Visio files outside of Visio, you should test opening these files in Visio to ensure that the files open correctly.

Visio generates warnings to indicate potential XML issues when a file opens but, by default, Visio does not show warnings in the user interface. We wanted to optimize for end-users and we know that they do not want to see log files with XML warnings: we heard from these users that the warnings are confusing and they cannot do anything about them but worry.

If you are a file format developer, however, you probably want these warnings turned on. To change this setting, click File, then Options, then Advanced and then Show file open warnings under the Save/Open heading.

Tip #5: Triggering recalculation of the file

When Visio opens a VSDX file, it does not recalculate any ShapeSheet cells or redo routing. If you make changes within Visio, using either the user interface or the API, Visio will recalculate dependent properties immediately. When you save the file, all the properties will be consistent with each other and they will remain correct when loaded again.

If you change a shape property directly in the file XML, however, none of the properties that depend on this change will update automatically when Visio loads the file. This will likely cause inconsistencies in how the diagram looks or behaves.

There are two ways to trigger recalculation when you update something directly in the file.

1. When you update the value or formula for a ShapeSheet cell in the file format, use a processing instruction to indicate to Visio that the ShapeSheet cell was updated outside of Visio. A processing instruction will increase load time but only slightly.
2. When you want to make more significant changes to the file, use the RecalcDocument flag in the \docProps\custom.xml part. This will cause a complete recalculation, similar to the load behavior from VDX, but will also significantly slow down load. Once the file has been recalculated and loaded, the next save will remove the RecalcDocument flag from the document. This will limit the performance hit to a single file load.

An example of the custom.xml part with RecalcDocument flag is shown below.

These techniques are both described in How to: Manipulate the Visio 2013 file format programmatically.

Tip #6: Adding custom data to the VSDX file

Anyone can add custom data to a VSDX file by using a custom part. This is particularly useful if you have a tool external to Visio that reads and writes to the VSDX format, but needs to store additional information related to the tool’s feature set.

To have Visio preserve your custom part and save it back to the file, you need to ensure that there is a proper path via relationships to your part. Package relationships specify how the collection of document parts come together to form a document. Visio loads VSDX files by navigating through the structured defined by the relationship parts (.rels parts).

The easiest way to ensure that your custom part will be preserved is to store a relationship targeting your custom part in the /_rels/.rels part. The /_rels/.rels part stores the relationships for the package as a whole and is the first part read by Visio. If stored here, your relationship is a package-level relationship, and you will not have to worry about any of the deeper complexities around correctly ensuring that there is a path from a package-level relationship to your custom part.

Tip #7: The difference between VSDX, VSDM, VSSX, VSDM, VSTX and VSTM

In Visio 2010, there were three main file types: drawings (.VSD), templates (.VST) and stencils (.VSS). There are still three main file types in the new format, but we now offer macro-free and macro-enabled formats for each. The extension for each format is listed below.

With the VSD, VST and VSS formats, you can change between file types simply by changing the file extension. With the new file formats, this does not work. In addition to changing the file extensions, you also have to ensure that the ContentType of the /visio/document.xml part in the \[Content_Types].xml part matches the file extension.

Here are the correct ContentTypes for each of the new file extensions.

Tip #8: Content types

Each document part has a specific content type. The content type of a part describes the contents of that file type. The [Content_Types].xml part, at the root of the package, lists the ContentType for different parts in the file.

A typical content type begins with the word “application” and is followed by the vendor name. In the content type, the word “vendor” is abbreviated to vnd. All content types that are specific to Visio begin with application/vnd.ms-visio. If a content type is an XML file, then the ContentType ends with +xml. Other non-XML content types, such as images, do not follow this convention.

This section contains a list of the most frequently encountered content types and examples of their associated parts. The list below is pulled from the [Content_Types].xml part of a VSDM Visio file: we used the macro-enabled drawing format for this example, since it allowed us to include macros in the file and in the list below.

<Default Extension="bin" ContentType="application/vnd.ms-office.activeX"/>

<Default Extension="emf" ContentType="image/x-emf"/>

<Default Extension="jpeg" ContentType="image/jpeg"/>

<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>

<Default Extension="xml" ContentType="application/xml"/>

<Default Extension="docx" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document"/>

<Override PartName="/visio/document.xml" ContentType="application/vnd.ms-visio.drawing.macroEnabled.main+xml"/>

<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>

<Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/>

<Override PartName="/docProps/custom.xml" ContentType="application/vnd.openxmlformats-officedocument.custom-properties+xml"/>

<Override PartName="/visio/masters/masters.xml" ContentType="application/vnd.ms-visio.masters+xml"/>

<Override PartName="/visio/masters/master1.xml" ContentType="application/vnd.ms-visio.master+xml"/>

<Override PartName="/visio/pages/pages.xml" ContentType="application/vnd.ms-visio.pages+xml"/>

<Override PartName="/visio/pages/page1.xml" ContentType="application/vnd.ms-visio.page+xml"/>

<Override PartName="/visio/embeddings/oleObject1.bin" ContentType="application/vnd.openxmlformats-officedocument.oleObject"/>

<Override PartName="/visio/windows.xml" ContentType="application/vnd.ms-visio.windows+xml"/>

<Override PartName="/visio/vbaProject.bin" ContentType="application/vnd.ms-office.vbaProject"/>

<Override PartName="/visio/vbaProjectSignature.bin" ContentType="application/vnd.ms-office.vbaProjectSignature"/>

<Override PartName="/visio/data/connections.xml" ContentType="application/vnd.ms-visio.connections+xml"/>

<Override PartName="/visio/data/recordsets.xml" ContentType="application/vnd.ms-visio.recordsets+xml"/>

<Override PartName="/visio/data/recordset1.xml" ContentType="application/vnd.ms-visio.recordset+xml"/>

<Override PartName="/visio/validation.xml" ContentType="application/vnd.ms-visio.validation+xml"/>

<Override PartName="/visio/comments.xml" ContentType="application/vnd.ms-visio.comments+xml"/>

<Override PartName="/visio/solutions/solutions.xml" ContentType="application/vnd.ms-visio.solutions+xml"/>

<Override PartName="/visio/solutions/solution1.xml" ContentType="application/vnd.ms-visio.solution+xml"/>

<Override PartName="/visio/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>

Tip #9: Multi-threaded load and using Triggers

Visio uses multi-threaded load to open VSDX files. The active page and all dependent pages are considered necessary and are fully loaded before the user can work with the document.

If you are working in Visio using either the user interface or the API, you will not be adversely affected by multi-threaded load. Visio will ensure that the information you need is loaded before you access it. There is one caveat for solutions that query properties across multiple pages on load, such as a solution that builds a data model of the document on load: any page you access via the API will be loaded, so if you access all pages in document open, you may notice a performance hit for large, multi-page diagrams.

If you edit a file outside of Visio and add new ShapeSheet functions, you should be aware of Trigger elements. Visio uses Trigger elements to help calculate dependent pages on load. A trigger indicates that a particular ShapeSheet function is present in another (probably not-yet-loaded) part and that this other part needs to be loaded.

For example, consider a diagram where a shape displays the creation date of the document. To get this behavior, we use the DOCCREATION() ShapeSheet function.

This function is listed in the Trigger elements topic as a function that uses a trigger, RecalcCreateDT. As a result, the DocumentSheet, stored in the \visio\document.xml part needs this trigger to correctly identify this dependency on file load.

If you add ShapeSheet functions directly to the Visio file format and your functions depend on properties stored in other parts, you will likely need to add corresponding Trigger elements to ensure that these dependencies are discovered by Visio.

Tip #10: Fallback images for Objects and ActiveX Controls

Suppose your Visio file contains an ActiveX control or Object, such as the ones found in the Insert Object dialog accessible via the Object button on the Insert tab. Along with the ActiveX control or object part, Visio also writes out a corresponding .rels files and an image version of control/object. We call this the fallback image.

For example, the part \visio\embeddings\oleObject1.bin would have a corresponding \visio\embeddings\_rels\oleObject1.bin.rels part, which links to an image in the \visio\media path.

For developers, fallback images have the following implications:

1. If you don’t want to open a binary object or control part in your tool, you can use the fallback image in the file to display the contents of the binary part.
2. If you add an object or control directly to the file, you will have to decide whether you want to include a fallback image as well. Visio Services and third-party applications may not render your object or control unless a fallback image is present.
3. If you modify an object or control, or a corresponding fallback image, directly from the file, you should make sure that the two parts stay in sync.

Conclusion

Since the release of our new file format, we have heard from many excited developers. There are many opportunities to work directly with the new file format. Common reasons to work directly with the Visio file include data extraction, file manipulation when Visio is not available, and information storage and retrieval by another tool or application.

Of course, if the Visio API suits your needs, we still recommend that you work with Visio files via the API. This eliminates a lot of complexity, because Visio does the background work to ensure that your file stays in a consistent and correct state.

For those that want to work directly with the file format, we hope this list of tips makes it easier to get started with your development project. Each tip was purposely short, but we hope that the information above gives you the necessary details to decide if a tip applies to you and to investigate if it does.

If you have other tips, or run into problems working with the file format, feel free to post a comment below!