Troubleshooting Deployment Errors in Visual Studio 2005 Tools for the Office System SE
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)
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. ![]()
Line breaks are added to this code example to facilitate online viewing. You must remove them before running this command.
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.
![]() 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:
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.
![]()
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. ![]()
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.
These three steps reveal most of the common issues associated with flawed Visual Studio Tools for Office deployments. |
![]() ![]() Video Length: 00:09:00 File Size: 8.78 MB WMV ![]()
|