Troubleshooting Deployment Errors in Visual Studio 2005 Tools for the Office System SE

Article
05/23/2014

Summary: Review code access security policy and learn how to avoid common deployment errors when developing custom solutions that use Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System, Second Edition. (6 printed pages)

Office Visual How To

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

Steve Hansen, OfficeZealot.com

June 2007

You spent hours perfecting an elegant solution to a problem by using Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System, Second Edition. Now it is time to deploy your work to your co-workers who are eager to start enjoying the fruits of your labor. You run your setup on a test computer and open the document. Nothing happens. Now what do you do?

While there is a growing amount of content available regarding Visual Studio Tools for Office deployment, there is not much regarding troubleshooting Visual Studio Tools for Office deployments. The purpose of this Office Visual How-To is to provide some guidance on troubleshooting common deployment problems.

The video uses the Microsoft .NET Framework 2.0 Configuration utility to create a code access security policy. However, you can also create a code access security policy from a command prompt window or from a script. For example, the following code example creates a user code access security policy named My code access security policy that uses a URL condition for evidence. Type the following command in a command prompt window. This code access security policy grants full trust to assemblies deployed to the "C:\My Deployment Directory" for the user account that executes the command.

Note

Line breaks are added to this code example to facilitate online viewing. You must remove them before running this command.

"C:\Windows\Microsoft.NET\Framework\v2.0.50727\caspol.exe" -q -u -ag 1 -url 
"C:\My Deployment Directory\*" FullTrust -name "My code access security policy" 
-description "A policy to allow my Visual Studio Tools for Office customization to run."

Using a wildcard (*) in a URL condition in this manner is a security consideration because it grants full trust to any code to run from the directory. You can enhance security by avoiding wildcards, by using a strong name, or by using a combination of a strong name and location.

Using the Visual Studio Tools for Office ServerDocument Class

The Application Manifest Editor sample application for Visual Studio Tools for Office is a good illustration of the capabilities of the ServerDocument class in Visual Studio Tools for Office. Among other uses, one use of this class is to manipulate a document's embedded application manifest. Even without the Application Manifest Editor sample application, it is trivial to build your own tool to work with embedded application manifests. For example, the following example opens a document, extracts the XML representing the embedded application manifest, and then shows it in a message box.

private void viewEmbeddedAppManifest(string file)
{
    if(ServerDocument.IsCustomized(file))
    {
        ServerDocument serverDoc = null;
        try
        {
            serverDoc = 
                new ServerDocument(file, true, FileAccess.Read);
            MessageBox.Show(serverDoc.AppManifest.ToXml());
        }
        catch (Exception ex)
        {
            MessageBox.Show(ex.Message);
        }
        finally
        {
            if (serverDoc != null)
                serverDoc.Close();
        }
    } 
    else
    {
        MessageBox.Show("This is not a customized document.");
    }
}

There are two important concepts to understand when troubleshooting Visual Studio Tools for Office deployments. First, you need a basic understanding of code access security policies. Second, you need to have an understanding of the relationship between your document, the application manifest, the deployment manifest, and the assembly. These two topics are the source of most deployment problems.

Remember to ensure that the prerequisites are present on the target computer. In fact, since it is easy to check the prerequisites by using the Microsoft PSS VSTO 2005 Client TroubleShooter tool, it is a good first step in your troubleshooting process, unless you are positive that all of the prerequisites are in place.

Before moving on to specific troubleshooting tips, here is a two-minute review of code access security and the Visual Studio Tools for Office deployment model. The Visual Studio Tools for Office security design philosophy is secure by default. Nothing you create runs outside of the development environment unless it is given specific permission to run. Unlike Microsoft Visual Basic for Applications (VBA), code is not contained in the document. It is in a separate file. Because of these two design principles, you cannot distribute Visual Studio Tools for Office solutions merely by sending an Office document to an end-user as you can with VBA.

To run Visual Studio Tools for Office customizations, there are two primary tasks to complete. First, you must explicitly give permission for these customizations to run on each user's computer. Second, you have to provide a way for a Visual Studio Tools for Office extended document to know that there is an assembly associated with it, and if it has explicit permissions, where to locate the assembly containing your code. The functionality to do this is provided by Visual Studio Tools for Office. However, you need to understand how it works so that you can configure it correctly.

Code Access Security

Code access security grants permissions to code regardless of the role of the user, unlike Windows security. which is a role-based system. To make management of permissions easier, code access security uses code groups to manage permissions. There are two things to understand about code groups: evidence and permissions. Evidence refers to the characteristics of an assembly that allow the Microsoft .NET Framework to determine whether it is part of a given code group or not. Permissions refer to the types of activities that a given code group can perform. Regarding permissions and Visual Studio Tools for Office assemblies, understand that Visual Studio Tools for Office customizations must have full trust permissions.

Configuring a code access security policy for Visual Studio Tools for Office assemblies consists of two tasks:

Creating a code group that has full trust.
Ensuring that the Visual Studio Tools for Office assemblies, which should be part of that code group, have ample evidence to be associated with a code group, such as URL evidence, strong name evidence, certificates, or custom evidence.

Visual Studio Tools for Office Deployment Model

Because a Visual Studio Tools for Office assembly is not embedded in a document, you must be able to associate a Visual Studio Tools for Office assembly with a document (assuming you have a document-level customization rather than an application add-in). The Visual Studio Tools for Office deployment model is actually quite flexible. The key to successful deployments and to troubleshooting flawed deployments is developing an understanding of how this model works.

A typical document-level Visual Studio Tools for Office deployment consists of four files in addition to any supporting files (resources) that a solution requires. The four files are listed in Table 1.

Table 1. Visual Studio Tools for Office Deployment Components

ComponentFile ExtensionPurpose

Application Manifest*.dll.manifestDirects the Visual Studio Tools for Office runtime to the correct location of the assembly. Specifies which classes to instantiate when the customization starts up.

Assembly*.dllContains the functionality that you implemented.

Deployment Manifest*.applicationDirects the Visual Studio Tools for Office runtime to the most current version of the application manifest.

Document or template*.doc, *.dot, *.xls, *.xlt

The document that your customization extends.

Note

The document also contains an embedded version of the application manifest.

When the document is opened, the Visual Studio Tools for Office runtime examines the copy of the application manifest embedded in the document. The application manifest has an "installFrom" node that contains the location of the deployment manifest. The Visual Studio Tools for Office runtime proceeds to the deployment manifest and verifies whether the current application manifest version specified in the deployment manifest is the same as the version that is embedded in the document. If it is not, the runtime takes the application manifest version specified in the deployment manifest and embeds it in the document. At this point, the embedded application manifest version, the deployment manifest version, and the application manifest version are all synchronized. Next, the assembly loader for the common language runtime (CLR) attempts to load the assembly specified in the application manifest into memory. Finally, the Visual Studio Tools for Office runtime starts up the classes specified in the application manifest.

Note

You can deploy locally without a deployment manifest. In this case, the Visual Studio Tools for Office runtime resolves the location to the assembly by using the path relative to the current document location.

Troubleshooting Deployments

Armed with an understanding of code access security and the Visual Studio Tools for Office deployment model along with a couple of tools, you should be able to identify the source of your problems.

Validate prerequisites. The Microsoft PSS VSTO 2005 Client TroubleShooter tool makes this an easy task.
Verify the location of the four deployment files. One purpose of this step is to make sure that you can follow the path that the Visual Studio Tools for Office runtime uses to load the assembly. For example, the embedded version of the application manifest may point to an invalid path or URL, which prevents the Visual Studio Tools for Office runtime from locating the deployment manifest. If so, you can edit this path by using the Application Manifest Editor. The second purpose of this step is to validate the original location of the assembly. When you use URL evidence to associate the assembly with a code group, you need to know this for the final step—validating the code access security policy.
Validate the code access security policy. For example, if you use a URL condition, make sure that the URL matches the original location of the assembly as determined in step two above. If you use another condition for evidence, verify that the evidence associated with the assembly from step two matches the evidence defined in the code group. If the code group is not a level final code group, make it level final to verify that the code group works as expected. Then, turn level final off and use the "resolvegroup" flag with CASPOL.EXE or with the .NET Framework 2.0 Configuration tool to figure out which code group may be overriding the code group. Finally, if you are still having problems and want to assess whether the issue is truly a security issue or not, the easiest way to do this is to create a level final, URL condition at the enterprise level, and then attempt to open the document. This is the easiest condition to set up and use. Finally, in a remote document/remote assembly scenario (such as with Microsoft SharePoint Products and Technologies), you must grant full trust permissions to the document and to the assembly.

Note

The Microsoft PSS VSTO 2005 Client TroubleShooter tool, CASPOL.EXE, and the .NET Framework 2.0 Configuration tool are installed with the Microsoft .NET Framework 2.0 SDK and are not typically present on end-user computers.

These three steps reveal most of the common issues associated with flawed Visual Studio Tools for Office deployments.

Watch the Video

Video Length: 00:09:00

File Size: 8.78 MB WMV

Troubleshooting Deployment Errors in Visual Studio 2005 Tools for the Office System SE

Additional resources