Office Development with Visual Studio : Deployment

Visual Studio 2010: Specify advanced publishing options (Saurabh Bhatia)

VSTO Team — Mon, 19 Oct 2009 22:31:12 GMT

I have previously posted how you can specify various properties for a VSTO solution like the Publisher and Product Names by tweaking a few files in Visual Studio 2008.

With Visual Studio 2010 (Beta 2) you can edit these properties directly through the Publish Page. All Office projects in Visual Studio 2010 now have an Options button on the Publish Page, which allows you to spet these properties.

The Publish Options dialog is similar to the ClickOnce publish options dialog for other types of projects, but this dialog only displays the options applicable to Office projects.

Here is what these properties mean:

Publisher Name – The name of the Publisher as displayed in Programs and Features

Product Name – The name of the Solution as it will show up in the Programs and Features (Add Remove Programs Entry)

Support URL – A URL which End Users can visit to get support for this particular solution. The support URL shows up as a clickable link for the product name during the installation trust prompt.

Solution Name – (Friendly Name) This is the name of the Add-In as it is displayed in the Office Add-ins dialog.

Office Application Description – The description of the Office Add-in as displayed in the Office Add-ins dialog.

Add-in Load Behavior – Specifies whether the add-in should load when the Office Application Starts up or whether it should load on demand when the end user tries to interact with it. By default all add-ins are set to load at startup of the Office Application but if you care about Office startup performance and don’t want your add-in to be running all the time then you should consider loading it on demand.

Andrew Whitechapel has a post on how an Office add-in can be demand loaded using different loadbehavior values. Previously you had manually update the ClickOnce manifests with the appropriate load behavior value. With Visual Studio 2010 you can set the option to load the add-in on demand and the loadbehavior will be automatically set to 16 (connect first time) –> Load the add-in on startup for the first time and then load on demand from then on.

Loading an add-in on demand can help improve the startup performance of the Office application. It can also reduce the application’s working set as the add-in is not loaded in memory until the end user interacts with it. Setting the add-in to demand load is a good option if your add-in has UI based triggers, like a Ribbon item that the end user can interact with to load the add-in. However demand loading may not be a good option if your add-in is needs to listen to application events like opening a document etc all the time the application is running. So if your add-in doesn’t have to run all the time, then setting it to Load on Demand is a good option to consider.

Lastly, there is an interesting side note for those of you who may have changed their VS 2008 based project files based on my previous post. If you updated the project file using the same property names as that mentioned in the post, you can migrate that project to VS 2010 and continue using those property values. You no longer need the custom targets file as that functionality is now directly available in the Visual Studio common targets.

For more information, see Publishing Office Solutions.

Have fun with Visual Studio 2010 Beta2 and let us know your feedback!

Saurabh

Can I deploy my and all of its prerequisites in one file? (Mary Lee)

VSTO Team — Wed, 14 Oct 2009 22:16:01 GMT

One frequent customer question is about how to deploy an application and all of its prerequisites in a single .msi or .exe file. This question applies whether you are deploying any of the following:

Microsoft Office 2003 solutions with dependencies on .NET Framework 2.0, Visual Studio Tools for Office 2005 SE runtime, Microsoft Office 2007 primary interop assemblies.
Microsoft Office 2007 solutions with dependencies on .NET Framework 3.5 , Visual Studio Tools for Office runtime 3.0, Microsoft Office 2007 primary interop assemblies.
Microsoft Office 2007 solutions with dependencies on .NET Framework 3.5 SP1, Visual Studio Tools for Office runtime 3.0 SP1, Microsoft Office 2007 primary interop assemblies.
Microsoft Office 2007 solutions with dependencies on .NET Framework 3.5 SP1 Client Profile, Visual Studio Tools for Office runtime 3.0 SP1, Microsoft Office 2007 primary interop assemblies.
Really, any WinForms/WPF/console/whatever app with dependencies on .NET Framework, SQL Server Express, SQL Server compact, Visual C++ runtime, Windows Installer, or anything else.

There are three concepts in deployment related to prerequisites: nesting, merging, and chaining or bootstrapping.

Nesting is the process of embedding a Windows Installer file (.msi) within another .msi file. However, the How to create a nested .msi package article has an important disclaimer.

The drawbacks of creating a nested MSI installation are listed in the same article.

Nested Installations cannot share components.
An administrative installation cannot contain a nested installation.
Patching and upgrading will not work with nested installations.
The installer will not correctly cost a nested installation.
Integrated ProgressBars cannot be used with nested installations.
Resources that are to be advertised cannot be installed by the nested installation.
A package that performs a nested installation of an application should also uninstall the nested application when the parent product is uninstalled.

For these reasons, nesting is no longer supported.

Merging includes shared code, files, resources, registry entries, and setup logic to applications as a single compound file. Prerequisites available as a merge module (.msm) form can be added to a .msi file. For example, if a prerequisite is available as an .msm, you can add it to a Setup project in Visual Studio as shown in How to: Create or Add a Merge Module Project. However, merge modules cannot be serviced by the same owner as the .msi file, so it is difficult to fix issues in the merge module. Tao of the Windows Installer, Part 4 lists two cautionary notes:

Do not consume merge modules of vendors who do not promise to fix their merge modules promptly when bugs arrive
Be prepared to handle the heat when bugs are found in your merge module causing issues for others’ products that have consumed your merge module and you get to put out the flame

For these reasons, using merge modules is not recommended.

Nesting and merging create a single file to deploy an application and its prerequisites, but these methods are not supported and not recommended. Thus, the answer to the question in the title is no: you cannot or should not deploy an application and its prerequisites in one file.

Chaining or bootstrapping is the process of checking for and installing missing prerequisites, including installing the application that is going to be used to install the rest of the prerequisites and application. You can use Visual Studio to generate a chainer/bootstrapper that is called Setup.exe. This program checks for and installs missing prerequisites before installing the application or Office solution.

If you are deploying an Office 2007 solution in Visual Studio 2008 SP1, the .NET Framework 3.5 SP1, Visual Studio Tools for Office 3.0 SP1 runtime, and Microsoft Office 2007 primary interop assemblies are already selected in the Prerequisites Dialog Box.

To learn more about how to install prerequisites in Visual Studio, see the following topics.

How to: Install Prerequisites on End User Computers to Run Office Solutions

How to: Install Prerequisites in Windows Installer Deployment

How to: Install Prerequisites with a ClickOnce Application

If the prerequisite package does not appear in Visual Studio, you can create your own bootstrapper package. After you create a product.xml file that describes the prerequisite and a package.xml files that includes locale-specific error messages, you can copy the bootstrapper package to \Program Files\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages folder. For more information, see Creating Bootstrapper Packages.

Other tools besides Visual Studio: You can also use MSBuild and the GenerateBootstrapper Task to create a bootstrapper on a build computer. Alternatively, you can use the Windows Installer XML Toolset to generate .msi files and package prerequisites. For more information, see http://wix.sourceforge.net/.

For questions about bootstrapping, search for answers or post new questions in the ClickOnce and Setup & Deployment forum.

Happy deployment!

Mary Lee, Programming Writer.

Use a path that resolves anywhere your VSTO solution could be deployed (Christin Boyd)

VSTO Team — Thu, 04 Jun 2009 23:29:27 GMT

One of the VSTO MVPs pointed out that in some cases his customers were unable to resolve UNC paths consistently. When he investigated further, he found that some branch offices of an enterprise were unable to resolve the UNC path (\\myserver\myvstoapps\installpath\) because of the way they setup their network infrastructure. The only workaround he could find was to use a fully qualified web URL instead of a UNC path. The resolution was to create a web server internal to the corporation which is still accessible by people in the branch office. The other option would be to negotiate with the IT staff to change the way the branch office resolves server names, but apparently that was not an option.

We looked at the situation and agree with his conclusion about the workaround. If the network just won’t give you the correct path using UNC, then HTTP is a reliable solution.

-Christin Boyd, Program Manager

Copying a Document to the End User Computer after a ClickOnce Installation (Mary Lee)

VSTO Team — Thu, 21 May 2009 20:00:00 GMT

Starting in Visual Studio 2010 Beta 1, you can perform additional tasks after an Office solution is installed known as a post-deployment action. For example, you can copy a customized Office document and create registry keys on the end user computer. You can compare these to Windows Installer custom actions.

The Visual Studio Tools for Office runtime supports the ability to perform post-deployment actions after an Office solution is installed. However, Visual Studio does not generate the necessary sections of the ClickOnce application and deployment manifests to perform these actions. To run these post-deployment actions, you must modify the application and deployment manifests. This process is demonstrated in the Walkthrough: Copying a Document to the End User Computer after a ClickOnce Installation topic in the MSDN Library.

The walkthrough uses an Excel workbook project, but this example uses a Word document project for demonstration purposes.

Creating a New Project

1. Create a new Word document-level project that targets the .NET Framework 3.5 named FabrikamWordDocument.

2. Add code to the FabrikamWordDocument project.

3. Build the project.

Creating a Class Library Project that Defines the Post-Deployment Action

1. Create a class library called FileCopyPDA.

2. Add references to Microsoft.VisualStudio.Tools.Applications.Runtime.v10.0 and Microsoft.VisualStudio.ToolsApplications.ServerDocument.v10.0.

3. Rename the class to FileCopyPDA.

4. Replace the FileCopyPDA class with the following code that completes the following tasks:

Copies the Word document file to the user's desktop if the solution is installed or updated.

Changes the _AssemblyLocation property from a relative path to a fully qualified path for the deployment manifest. This is done using the AddCustomization and RemoveCustomization methods.

Deletes the file if the solution is uninstalled.

Public Class FileCopyPDA
    Implements IAddInPostDeploymentAction

    Sub Execute(ByVal args As AddInPostDeploymentActionArgs) Implements IAddInPostDeploymentAction.Execute
        Dim dataDirectory As String = "Data\FabrikamWordDocument.docx"
        Dim file As String = "FabrikamWordDocument.docx"
        Dim sourcePath As String = args.AddInPath
        Dim deploymentManifestUri As Uri = args.ManifestLocation
        Dim destPath As String = Environment.GetFolderPath(Environment.SpecialFolder.DesktopDirectory)
        Dim sourceFile As String = System.IO.Path.Combine(sourcePath, dataDirectory)
        Dim destFile As String = System.IO.Path.Combine(destPath, file)

        Select Case args.InstallationStatus
            Case AddInInstallationStatus.InitialInstall, AddInInstallationStatus.Update
                File.Copy(sourceFile, destFile)
                ServerDocument.RemoveCustomization(destFile)
                ServerDocument.AddCustomization(destFile, deploymentManifestUri)
                Exit Select
            Case AddInInstallationStatus.Uninstall
                If File.Exists(destFile) Then
                    File.Delete(destFile)
                End If
                Exit Select
        End Select
    End Sub

End Class

5. Build the FileCopyPDA project.

6. Add a reference to FileCopyPDA.dll in the FabrikamWordDocument project.

7. Create a directory called “Data” in the FabrikamWordDocument project.

8. Add the FabrikamWordDocument.docx file to the Data folder.

9. In Properties window for the FabrikamWordDocument.docx file, change the Build Action property to Content, and change the Copy to Output Directory property to Copy if newer.

10. Publish the FabrikamWordDocument project. This example uses the c:\publish directory.

Modifying the Application Manifest

1. Open the C:\publish\Application Files\FabrikamWordDocument_1_0_0_0\FabrikamWordDocument.dll.manifest file in the XML Editor in Visual Studio.

2. Add the following XML code after the </vstav3:update> element to run the FileCopy post-deployment action.

<vstav3:postActions>
  <vstav3:postAction>
    <vstav3:entryPoint
      class="FileCopyPDA.FileCopyPDA">
      <assemblyIdentity
        name="FileCopyPDA"
        version="1.0.0.0"
        language="neutral"
        processorArchitecture="msil" />
    </vstav3:entryPoint>
    <vstav3:postActionData>
    </vstav3:postActionData>
  </vstav3:postAction>
</vstav3:postActions>

Re-signing the Manifests

To prove that yes, you really meant to make these changes to the application manifest, you must re-sign the application manifest with a certificate. Then, re-sign and update the deployment manifest to point to the new application manifest.

1. Copy your certificate to the C:\publish\Application Files\FabrikamWordDocument_1_0_0_0 directory. In this example, I’m reusing the temporary certificate created by Visual Studio because I’ll be installing this to a test computer. For production deployment, we recommend that you use a certificate obtained from a certificate authority.

2. In a Visual Studio command prompt, change to the C:\publish\Application Files\FabrikamWordDocument_1_0_0_0 directory. (You may have to open the command prompt in Administrator mode to re-sign the files in the c:\publish directory.)

3. Re-sign the application manifest with the following command:

mage -sign FabrikamWordDocument.dll.manifest -certfile FabrikamWordDocument_TemporaryKey.pfx

4. Change to the c:\publish directory

5. Re-sign the deployment manifest with the following command (on one line):

mage -update FabrikamWordDocument.vsto

–appmanifest "Application Files\FabrikamWordDocument_1_0_0_0\FabrikamWordDocument.dll.manifest"

-certfile "Application Files\FabrikamWordDocument_1_0_0_0\FabrikamWordDocument_TemporaryKey.pfx"

6. Copy the c:\publish\FabrikamWordDocument.vsto file to the c:\publish\Application Files\FabrikamWordDocument_1_0_0_0 directory.

Testing the Installer

1. Copy the c:\publish directory to a test computer.

2. In the c:\publish directory, run the Setup.exe file or double-click FabrikamWordDocument.vsto.

3. Verify that FabrikamWordDocument appears in the Add/Remove Programs list in Windows XP or Programs and Features in Windows Vista.

4. Verify that the FabrikamWordDocument.docx file appears on the desktop.

5. Open the Word document file to verify that your code is running.

Feel free to leave comments and feedback about this new scenario at the bottom of this article.

Happy deployment!

Mary Lee, Programming Writer.

Deploying Multiple Office Solutions In a Single Installer (Mary Lee)

VSTO Team — Wed, 20 May 2009 20:00:00 GMT

Starting in Visual Studio 2010 Beta 1, you can deploy multiple Office solutions in a single ClickOnce installer. For example, you can develop two Office solutions (one for Outlook and another for Excel) and combine these into a single installer with a single entry in the Add/Remove Programs list in Windows XP and the Programs and Features list in Windows Vista.

The Visual Studio Tools for Office runtime supports the ability to deploy multiple Office solutions in a single installer. However, Visual Studio still generates the ClickOnce application and deployment manifests for individual deployment. To deploy multiple Office solutions in a single installer, you must modify the application and deployment manifests to install multiple assemblies. This process is demonstrated in the Walkthrough: Deploying Multiple Office Solutions in a Single ClickOnce Installer topic in the MSDN Library.

Creating Multiple Office Solutions

To continue the example mentioned in the introduction, you can develop an Excel workbook project and an Outlook add-in project for .NET Framework 3.5. Then, to deploy both of these, create an installer project, which you can re-use later to add a third or fourth project. By keeping this installer project separate, it’s possible to keep the original files for the individual projects intact. In this example, the installer project is based on a Word document project, but the document isn’t being deployed. The following figure shows Solution Explorer with three projects, one installer project and two projects to deploy to end user computers.

Publishing the Office Solutions

After you add your code to the Excel and Outlook projects, publish the ContosoExcelWorkbook, ContosoOutlookAddIn, and then ContosoInstaller projects (in that order) to a folder on the development computer. You can right-click on the projects in Solution Explorer, and then click Publish. In this example, the publish directory is c:\publish.

Modifying the Application Manifest

Visual Studio generates an application manifest and deployment manifest for each project. The ClickOnce application manifest is a description of all the files included in the project. Additionally, this file describes how the Office application could load the assembly and run your code. By modifying the application manifest, you can describe files from multiple projects and install all specified projects. There are three different sections of the application manifest to modify: install dependencies, entry points, and assemblies.

These changes may appear lengthy, but it really amounts to a few copy-paste operations and adding four words to the application manifest.

Adding the Install Dependencies

1. In the c:\publish\Application Files folder, copy the contents of the ContosoExcelWork_1_0_0_0 and ContosoOutlookAddIn_1_0_0_0 folder into the ContosoInstaller_1_0_0_0 folder.

2. From the c:\publish\Application Files\ContosoInstaller_1_0_0_0 folder, open the three .dll.manifest files in the XML editor in Visual Studio.

3. Copy the <dependency> block for the Office customization assembly from the ContosoOutlookAddIn.dll.manifest and ContosoExcelWorkbook.dll.manifest files into the ContosoInstaller.dll.manifest file. This code specifies that the ContosoOutlookAddIn.dll and ContosoExcelWorkbook.dll files are part of the ContosoInstaller project.

4. Delete the <dependency> block for the ContosoInstaller.dll. This file is not part of the project, because you are only using the ContosoInstaller project to generate the application manifest template.

Adding the Entry Points

1. In the ContosoInstaller.dll.manifest file, delete the text between the <vstav3:entryPointsCollection> and </vstav3:entryPointsCollection> elements.

2. In the ContosoOutlookAddIn.dll.manifest and ContosoExcelWorkbook.dll.manifest files, copy the text between the <vstav3:entryPointsCollection> and </vstav3:entryPointsCollection> elements and paste them into the ContosoInstaller.dll.manifest file.

3. Add an id to the <vstav3:entryPoints> elements.

Adding the assemblies

1. In the ContosoInstaller.dll.manifest file, delete the text between the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> and </vstov4:customizations> elements.

2. In the ContosoOutlookAddIn.dll.manifest and ContosoExcelWorkbook.dll.manifest files, copy the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> and </vstov4:customizations> elements and paste them into the ContosoInstaller.dll.manifest file.

3. Add the id name to the <vstov4:customization> elements.

4. Save the changes in the ContosoInstaller.dll.manifest file, and close the ContosoExcelWorkbook.dll.manifest and ContosoOutlookAddIn.dll.manifest files.

Re-Signing the Manifests

1. Copy your certificate to the c:\publish\Application Files\ContosoInstaller_1_0_0_0 directory. In this example, I’m reusing the temporary certificate created by Visual Studio because I’ll be installing this to a test computer. For production deployment, we recommend that you use a certificate obtained from a certificate authority.

2. In a Visual Studio command prompt, change to the c:\publish\Application Files\ContosoInstaller_1_0_0_0 directory. (You may have to open the command prompt in Administrator mode to re-sign the files in the c:\publish directory.)

3. Re-sign the application manifest with the following command:

mage -sign ContosoInstaller.dll.manifest -certfile ContosoInstaller_TemporaryKey.pfx

4. Change to the c:\publish directory

5. Re-sign the deployment manifest with the following command (on one line):

mage -update ContosoInstaller.vsto

-appmanifest "Application Files\ContosoInstaller_1_0_0_0\ContosoInstaller.dll.manifest"

-certfile "Application Files\ContosoInstaller_1_0_0_0\ContosoInstaller_TemporaryKey.pfx"

6. Copy the c:\publish\ContosoInstaller.vsto file to the c:\publish\Application Files\ContosoInstaller_1_0_0_0 directory.

Testing the Installer

1. Copy the c:\publish directory to a test computer.

2. In the publish directory, run the Setup.exe file or double-click ContosoInstaller.vsto.

3. Verify that ContosoInstaller appears in the Add/Remove Programs list in Windows XP or Programs and Features in Windows Vista.

4. Open the Excel workbook file and Outlook to verify that your code is running.

Feel free to leave comments and feedback about this new scenario at the bottom of this article.

Happy deployment!

Mary Lee, Programming Writer.

Issues with installing VSTO projects that were published from Visual Studio 2008 on Windows 7 RC (Saurabh Bhatia)

VSTO Team — Thu, 07 May 2009 23:32:00 GMT

Many customers have reported issues with installing a VSTO project that has been published with Visual Studio 2008 running on the recently released Windows 7 Release Candidate.

If you published your solution using VS2008 on a machine running the Windows 7 RC and then you try to install the solution on any machine you will see the following error: “The required version of the .NET Framework is not installed on this computer”

You will see this error even if you have the right version of .Net Framework installed. The issue occurs due to some differences in the publishing mechanism on the Windows 7 RC caused by a missing file in the .Net Framework 3.5.1 which was included in the RC.

The following file is missing:

%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.5\RedistList\FrameworkList.xml

You can workaround the issue by manually copying this file from an existing non Windows 7 machine which has the .Net Framework 3.5 installed. The file will be available at the exact same location.

Once you have included this file on the Windows 7 RC machine, you will be able to publish and generate the correct manifests. After making this change please republish any solutions that were previously published from the Windows 7 RC machine. These solutions will now be able to install successfully.

We are tracking this issue and plan to address it before Windows 7 RTM. If you are using the RC release please use the workaround mentioned above.

Updates**********

If you have having trouble replacing the file. You need to be an Owner of the file and your user account needs Full Control. To do this:

•    Right click the File -> Properties
•    Select Security Tab
•    Click the Advanced Button
•    Click the “Owner” Tab
•    Click the Change Button
•    Double Click your User Object
•    Click Okay
•    Click Okay,
•    Ensure you have “Full Control” Permissions to the file by repeating steps above and adding your user account with Full Control permissions.

Also if you are on a 64 bit system:

Note that you need to replace both the architecture specific files on a 64bit bit OS, i.e.
[Program Files x86]\Reference Assemblies\Microsoft\Framework\v3.5\RedistList
%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.5\RedistList

Signing and re-signing manifests in ClickOnce (Saurabh Bhatia)

VSTO Team — Thu, 30 Apr 2009 04:25:00 GMT

ClickOnce manifest signing can be a little confusing for someone going through the process the very first time. This is probably because it involves signing multiple files in a particular sequence. Once you understand the process conceptually it becomes fairly easy to follow. In this post, I hope to provide a quick summary of the important thingsyou need to know about manifests and this signing/resigning business.

Let’s start with some background info in case you missed it:

What are these manifests I speak of?

Any application deployed through ClickOnce will have two manifests: a deployment manifest and an application manifest.

Depending on the type of application, the deployment manifest can have the following file extensions:

.application – for any executable application like a Winforms or WPF application

.vsto – for a VSTO based Office customization solutions (which this blog is all about)

.xbap – for a Browser Hosted WPF application

An application manifest will always have the .manifest extension. For example:

.exe.manifest – for any executable including Winforms, WPF and Browser Hosted WPF applications.

.dll.manifest – for VSTO based office customizations.

MSDN has documentation that describes these files and their use in detail but for a one line summary – think of these as “Setup Authoring” for your application that tells the application how to install, update, what the application is called etc.

ClickOnce Application Manifest

ClickOnce Deployment Manifest

Application Manifests for Office Solutions (2007 System)

So why do manifests have to be signed?

The ClickOnce “trust model” is based on signing the ClickOnce manifests with a Certificate. By “trust model,” I mean the process by which ClickOnce and the end user can decide whether to trust an application and allow it to install or not. To sign an application, you need a Certificate - Visual Studio will generate a temporary certificate for you when you publish an application (like MyApplication_Temporary.pfx) and also sign the manifests for you. You can also choose to sign the manifests with a code-signing certificate that you can obtain from a Root Certificate Authority.

These MSDN articles go into details about the certificates and how they are used:

ClickOnce Deployment and Authenticode

Signing ClickOnce Manifests

Starting with .NET 3.5 SP1, signing has become optional for any .exe-based application. So Winforms/WPF/Console applications deployed via Clickonce no longer need to be signed. The downside of course is that there are no guarantees on the integrity of the application. The developer has to make the choice between the tradeoff of securing the application and going through the signing process vs not signing the application at all and relying on some other means of ensuring the application has not being compromised.

Note that VSTO solutions still require that the manifests be signed. Most VSTO scenarios are in the enterprise where best practices require signing of applications. Also since VSTO solutions always run full trust there is a higher risk associated with making signing optional.

Why do they need to be re-signed?

Visual Studio is capable of generating signed manifests. Why get into this whole re-signing business? Re-signing is needed when you are in a situation where you want to change something about the application after it has already been published – and you want to do so without re-building or re-publishing the application from Visual Studio. You may want to simply sign the application with a different certificate without re-building the application, for example you test the application with a self created test certificate but when you deploy the application to end users it is signed with a code-signing certificate issued by a Certificate Authority. Some of the most common examples that re-quire re-signing are when you want to change a particular file that is part of your application like the .config file, or maybe a simple resource/data file that is deployed along with your application.

The ClickOnce manifests contain hashes to all the files that are being deployed as part of the application. If any of the files change, then the hash for that file breaks and the signing becomes invalid. So you cannot simply replace an individual file in a ClickOnce package without breaking the signing. You will have to update and re-sign the manifests if you want to update a file.

The following figures should help illustrate this better.

A typical ClickOnce deployment package consists of

· Deployment Manifest

· Application Manifest

· Application Files – the exe and dlls associated with the application.

The deployment manifest links to the application manifest along with the hash of the application manifest, so if the application manifest changes the hash will no longer be valid. Similarly the Application manifest links to all the application files along with their hashes.

So consider the situation where one of the application files say the .config file in this case changes after the app has been published.

Since the .config file changed the hash in the Application Manifest will not match up to the new file anymore. Trying to install the application in this state will fail (unless you are using optional signing and hashing of course).

You will have to update and re-sign the application manifest in order to get the deployment to work again.

You can do this using the following mage commandline:

Start the Visual Studio command prompt. Locate the application manifest folder. Typically under “%Publish Folder%\Application Files\MyApplication_Version\Myapplication.exe.manifest”

Use the –update option for the mage command line.

> mage –update Myapplication.exe.manifest –certfile mycert.pfx

The update command will update all the file hashes defined in the application manifest to match those of the files located next to it. For other options on how to use update see MSDN: Manifest Generation and Editing Tool (Mage)

Note: While update the application, you might see some errors about Files not found. This could happen if you using the .deploy extensions for you application files. To avoid this, you must rename the .deploy extensions back to their original extensions and then run the update command with mage. Once you have update the application manifest, you must rename the application files back with he .deploy extension.

Once you have updated the application manifest with mage, all the files it refers to will have the correct hashes. However at this point since the application manifest itself is updated, the hash to the application manifest contained within the deployment manifest will no longer match.

To fix this the deployment manifest needs to be updated with the hash of the new application manifest and re-signed.

The mage command line to do this:

> mage.exe –update Myapplication.application –appmanifest “Application Files\MyApplication_%Version%\Myapplication.exe.manifest” –certfile mycert.pfx

At this point, all the hashes to all the files have been updated and both manifests have been re-signed. So the application is ready to be installed on the end users’ machine without re-building or re-publishing from Visual Studio.

In the above example I chose to show how the resigning process is done through the Mage command line tool. The same process can be done through the MAGEUI tool which provides a GUI for the manifest editing. For simply re-signing your manifests I have always preferred to use the command line. The re-signing process itself can be straightforward once you understand the need for it. Most users forget to either update or sign both manifests and I hope this post illustrates the chaining dependency and why both manifests need to be updated.

Channel 9 Interview: Resigning ClickOnce Application and Deployment Manifests with MAGE (Beth Massi, Saurabh Bhatia)

VSTO Team — Wed, 08 Apr 2009 18:25:33 GMT

I just posted another interview on Channel 9. I sit down again with Saurabh Bhatia, a Program Manager on the Office Client team, who is responsible for the ClickOnce publishing functionality in Visual Studio. We chat about trust issues and certificates and he sets me straight on how ClickOnce deployment and application manifests work. He then shows how to resign them outside of Visual Studio using a tool called Mage. This is really handy for folks that need to modify the files within a deployment package, like the application settings (app.config) file, but don't have Visual Studio installed.

Channel 9: Resigning ClickOnce Application and Deployment Manifests with MAGE

Saurabh draws on the whiteboard in this one and since I'm a one (wo)man show I couldn't jump up and zoom in so I redrew it for you all here.

Links from the show:

VSTO Developer Center

Enjoy,
-Beth Massi, Visual Studio Community

Deploying Office Solutions with Visual Studio 2008 SP1 and Windows Installer (Mary Lee)

VSTO Team — Wed, 18 Mar 2009 18:36:44 GMT

In Deploying Office Solutions with a Setup Project (Mary Lee), you read about how to deploy Visual Studio Tools for Office solutions with Windows Installer (.msi) in Visual Studio 2008. With Visual Studio 2008 Service Pack 1, the steps are the same: add the project output to the Setup project, add registry keys, sign the application and deployment manifests, and so on.

However if you are using launch conditions to verify that the prerequisites are installed, you must update the launch condition to look for the VSTO 3.0 SP1 runtime.

In the Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System Using Windows Installer (Part 1 of 2) whitepaper, look at the To configure launch conditions procedure. Change step 6c from this:

Set the value of RegKey to Software\Microsoft\vsto runtime Setup\v9.0.21022

to the following:

Set the value of RegKey to Software\Microsoft\vsto runtime Setup\v9.0.30729

We are working to update the whitepaper to reflect both of these registry keys. If you have questions about the whitepapers, please visit the Visual Studio Tools for Office MSDN Forum to search for answers and ask your questions.

Happy deployment!

Mary Lee, Programming Writer.

Deploying Documents to a SharePoint Document Library (Mary Lee)

VSTO Team — Sat, 14 Mar 2009 02:56:00 GMT

When you are done developing your customized Microsoft Excel 2007 or Microsoft Word 2007 document-level project in Visual Studio 2008, you may want to publish it to a SharePoint document library for others to use from the SharePoint site, or they can copy the file from the site to their desktop to use locally. In either case, the customization assembly cannot be stored in the SharePoint document library, so you have to configure the workbook to store the assembly on a file share.

In Solution Explorer, right-click the Excel document-level project, and then click Publish. You'll see the Publish Wizard appear.

In the first page of the Publish Wizard, type the folder name where you want Visual Studio to copy the files, known as the publish location. In this case, it's a subfolder of the project folder.

In the second page of the Publish Wizard, type the folder name where the installation files will be located. In this example, the installation files are located on a configure the workbook to look for the assembly on a file share, known as the install location.

Note: You could have set the publish location to this file share in step 1 if you have access rights to the file share. Setting the install location separate from the publish location allows you to publish the files locally and then hand the files over to an IT administrator to upload the files to a file share.

The third and last page of the Publish Wizard is a summary of the publish options.

Copy the publish folder from step 1 to the file share, and upload the Excel workbook file to a SharePoint document library.

The final step is to trust the location of the SharePoint document library to the Trusted Location in Excel. Copy the URL of the SharePoint document library and remove the last Forms/Allitems.aspx text from the URL. For example, if your SharePoint document library is http://sharepoint/sites/writers/SampleDocLibrary/Forms/AllItems.aspx, the location to add to Excel is http://sharepoint/sites/writers/SampleDocLibrary.

1. Open Excel.

2. Click the Microsoft Office button.

3. Click Excel Options.

4. Click Trust Center.

5. Click Trust Center Settings.

6. Click Trusted Locations.

7. Check Allow Trusted Locations on my network.

8. Click Add new location.

9. In the Microsoft Office Trusted Location dialog box, in the Path textbox, type or paste the URL to the SharePoint document library. In this example, it's http://sharepoint/sites/writers/SampleDocLibrary.

10. Click OK to close the Microsoft Office Trusted Location dialog box.

11. Click OK to close the Trust Center dialog box.

12. Click OK to close the Excel Options dialog box.

Finally, open the Excel workbook file from the SharePoint document library. This starts the installation process for the Excel solution. Depending on the security settings, you may see the Microsoft Office Customization Installer dialog box prompting you to install the Excel solution.

This is the blog version of the following topic in the MSDN Library: How to: Deploy a Document-Level Office Solution to a SharePoint Server (2007 System). You can also see the video demonstration at Video How to: Deploy a Document-Level Office Solution to a SharePoint Server (2007 System).

Happy deployment!

Mary Lee, Programming Writer.

VSTO Runtime bootstrapper package failure causes deployed customization installation to fail (Aaron Cathcart)

VSTO Team — Sat, 07 Feb 2009 11:48:00 GMT

In an attempt to make this easier to read here are a few terms I will be using frequently in this article:

VSTOR = Visual Studio Tools for the Microsoft Office System (version 3.0 Runtime) (x86)
VSTORSP1 = Visual Studio Tools for the Microsoft Office System (version 3.0 Runtime) Service Pack 1(x86)
Bootstrapper = the clickonce bootstrapper that gets deployed with a VSTO customization when there are prerequisites checked (setup.exe)

Some of our customers have raised an issue with the bootstrapper failing after deploying their customizations onto a user’s machine that has previously had VSTOR & VSTORSP1 installed.

The problem occurs when an end user installs VSTOR followed by VSTORSP1 then subsequently uninstalls VSTOR from the Add/Remove Programs wizard. The uninstall removes the entire product including the service pack but fails to update the registry keys that our bootstrapper uses to detect if VSTOR is installed. If a user then installs a customization using the bootstrapper it will incorrectly detect that VSTOR is installed and proceed to install VSTORSP1, at which point it fails.

I recently responded to a customer on the VSTO forums ( http://social.msdn.microsoft.com/Forums/en-US/vsto/thread/2dd02b04-cc89-47c3-8f76-462ecfbee65e ) regarding this issue where I approached it from an end-user perspective, providing them with a list of fixes for post-deployment use. The purpose of this article is to provide a solution that developers can utilize so that end-users machines do not require post-deployment modification.

This workaround will allow developers to bake the correct VSTOR detection logic into every customization they develop that utilizes the bootstrapper.

Here is what you need to do:

On the development machine locate the file %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\VSTOR30\product.xml
Replace the element
<RegistryCheck Property="VSTORuntimeInstalled" Key="HKLM\SOFTWARE\Microsoft\VSTO Runtime Setup\v9.0.21022" Value="Install"/>
with
<MsiProductCheck Property="VSTORuntimeInstalled" Product="{8FB53850-246A-3507-8ADE-0060093FFEA6}"/>
Alter the element
<BypassIf Property="VSTORuntimeInstalled" Compare="ValueGreaterThanOrEqualTo" Value="1"/>
to be
<BypassIf Property="VSTORuntimeInstalled" Compare="ValueGreaterThanOrEqualTo" Value="3"/>

And that’s it! Now that you have made these changes to your product.xml, every VSTO customization you build and deploy with a bootstrapper will correctly detect if VSTOR is installed regardless of what state the end-users machine is in.

Best Practices for Deployment with Visual Studio 2008 SP1 (Mary Lee, Rachel Schaw)

VSTO Team — Tue, 03 Feb 2009 02:01:00 GMT

After you develop Office solutions with Visual Studio Tools for Office, you can use Visual Studio 2008 SP1 to simplify your deployment experience. First, you can take advantage of the smaller .NET Framework Client Profile to decrease download time. Next, the Office 2007 primary interop assemblies (PIAs) are included in-the-box with VS2008 SP1 to avoid having to generate bootstrapper manifests. Finally, you can also troubleshoot any installation problems with the event viewer.

Develop your Office 2007 solutions against the .NET Framework Client Profile. The large size of the .NET Framework 3.5 SP1 can lead to long download times. The .NET Framework Client Profile is only 25MB in size, so download times are reduced when installing from the component vendor's web site. For more information about how to configure your solution to use the .NET Framework Client Profile, see How to: Target a Specific .NET Framework.

Deploying the Office 2007 primary interop assemblies is now (mostly) hassle-free. Visual Studio 2008 SP1 includes the Office 2007 PIAs as part of the update. This relieves you from having to download the PIA installer, download a code sample that contains the bootstrapper manifests, move the manifests to a certain directory, compile the ComponentCheck.cpp file to verify that the correct version of Microsoft Office is installed, and dance the hula. Instead, developing with one of the Visual Studio Tools for Office project templates already marks the Microsoft Office 2007 primary interop assemblies as a prerequisites. All you have to do is right-click on the project in Solution Explorer and click Publish.

Troubleshooting the installation and deployment process is more transparent. Any errors that occur are now logged in the event viewer. For example, I deliberately installed the same Office solution twice to generate the following error in the event viewer. Developers commonly see this error when they build and debug an Office solution on their development computer, and then try to install the Office solution on the same development computer. To avoid this problem, use a different account to test the installer on the development computer, or use a different test computer. For more information about the event viewer, see Event Logging (2007 System).

Visual Studio 2008 SP1 also introduced ClickOnce manifests that do not need to be signed. However, Visual Studio Tools for Office relies on signed manifests to identify the publisher and determine if the Office solution is trusted. Optional signing is a feature in VS2008 SP1 that does not apply to Office developers. For more information about trusting Office solutions, see Granting Trust to Office Solutions (2007 System).

Mary Lee, Programming Writer.

Rachel Shaw, Program Manager.

Deploying Office 2003 Solutions with Windows Installer (Mary Lee)

VSTO Team — Thu, 18 Dec 2008 02:08:05 GMT

You may want to develop Microsoft Office 2003 solutions with Visual Studio Tools for Office (VSTO) in Visual Studio 2008 SP1 for several reasons.

Your customers are using Microsoft Office 2003.
Your customers are using both Microsoft Office 2003 and the 2007 Microsoft Office system.
Your customers are using .NET Framework 2.0 and cannot migrate to .NET Framework 3.5.

Once you're done with development, you'll want to deploy your Microsoft Office 2003 solutions to your end users. This process involves the following steps:

Check for and install the following prerequisites: .NET FX 2.0, VSTO 2005 SE runtime, and the Microsoft Office primary interop assemblies. If your client computers already have the prerequisites, or you want to do this manually, you can skip this step.
Copy the customization assembly to the end user computer.
Grant full trust to the customization assembly.
For application-level add-ins only, create a set of registry keys so that the Office application knows to load the add-in.

Due to customer demand, I've created five deployment samples that demonstrate these steps. Step 1 is demonstrated in two ways: you can select your prerequisites through the Prerequisites Dialog Box to be installed with the Setup.exe bootstrapper; alternatively, you can configure launch conditions in the Setup project to only install the customization if the prerequisites already exist.

Prerequisites Dialog Box:

Launch Conditions editor:

You can use the Setup project to complete step 2 by copying the customization assembly and for document-level projects, the document or workbook, to the designated installation location. This is done by adding the project output with the File System Editor. The default installation location in these Setup projects is %PROGRAMFILES%\MyCompany\<Name of Setup Project>.

File System Editor:

Full trust is granted by using the SetSecurity project for step 3. This code uses a custom action in the Setup project to create a code access security policy that creates a solution code group for your Office solution, and an assembly code group for the customization assembly.

Custom Actions Editor:

Step 4 only applies to application-level add-ins: when you use the Excel 2003 add-in or Word 2003 add-in project templates, there is a Setup project automatically added to your Office solution that already creates the registry keys documented in Registry Entries for Application-Level Add-Ins.

Registry Editor:

The process of preparing the development computer for deployment and configuring the Setup project is written out step-by-step in the following two whitepapers:

Deploying Visual Studio 2005 Tools for the Office System SE Solutions Using Windows Installer (Part 1 of 2)

Deploying Visual Studio 2005 Tools for the Office System SE Solutions Using Windows Installer: Walkthroughs (Part 2 of 2)

Now, it's time to experiment on your own. Download the sample code and the completed installers from the MSDN Code Gallery: http://code.msdn.microsoft.com/VSTO2005SEMSI

Happy deployment!

Mary Lee, Programming Writer.

Why Can’t I Change the Update Path when Redeploying VSTO Solutions? (Christin Boyd, Kris Makey, Jeff Young)

VSTO Team — Wed, 17 Dec 2008 01:45:39 GMT

The other day I was asked about the automatic Updates feature of VSTO 3.0 deployment. In this scenario, he used the Publish Wizard in VS 2008 to create a Word document solution and the install manifest. Then a bunch of people used the Word document, and kicked off the installer which then copied things to their ClickOnce cache. Everything worked fine. Then he needed to make changes to the code, recompile, and somehow get the solution to all of his customers. Instead of using the Publish Wizard to create the update in the same server, he chose to use a different server path. The customers were unable to install the updates. He tried editing the custom properties of the document to change the install path to the new server, but it still didn’t work. Then he tried testing with a new, clean computer, and on that computer he was able to install from the new path and use the new Word document. He asked us why were the “old” users unable to get the update?

This question shows up on the Forum occasionally. “Why can I not change the update location of VSTO v3 Add-in or Document once it is installed?” (Or) “Why does VSTO continue to check in the old location even after I change location property on client machines that installed the old version?”

The Path to the deployment manifest is used as part of the Identity for an Add-in. During the First installation of an Add-in or Document, the Full Path is set and stored by the VSTO Runtime for that client machine. Once you have installed an Add-in changing the path in the registration will cause the Add-in to throw an Error. Once you have installed a customized Document, the code-behind will only check the original location and changes to the path stored in the document will be ignored (this is to allow copying a local version of a customized document that you installed from a remote location). In order to change the location that an Add-in or Document checks for updates, you must First uninstall the “old” version on the installed clients and then install from the new location.

Now, if you want to delve deeper, then keep reading this paragraph, or skip to the next one. The low-level explanation is that ClickOnce uses the solution path as part of its identity when storing solutions into the ClickOnce cache. You will get similar behavior in a CO-deployed Windows Application as well _unless_ you use the deploymentProviderURL (DPURL). Setting the DPURL can allow WinForms applications to change where updates are pulled from so that Server A (from which a solution was original installed) can be decommissioned and updates can be retrieved from Server B. VSTO does not support DPURL. Why not, you ask? At the time we were considering it during the development of VS 2008, the amount of development work-months required was more than the time we had remaining (DPURL has implications on migration of data from old solution to new solution, for instance). After much discussion, we decided to have the ClickOnce team throw an exception of a DPURL is set for VSTO solutions. At the start of development for VS 2010, we considered this feature again, but again this feature did not make our list of highest priority deployment features. We are implementing a lot of new deployment features for VS 2010.

In conclusion, the solution Path is used as part of the identity. You can’t change the update path after you've installed an Office solution. In a Windows solution, you can change the update path using DPURL. VSTO doesn’t support DPURL because we couldn’t fit that feature in the development schedule. The workaround is to uninstall the solution from the user’s computer when it is stuck pointing to an old path that you can’t update anymore and then reinstall with a new Install Path set in the Publish wizard. We recommend that you set your Install Path to a URL that you predict can stay the same for as long as your users will need updates.

This explanation applies to Word document and template solutions, and to Excel spreadsheet and template solutions.

I hope this blog entry is helpful! Please leave comments to this article if you have feedback.

-Kris Makey, Jeff Young, Christin Boyd, Mary Lee and Saurabh Bhatia contributed to this blog post

How to Include .NET Framework 3.5 SP1 with Your Installer (Mary Lee)

VSTO Team — Wed, 19 Nov 2008 01:55:00 GMT

Recently in the Visual Studio Tools for Office forum, a Visual Studio 2008 SP1 developer asked how to include the .NET Framework 3.5 Service Pack 1 in the same directory as the application. For example, you can select Download prerequisites from the same location as my application in the Prerequisites Dialog Box if your application is going out on CD and being installed without a network connection.

However, when you try to build your setup project or ClickOnce installer, you see the following error message: "The install location for prerequisites has not been set to 'component vendor's web site' and the file 'DotNetFX35SP1\dotNetFX20\netfx20a_x86.msi' in item '.NET Framework 3.5 SP1' can not be located on disk. "

What does it mean? The installers for .NET Framework 3.5 SP1 were not included in the VS2008 SP1 installer due to size restrictions. The default deployment experience is to download the .NET Framework 3.5 SP1 from the Microsoft Download Center during installation.

How do you include the .NET Framework 3.5 SP1? You can download the full .NET Framework 3.5 SP1 installer and extract the necessary files to the Visual Studio bootstrapper directory. After you modify the product.xml file and update the PublicKey value, the .NET Framework 3.5 SP1 will appear in the Prerequisites Dialog Box. You can find the full instructions in the Visual Studio 2008 Service Pack 1 Readme in section 2.3.1.1 Enable Samesite for the .NET Framework 3.5 SP1 bootstrapper package.

While these steps may seem lengthy, you only have to complete the steps once on your development computer. Then, every project you develop and deploy can include .NET Framework 3.5 SP1 as a prerequisite.

If you have further questions about deployment, visit the ClickOnce and Setup & Deployment MSDN forum to search for answers or ask your questions.

Happy deployment!

Mary R Lee, programming writer.