Office Solution Build Process Overview
Building a Microsoft Office solution is very similar to building other applications in Visual Studio. However, there are several things to consider that are specific to Office solutions.
For general information about how to build applications, see Building in Visual Studio.
Project Output for 2007 System Projects
The output location for a 2007 version project is projectname\bin\release or projectname\bin\debug. You cannot build to a deployment directory.
Document-Level Projects
When you build a document-level project, the following items are included in the project output:
A copy of the project document.
The project assembly and all referenced assemblies that have their Copy Local property set to true.
The application manifest, which has the file name extension .manifest. For more information, see Application Manifests for Office Solutions (2007 System).
The deployment manifest, which has the file name extension .vsto. For more information, see Deployment Manifests for Office Solutions (2007 System).
A program database (PDB) file.
Application-Level Projects
When you build an application-level project, the following items are included in the project output:
The project assembly and all referenced assemblies that have their Copy Local property set to true.
The application manifest, which has the file name extension .manifest. For more information, see Application Manifests for Office Solutions (2007 System).
The deployment manifest, which has the file name extension .vsto. For more information, see Deployment Manifests for Office Solutions (2007 System).
A program database (PDB) file for the project assembly.
The build process for application-level projects also creates a set of registry entries on the development computer that are required to load the add-in. For more information, see Registry Entries for Application-Level Add-Ins.
If you build an Outlook add-in project that contains form regions, the build process adds the following additional information to the registry:
A key for each message class that is associated with one or more form regions.
An entry for each form region and an associated value that represents the name of the Outlook add-in.
Outlook needs this information to load the form regions.
Project Output for 2003 System Projects
The output location for a 2003 version project is projectname\bin\release or projectname\bin\debug. You cannot build to a deployment directory.
Document-Level Projects
When you build a document-level project, the following items are included in the project output:
A copy of the project document.
The project assembly and all referenced assemblies that have their Copy Local property set to true.
The application manifest (embedded in the document). For more information, see Application and Deployment Manifests in Office Solutions.
A program database (PDB) file.
For Excel solutions, you cannot change the output path, or working directory. If you set the working directory option in the Debug pane of the Project Designer to a different location, Excel will change it back to the default at run time when the document is opened. However, for Word solutions, you can change the output path normally.
Application-Level Projects
When you build an application-level project, the following items are included in the project output:
The project assembly and all referenced assemblies that have their Copy Local property set to true.
The application manifest. For more information, see Application and Deployment Manifests in Office Solutions.
A program database (PDB) file.
The build process for application-level projects also creates a set of registry entries on the development computer that are required to load the add-in. For more information, see Registry Entries for Application-Level Add-Ins.
Referenced Assemblies
You can reference assemblies (including class library projects) from your Visual Studio Tools for Office project. Every referenced assembly has a property called Copy Local. Copy Local indicates whether the assembly is copied to the output directory. By default it is set to true. Every referenced assembly that has Copy Local set to true is copied to the output directory.
Security During the Build Process
Visual Studio automatically configures the security settings on the development computer to grant trust to the solution during the build process. This allows the solution to run while you debug it. Security configuration is handled differently in projects for the different versions of Office.
2007 System Projects
For 2007 Microsoft Office system projects, Visual Studio Tools for Office uses an inclusion list and certificates to verify the publisher. Visual Studio automatically creates a temporary certificate to identify Office solutions, and adds an entry to the inclusion list to trust that certificate.
For more information, see Security in Office Solutions (2007 System).
2003 System Projects
For Microsoft Office 2003 projects, Visual Studio Tools for Office includes a Boolean property called Trust Assemblies Location. This property appears in the Properties window in Visual Studio. By default, this property is set to True. If the property is set to True, when you build the project, Visual Studio grants full trust to the project assembly by using the URL as evidence.
Full trust permissions are also granted to referenced and satellite assemblies that are in the output folder. Trust is granted at the User level for assemblies that are on the local computer. Therefore, you do not need administrative credentials for those projects. If you rebuild the project in a different location, the full trust permissions for the old location are removed. For more information about security, see Security Requirements to Run Office Solutions (2003 System).
Checking the location and granting trust at each build enables you to move projects and share projects without having to change the security configuration of the computer manually every time. However, you must use the tools provided by Visual Studio to change the project location. If you use an external tool, such as Windows Explorer, Visual Studio is not able to update the permissions.
Network Projects
If the assembly or document location is on a network share, the local (User level) security policy update is not enough to allow the solution to run. An administrator must grant full trust at the Machine level to assemblies and documents that are on a network share before the solution will run. For more information about how to set security policy, see How to: Grant Permissions to Folders and Assemblies (2003 System).
For 2007 system document-level projects, you must also add the fully qualified location of the document to the Office trusted folders list. For more information, see Granting Trust to Documents (2007 System).
Testing a Document-Level Customization
Press F5 to build and debug a solution. If you want to test a Word 2003 or a Word 2007 solution without debugging by building and then opening the document outside Visual Studio, close the project before you open the document. When you open a Word document in Visual Studio, a flag is set on the Word process so that it does not run customizations. If you open a customized Word document outside Visual Studio by double-clicking the file in Windows Explorer, the flag can prevent this document from running customizations also. When you double-click the file to open it, Word opens the document in the same process as any currently running document. Since a document is open in Visual Studio, the new document is opened in that same process and receives the flag not to run customizations.
Testing an Application-Level Add-In
Press F5 to build and debug a solution. If you test your application-level add-in by publishing and installing the solution, uninstall the solution before re-publishing or making more code changes and re-testing by pressing F5. When you install a published solution, the assembly for the add-in is installed into the ClickOnce cache. The Setup program also creates registry keys so the Office application can find and load the assembly. Because rebuilding the solution updates the registry keys, it is necessary to uninstall the first version before publishing or running the second version.
Using the Clean Command
To remove the built project files from the development computer, you can use the Clean command on the Build menu in Visual Studio. The Clean command deletes all files in the build output location. For application-level projects, the Clean command also removes the registry entries that are created by the build process.
Note
The Clean command does not remove the permissions that the build process granted to the solution assemblies. For information about how to remove permissions, see How to: Remove Permissions from Folders and Assemblies (2003 System).
Changing the Platform Target to x64
By default, the platform target is Any CPU. If you set the platform target to x64, you can compile the project, but the solution will not run. The x64 platform target requires the solution to run in a 64-bit process. Office runs in a 32-bit process. Therefore, Office will not be able to load the solution.
See Also
Tasks
How to: Build Office Solutions
Concepts
Debugging in Document-Level Projects