Using the Visual Studio Tools for Office Application Manifest Editor

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

J. Jason De Lorme, Simplesheet, Inc.

Revised: November 2005

Applies to: Microsoft Visual Studio 2005, Microsoft Visual Studio 2005 Tools for the Microsoft Office System, Microsoft Office Professional Edition 2003

Summary: Learn about the application manifest and the process of building the Application Manifest Editor Sample that ships as a sample with Visual Studio 2005 Tools for Office. This article also describes common deployment scenarios supported by this tool. (22 printed pages)

Contents

• Introduction to the Application Manifest Editor

• Walking Through the Application Manifest Editor Tool

• Debugging the Application Manifest

• Inspecting Cached Datasets

• Tracking Edits Made Using the Application Manifest Editor

• Command-Line Options for the Application Manifest Editor

• How the Application Manifest Editor Uses ServerDocument

• Code Security Issues to Consider

• Conclusion

• Additional Resources

Introduction to the Application Manifest Editor

The Application Manifest Editor sample tool enables you to view and modify the application manifest and cached datasets stored in a document created using Microsoft Visual Studio 2005 Tools for the Microsoft Office System (Visual Studio 2005 Tools for Office). The setup program installs source code for the tool, which was developed using Microsoft Visual C. Visual Studio 2005 Tools for Office enables you to build Microsoft Office Word 2003 or Microsoft Office Excel 2003 solutions in C or Microsoft Visual Basic, using the complete Microsoft .NET Framework. When developing with Visual Studio 2005 Tools for Office, your solution code is compiled into an assembly containing intermediate language (IL) and metadata that gets stored on your development computer as a DLL. Application information, or the application manifest, is metadata embedded in a Visual Studio 2005 Tools for Office document that contains information used by the Visual Studio 2005 Tools for Office runtime to locate and execute your application solution.

The application manifest format is extensible and may be used in future versions to contain design-time information as well. In its current state, it contains two logical sections: one for manifest information and another for cached data. Visual Studio 2005 Tools for Office enables you to program directly against datasets cached in a document without having to use the object model of Word or Excel. Cached datasets are serialized into structured storage of the documents and are identified through the CachedData section of the application manifest.

Application Manifest Editor Overview

The application manifest is serialized into structured storage in the document and is not directly editable using simply a text editor. Visual Studio 2005 Tools for Office provides the ServerDocument class to access the application manifest. The Application Manifest Editor is a sample tool that uses the ServerDocument class to inspect and modify the embedded application manifest of a document. It also provides a simple command-line interface to support rudimentary scripting scenarios.

Setup Requirements for the Application Manifest Editor

To use the Application Manifest Editor, you must have Microsoft Visual Studio 2005 Tools for the Microsoft Office System installed.

Walking Through the Application Manifest Editor Tool

To help you become more familiar with the application manifest, we walk through the process of creating a Visual Studio 2005 Tools for Office document and examining it using the Application Manifest Editor. Then, we'll review common usage scenarios that illustrate the functionality of the Application Manifest Editor.

Creating the Document

To start, open Visual Studio 2005 Tools for Office and create a Word or Excel project. Figure 1 shows the New Project Wizard including a project node called "Office." I set up my Visual Studio profile as a Visual C developer, so my options may look a little different from yours depending on how you configure your environment. All samples in this article use C, but you can also use Microsoft Visual Basic to build your solutions if you choose.

Figure 1. New Project Wizard

To create the solution, follow these steps:

1. Select Visual C and expand the tree.

2. Select Office from the tree view.

3. Select Excel Workbook from the tree pane.

4. Change the name of the application to Application Manifest Sample and click OK.

5. In the next dialog box, select Create a new document and click OK.

Visual Studio 2005 Tools for Office creates an Excel workbook and a few C classes that represent the workbook and each of its worksheets. Notice that when the solution is created, Visual Studio displays Sheet1 of your new Excel workbook, hosted inside the Visual Studio designer. I am not going to get into the specifics of building an Excel application here; there are already some great articles on MSDN that focus on Visual Studio Tools for Office solution development. For more information, see Visual Studio Tools for Office Developer Portal on the Microsoft Office Developer Center on MSDN. For the purpose of the Application Manifest Editor tool, I am just going to add the canonical "Hello World" dialog box to Sheet1.

To jump to the code, you can press F7 or right–click Sheet1 in the Solution Explorer and then select View Code. Listed below is the code that was generated by Visual Studio 2005 Tools for Office when it created the solution. I added the "Hello World" code in bold.

    public partial class Sheet1
    {
        private void Sheet1_Initialize(object sender, System.EventArgs e)
        {

        }

        private void Sheet1_Shutdown(object sender, System.EventArgs e)
        {
        }

        region VSTO Designer generated code

        private void Startup()
        {
            this.Initialize += new System.EventHandler(Sheet1_Initialize);
            this.Shutdown += new System.EventHandler(Sheet1_Shutdown);
        }

        endregion

    }

If you compile and run this code (by pressing F5), you should see Excel load and your message box as displayed in Figure 2:

Figure 2. Hello World dialog box in Excel

Examining the Output

Close Excel and open Microsoft Windows Explorer to see the files generated by Visual Studio Tools for Office. If you chose the defaults in the New Project wizard, your files are probably in a directory such as C:\Documents and Settings\[your username]\My Documents\Visual Studio\Projects\Application Manifest Sample\Application Manifest Sample. Examine the bin\debug directory and you should see the files shown in Figure 3.

Figure 3. Files generated by Visual Studio

Notice that there is an assembly with the name of your solution (Application Manifest Sample.dll), as well as the document itself, in this directory. The .pdb file is a program database file that is only used for debugging. When you compile a Visual Studio 2005 Tools for Office solution, Visual Studio makes a copy of your document in the output directory and automatically adds the necessary application manifest entries to enable the solution to run.

If you double-click the document in this directory, your solution loads again and the Hello World message box appears. Close Excel and browse up two directory levels in Windows Explorer to see another copy of Application Manifest Sample.xls. Double-click this file and notice that your empty workbook loads, but no dialog box appears. This copy of the document does not have any application manifest entries that indicate how to load the associated code.

Move down to the bin\debug directory. To demonstrate how the Visual Studio 2005 Tools for Office runtime uses the application manifest, copy only the file, Application Manifest Sample.xls, from the bin\debug directory to the desktop of your computer. Once you copy the file, double-click the desktop copy. The Visual Studio 2005 Tools for Office runtime examines the application manifest and attempts to load the assembly, Application Manifest Sample.dll. However it cannot find it and the error appears, as shown in Figure 4.

Figure 4. Assembly loading error message

If you click the Details button in the exception dialog box, you can examine the stack trace and see that the solution failed to load due to a "FileNotFoundException" error when looking for the Application Manifest Sample.dll. To begin debugging this error, you need to examine the application manifest of the document. Unlike normal document properties that are visible by right-clicking the file, the application manifest is embedded deep within the document and you must use a special API in order to access it. Visual Studio 2005 Tools for Office provides a class called the ServerDocument, which is examined later in more detail.

Editing the Application Manifest

If you have not already installed the Application Manifest Editor Sample, do so now. This installs the Application Manifest Editor project onto your computer. Once you install the project, follow these steps to compile it. In the last step, open the Application Manifest Sample.xls workbook with the Application Manifest Editor tool:

1. Open the sample project.

   By default, the ApplicationManifestEditor project installs to the following directory:

   C:\Documents and Settings\user_name\My Documents\Visual Studio 2005\Projects\CS\ApplicationManifestEditor
   

2. In Visual Studio, open the solution file ApplicationManifestEditor.sln, and then press F5 to build and run the solution.

3. From the Application Manifest Editor File menu, click Open.

4. In the File Open dialog box, select Desktop.

5. Select Application Manifest Sample.xls and then click Open.

Figure 5. Application Manifest Sample.xls opened using the Application Manifest Editor tool

The application manifest that appears for your document, shown in Figure 5, contains information about the application, the customization assembly, and the entry points. For an Excel workbook, you will see entry points for each worksheet and one for the workbook. A Word document contains a single entry point for the document.

When you attempt to open your desktop copy of the workbook, the error you receive indicates that the runtime could not find the "Application Manifest Sample" assembly. If you examine the AssemblyPath, you find that Application Manifest Sample.dll is the assembly for which it was looking.

Figure 6. Customization assembly information in the property grid

The Visual Studio 2005 Tools for Office runtime uses a relative path to the document to load these assemblies. When the document was located in the same directory as the assembly it loaded just fine, however when you moved the document, the runtime could no longer locate the assembly. To fix this, update the AssemblyPath attribute shown in Figure 6 to the proper location of the assembly. On my computer, this directory is as follows:

C:\Documents and Settings\jason\My Documents\Visual Studio 2005\Projects\Application Manifest Sample
\Application Manifest Sample\bin\Debug\Application Manifest Sample.dll

You can update the AssemblyPath attribute with either an absolute path as shown in the previous example, or by using a relative path. For clarity, I used the absolute path.

After you update the path, click somewhere else in the property grid and then, on the File menu of the Application Manifest Editor, click Save. After saving the document, close the Application Manifest Editor before trying to open the document. Until you close the editor, it holds a lock on the file. Double-click the Application Manifest Sample.xls file on your desktop. You should again see the "Hello World" message box. If you receive an error when you try to open the document, repeat the previous steps and confirm that you typed the correct path.

Close the workbook and quit Excel. Now, remove the customization from the workbook so that no code is executed when the workbook is opened in Excel:

1. Return to the ApplicationManifestEditor solution in Visual Studio, and then run the solution.

2. In the File Open dialog box, select Desktop.

3. Select Application Manifest Sample.xls, and then click Open.

4. On the Edit menu, click Remove Customization.

5. On the File menu, click Save, and then quit the Application Manifest Editor.

Once again, double-click the file, Application Manifest Sample.xls on your desktop. This time, no code is executed when the workbook opens in Excel. In other words, you do not receive the "Hello World" message box as you did before, and you do not receive the error. In this case, because no code is expected to run, no error is reported.

Debugging the Application Manifest

Debugging is one of the most common usage scenarios for the Application Manifest Editor. At design time, Visual Studio 2005 Tools for Office updates entry points and dependencies in the application manifest for you. However, throughout the development life cycle you may move code or make changes to dependencies and inevitably end up with an error somewhere along the way. As a first step in debugging a traditional .NET-based application you may be familiar with running the Intermediate Language Disassembler (ILDASM), looking at dependencies, version numbers and so on, until you discover what changed or moved. The walkthrough presented earlier in this article demonstrated using the Application Manifest Editor to debug. If you find yourself updating solutions because you update dependencies or move assemblies around outside of the Visual Studio design-time environment, you will find this tool helpful.

Inspecting Cached Datasets

Because Visual Studio Tools 2005 for Office enables programmatic access to the data embedded in the document, an Office document can function as a repository for data. Because you can now separate the data from the view, code on a server (for example, in an ASP.NET page) can view and manipulate the data in a document without launching Office or using the native Office object model to instantiate the application. Figure 7 shows an example of a cached dataset embedded in an Excel document that is editable with the Application Manifest Editor.

Figure 7. CachedDataSet view

Add a Cached DataSet to Your Workbook

1. In Visual Studio 2005, open the Application Manifest Sample solution you previously created.

2. If Sheet1 is not already in design view, right-click Sheet1.cs in Solution Explorer and select View Designer.

3. Add a data source to the solution:

   • On the Data menu, click Add New Data Source.

   • Select Database as your data source type, and then click Next.

   • Click New Connection to add a new connection for the SQL Server Northwind sample database, and then click Next.

   • Click Next to save your connection string in the application configuration file.

   • Select only the Customers table, and then click Finish.

     This will add a new dataset named NorthwindDataset to your project.

4. Drag Customers from the Data Sources pane and drop it onto Sheet1.

   Note: This will create a new list object bound to the Customers table on the worksheet. To handle the binding, you will now see a dataset, table adapter, and binding source in the component tray.

5. In the component tray, select northwindDataSet.

6. In the Properties window, change the Modifiers property to Public and the CacheInDocument property to True.

7. Press F5 to run.

   When the workbook opens in Excel, the list object is filled with data from the Northwind Customers table. For the data to be cached into the workbook, you must save the workbook.

8. Save the workbook onto your desktop to replace your previous desktop version of Application Manifest Sample.xls, and then quit Excel.

Examining the Data Cache with the Application Manifest Editor

Now let's examine the cached data using the Application Manifest Editor:

1. Return to the ApplicationManifestEditor solution in Visual Studio 2005, and then run the solution.

2. In the File Open dialog box, select Desktop.

3. Select Application Manifest Sample.xls, and then click Open.

4. Click the Cached Data tab.

To change data within an embedded cached dataset, simply type in the grid as shown in Figure 7. You can change cell data values, remove rows, and add rows of data. To save the changes to the document, on the File menu, click Save.

Tracking Edits Made Using the Application Manifest Editor

The Application Manifest Editor maintains a dirty state flag for each open document and, similar to most Microsoft Windows applications, displays an asterisk in the title bar, as shown in Figure 8, if there are any unsaved changes. Application manifest changes do not persist to the underlying document until you save your changes.

Figure 8. Unsaved edits indicator

As with other standard Windows applications, if any unsaved changes exist when you close the document or exit the application, you are prompted to save changes or discard changes. Clicking Cancel returns you to the application without saving or closing the document.

Command-Line Options for the Application Manifest Editor

As you have seen, the Application Manifest Editor Windows GUI application allows you to interact visually with the application manifest. The command line interface allows you to perform most of the same update operations, including regular expression find and replace on multiple documents, but does not allow you to view property values.

Usage: VSTOApplicationManifestEditor Filename Option

Filename: Wildcards can be used to select multiple files. Supported file
types are: *.doc; *.dot; *.xls; *.xlt; *.manifest

Options: Only one option can be specified. Options marked with a *
require opening the document and should not be performed in a server
setting.

  /X    * Removes the application manifest and cached data from the file
        using the RemoveCustomization method.

  /R    Removes the application manifest in the file by overwriting it 
        with blank data.

  /M ManifestFile
        Adds an application manifest or overwrites the existing manifest 
        using ManifestFile.

  /A AssemblyFile
        * Attaches the specified customization assembly to the document 
        using the AddCustomization method.

  /S    Extracts and saves the application manifest to Filename.manifest.
        If Filename.manifest already exists, no action will occur.

  /SF   Extracts and saves the application manifest to Filename.manifest.
        If Filename.manifest already exists, it will be overwritten.

  /D    Removes all cached data from the file without compressing.

  /C    * Compress the data island in the file.

  /DC   * Removes all cached data from the file and compresses the data 
        island.

  /SR  FieldName SearchString ReplaceString
        Performs a search and replace operation in the specified field.
        Valid FieldName values are:
            All, ManifestName, ManifestVersion, DeploymentManifest,
            AssemblyName, AssemblyVersion, AssemblyPath, PublicKeyToken
        SearchString can be a regular expression.

To test the command line interface, let's remove the cached data in our Application Manifest Sample.xls file, and then compress the data island. Remember to replace the paths in these steps with the locations where you have the VSTOApplicationManifestEditor.exe and Application Manifest Sample.xls files on your computer.

1. On the Start menu, click Run.

2. Type cmd.exe, and then press the ENTER key.

   A command window appears.

3. Change to the bin\debug folder for the Application Manifest Editor solution:

   cd C:\Documents and Settings\user\My Documents\Visual Studio 2005\Projects\CS\ApplicationManifestEditor\bin\Debug
   

4. Execute the command to clear and compress the data cache:

   VSTOApplicationManifestEditor.exe "C:\Documents and Settings\user\Desktop\Application Manifest Sample.xls" /DC
   

5. Start the GUI for the Application Manifest editor, and then open the desktop copy of Application Manifest Sample.xls.

   You will notice that there is no longer a Cached Data tab because the data was removed.

How the Application Manifest Editor Uses ServerDocument

In addition to being a great tool, the Application Manifest Editor also acts as a learning tool because it shows you how to programmatically read and modify the application manifest using the ServerDocument class.

Loading a Document with ServerDocument

When you select a file to open in the Application Manifest Editor, you are executing the openDocument function in ApplicationManifestEditor.cs:

private void openDocument(String fileName)
{
    // Save the path to the document. It will be
    // used regardless of whether this is a
    // customized document or not.
    documentPath = fileName;

    if (ServerDocument.IsCustomized(documentPath))
    {
        // The document is customized. Create a ServerDocument
        // instance for it and store the manifest in a manifest
        // wrapper.
        document = new ServerDocument(documentPath);
        manifest = new AppManifestWrapper(document);

In the openDocument function, you simply create a new instance of a ServerDocument object, and then pass the full path to the workbook or document in the constructor. Prior to initiating the new ServerDocument object, you can use the IsCustomized property to determine if the workbook or document has a customization.

The openDocument function also checks to see if the document's data cache contains any items by examining the count of HostItems. If the count is less than zero, then it correctly assumes that there is no cached data and therefore will not display the Cached Data tab on the Windows Form.

if ()
{
    // The document contains cached data, so show
    // the cached data editor and fill it with the
    // current data values.
    showCachedDataPage();
    fillTreeView();

Saving a Document with ServerDocument

After making changes to the application manifest, saving your changes is as simple as calling the Save method on your ServerDocument instance. This is illustrated in the saveDocument function in ApplicationManifestEditor.cs:

private void saveDocument()
{
    System.Diagnostics.Debug.Assert(document != null);

    if (IsDirty)
    {
        if (document.CachedData.HostItems.Count > 0)
            saveTreeViewDataItems(cachedDataTreeView.Nodes);
        document.Save();

        IsDirty = false;
    }
}

Code Security Issues to Consider

The Application Manifest Editor sample is intended for instructional purposes, and should not be used in deployed solutions without modifications. In particular, code security must be taken into consideration.

To illustrate the simplicity of this sample solution, a list of potential threats are identified using the threat modeling process and tools described in Threat Modeling in the Microsoft Security Developer Center.

The following are some examples of the identified threats that you should take into consideration before expanding or deploying this solution.

Table 1. Example of security threats

Threat effect	Entry point	Known mitigation
The Office document's data cache is invalid or has been compromised.	Open Document	Only users with read/write access to a document can change the data cache using the Application Manifest Editor.
The Office document's application manifest points to an invalid assembly.	Open Document	Only users with read/write access to a document can change the application manifest using the Application Manifest Editor.
The customization has been removed from the Office document.	Open Document	Only users with read/write access to a document can change the application manifest using the Application Manifest Editor.

For more information about code security, see the Microsoft Security Developer Center.

Conclusion

The Application Manifest Editor tool helps you debug your Visual Studio 2005 Tools for Office solutions during development and facilitates deployment by enabling you to edit the raw contents of the underlying application manifest that drives your application solution. The sample offers an introduction to the ServerDocument class capabilities and the notion of separating data from view in Office documents with cached DataSets.

Additional Resources

Visual Studio Tools for Office

• Microsoft Visual Studio Developer Center

• Visual Studio Tools for Office online documentation

• Office Development Samples

• Visual Studio Tools for Office Developer Portal

• Visual Studio Tools for Office Blog

• Visual Studio Tools for Office Newsgroup: microsoft.public.vsnet.vstools.office

Code Security

• Writing Secure Code

• Microsoft Security Developer Center