Office Development with Visual Studio : Manifest

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

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.

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

Specifying a Product Name, Publisher Name and other properties for VSTO solutions (Saurabh Bhatia)

VSTO Team — Thu, 12 Jun 2008 02:04:00 GMT

Many customers have requested how to specify options like a Product or Publisher Name for Office 2007 VSTO solutions deployed from Visual Studio 2008. However, you cannot specify these properties in the Visual Studio IDE. In this post, I will describe the various other options you have to specify these properties.

Specifically we will be looking at the following properties:

Product Name – This is what the VSTO solution will be called in the Programs and Features (Add Remove Programs Entry)

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

Figure 1 : Programs and Features Dialog in Vista showing Product Name and Publisher Name

Friendly Name – This is the name of the VSTO solution as it is displayed in the Office Add-ins dialog, the same value is also used in the VSTO trust prompt. Usually this value should be the same as the Product Name.

Office Application Description – The description of the Office Add-in.

Figure 2 : Excel Add-ins Dialog showing Friendly Name and Office Application Description

SupportURL - End Users can click on the product name on the Trust Prompt dialog and visit a custom website related to the Solution.

Figure 3 : VSTO Trust Prompt with Friendly Name and link to SupporURL

The easiest way to specify these properties is to modify the Deployment and Application manifests for the VSTO solution (.vsto and .dll.manifest files).

To specify the Product, Publisher and SupportURL properties

The product name, publisher name and support url properties can all be specified in the deployment manifest, the .vsto file that is generated after publishing the solution. You can open the deployment manifest in a text editor and change the <description> tag to include the properties you want to specify.

Once you have modified the deployment manifest you need to resign it. This can be done using the Manifest Generation and Editing Tool (mage.exe) in the .NET Framework SDK, Windows SDK, or Visual Studio 2008.

Start the Visual Studio command prompt and use mage.exe to resign the deployment manifest:

mage –sign deploymentmanifest.vsto –Certfile Certificate.pfx

Example:

mage –sign MyExcelAddin.vsto –CertFile MyCert.pfx

To specify Friendly Name and Office Application Description:

The Friendly Name and Office Application Description properties can be found in the application manifest under the VSTOV3 namespace.

The application manifest (the MySolution.dll.manifest file) will typically be found under the Application Files\MySolution_X_X_X_X\ folder where the X’s describe the latest published version of the solution.

You can open the application manifest and change these properties:

<vstov3:customization xmlns:vstov3="urn:schemas-microsoft-com:vsto.v3">
<vstov3:appAddIn application="Excel" loadBehavior="3" keyName="ExcelAddIn9">
<vstov3:friendlyName>My VSTO Solution</vstov3:friendlyName>
<vstov3:description>A Sample Add-in created to show the add-in properties work</vstov3:description>
</vstov3:appAddIn>
</vstov3:customization>

After you have changed the application manifest, you need to re-sign the application manifest itself. In addition you will also need to refresh the deployment manifest so that it has the new hash for the application manifest. Lastly you need to re-sign the deployment manifest.

The three steps after editing the application manifest can be performed using mage:

Resign application manifest:

Mage –sign applicationmanifest.dll.manifest –Certfile certfile.pfx
Example:
Mage –sign “Application Files\MyVsto_1_0_0_0\myvsto.dll.manifest” –Certfile ..\myvsto.pfx

Update deployment manifest:

Mage –update deploymentmanifest.vsto -AppManifest applicationmanifest.manifest
Example:
Mage –update myvsto.vsto -AppManifest “Application Files\MyVsto_1_0_0_0\myvsto.dll.manifest”

Resign deployment manifest:

Mage –sign deploymentmanifest.vsto –Certfile Certificate.pfx
Example:
Mage –sign MyExcelAddin.vsto –CertFile MyCert.pfx

Your VSTO solution will now have these properties. The downside of this approach is that you will have to perform these manual steps after every publish. If you want to avoid these manual steps, you can make some changes to the VSTO build targets such that these properties are picked up by Visual Studio during publish. The general idea is that you can specify these properties in your Visual Studio project file (the .vbproj or .csproj) which will in turn be picked up by the build tasks so that they are automatically inserted into the manifest for every publish.

Changing your targets file is a risky scenario; if you change something incorrectly, none of your projects will build. So to be safe, the first thing you should do is make backups of the files that you are going to change.

Also to be safe, we will not be editing the main target file but a copy of it. Any VSTO project that you want to specify the publish properties for will use this new modified targets file.

One more thing to consider before modifying the targets file is that your project may not build correctly if you use the modified targets file and later update the Visual Studio version. If you update Visual Studio, you will have to make the corresponding changes in the new Visual Studio targets file.

Creating a backup and modifying the targets file

The file we will be modifying is: Microsoft.VisualStudio.Tools.Office.Office2007.targets,which can be found in the following directory: %ProgramFiles%\MSBuild\Microsoft\VisualStudio\v9.0\OfficeTools

To open the targets file

Create a backup. Copy the file to a safe location (cannot emphasize this enough).
Create another copy that you will be editing.

Create a copy of the file and save it to your Visual Studio 2008 folder under Documents. On Vista : C:\Users\username\Documents\Visual Studio 2008
On XP: C:\My Documents\Visual Studio 2008
Rename the filename to : Microsoft.VisualStudio.Tools.Office.Office2007_Properties.targets
You will be modifying this file for the remaining steps.

3. Open the Microsoft.VisualStudio.Tools.Office.Office2007_Properties.targets file in your favorite text editor.

To change the targets file to support Product Name

In this example, we treat Friendly Name to be the same as Product Name.

Find the comment for Add-in Options section: 
The comment is usually followed by the LoadBehavior tag: <LoadBehavior>3</LoadBehavior>
In the Add-in Options section before the LoadBehavior tag add the following line:
<ProductName Condition=" '$(ProductName)' == '' ">$(TargetName)</ProductName>
Quote sequence:
Condition = <doublequote><singlequote> $(ProductName) <singlequote> == <singlequote><singlequote><doublequote>
Find all instances of FriendlyName. Usually the FriendlyName is assigned to $TargetName: FriendlyName="$(TargetName)"
Change all instances to: FriendlyName = “$(ProductName)”
There will be three places in all where you need to update FriendlyName.
Search for Target GenerateDeploymentManifestForPublishing:
<Target Name="GenerateDeploymentManifestForPublishing">
Inside this target there is a GenerateDeploymentManifest task:
<GenerateDeploymentManifest
EntryPoint="@(ApplicationManifestWithPathForPublishingCollection)"
AssemblyName="$(DeploymentManifestFileName)"
AssemblyVersion="$(PublishVersion)"
MapFileExtensions="$(MapFileExtensions)"
OutputManifest="@(DeploymentManifestWithPathForPublishingCollection)"
Platform="$(PlatformTarget)"
Install="false"
/>
Add a Product attribute to this task:
<GenerateDeploymentManifest
EntryPoint="@(ApplicationManifestWithPathForPublishingCollection)"
AssemblyName="$(DeploymentManifestFileName)"
AssemblyVersion="$(PublishVersion)"
Product="$(ProductName)"
MapFileExtensions="$(MapFileExtensions)"
OutputManifest="@(DeploymentManifestWithPathForPublishingCollection)"
Platform="$(PlatformTarget)"
Install="false"
/>

To change the targets file to support Publisher Name

Search for Target GenerateDeploymentManifestForPublishing:
<Target Name="GenerateDeploymentManifestForPublishing">
Inside this target there is a GenerateDeploymentManifest task:
<GenerateDeploymentManifest
EntryPoint="@(ApplicationManifestWithPathForPublishingCollection)"
AssemblyName="$(DeploymentManifestFileName)"
AssemblyVersion="$(PublishVersion)"
Product="$(ProductName)"
MapFileExtensions="$(MapFileExtensions)"
OutputManifest="@(DeploymentManifestWithPathForPublishingCollection)"
Platform="$(PlatformTarget)"
Install="false"
/>
Add a Publisher attribute to this task:
<GenerateDeploymentManifest
EntryPoint="@(ApplicationManifestWithPathForPublishingCollection)"
AssemblyName="$(DeploymentManifestFileName)"
AssemblyVersion="$(PublishVersion)"
Product="$(ProductName)"
Publisher="$(PublisherName)"
MapFileExtensions="$(MapFileExtensions)"
OutputManifest="@(DeploymentManifestWithPathForPublishingCollection)"
Platform="$(PlatformTarget)"
Install="false"
/>

To changing the targets file to support SupportURL

Search for Target InitializePublishProperties :
<Target Name="InitializePublishProperties">
It is followed by a CreateProperty task:
<CreateProperty Value="Application Files">
<Output PropertyName="ApplicationFilesFolderName" TaskParameter="Value"/>
</CreateProperty>
After the CreateProperty task add the following:
<FormatUrl InputUrl="$(SupportUrl)">
<Output TaskParameter="OutputUrl" PropertyName = "_DeploymentFormattedSupportUrl"/>
</FormatUrl>
Search for Target GenerateDeploymentManifestForPublishing:
<Target Name="GenerateDeploymentManifestForPublishing">
Inside this target there is a GenerateDeploymentManifest task:
<GenerateDeploymentManifest
EntryPoint="@(ApplicationManifestWithPathForPublishingCollection)"
AssemblyName="$(DeploymentManifestFileName)"
AssemblyVersion="$(PublishVersion)"
Product="$(ProductName)"
Publisher="$(PublisherName)"
MapFileExtensions="$(MapFileExtensions)"
OutputManifest="@(DeploymentManifestWithPathForPublishingCollection)"
Platform="$(PlatformTarget)"
Install="false"
/>
Add a Publisher attribute to this task:
<GenerateDeploymentManifest
EntryPoint="@(ApplicationManifestWithPathForPublishingCollection)"
AssemblyName="$(DeploymentManifestFileName)"
AssemblyVersion="$(PublishVersion)"
Product="$(ProductName)"
Publisher="$(PublisherName)"
SupportUrl="$(_DeploymentFormattedSupportUrl)"
MapFileExtensions="$(MapFileExtensions)"
OutputManifest="@(DeploymentManifestWithPathForPublishingCollection)"
Platform="$(PlatformTarget)"
Install="false"
/>

To change the targets file to support Office application description

Search the text file for “OfficeApplicationDescription”
You will find a line as follows:
<OfficeApplicationDescription Condition="'$(VSTO_ProjectType)' == 'Application'">$(TargetName) - $(OfficeApplication) add-in created with Visual Studio Tools for Office</OfficeApplicationDescription>
Modify it to:
<OfficeApplicationDescription Condition="'$(OfficeApplicationDescription)' == '' and '$(VSTO_ProjectType)' == 'Application'">$(TargetName) - $(OfficeApplication) add-in created with Visual Studio Tools for Office</OfficeApplicationDescription>
Note the correct quotes are as follows:
Condition = <doublequote> <singlequote> $(OfficeApplicationDescription) <singlequote> == <singlequote><singlequote>
The very next line after this also needs to be modified:
<OfficeApplicationDescription Condition="'$(VSTO_ProjectType)' == 'Document'">$(TargetName) - $(OfficeApplication) document created with Visual Studio Tools for Office</OfficeApplicationDescription>
Modify it to:
<OfficeApplicationDescription Condition="'$(OfficeApplicationDescription)' == '' and '$(VSTO_ProjectType)' == 'Document'">$(TargetName) - $(OfficeApplication) document created with Visual Studio Tools for Office</OfficeApplicationDescription>
Note the correct quotes are as follows:
Condition = <doublequote> <singlequote> $(OfficeApplicationDescription) <singlequote> == <singlequote><singlequote>

You are done modifying the targets file. The next step is to modify your project file and specify values for these properties. You will have to modify any project that you want to specify these properties for. The Visual Studio projects file is the .vbproj or .csproj file associated with your project. You can open up this file in a text editor.

You will have to modify the project so that it starts using the new targets file which you have created:

Modify project to use new target file

Find the following comment in the projects file:
Replace the existing pointer to the targets file:
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v9.0\OfficeTools\Microsoft.VisualStudio.Tools.Office.Office2007.targets" />
With the path to the new targets file:
<Import Project="c:\users\username\documents\Visual Studio 2008\ Microsoft.VisualStudio.Tools.Office.Office2007_Properties.targets" />

Specify Properties in project file

Inside the first <PropertyGroup> tag you can add the following properties:

<ProductName>My VSTO Solution</ProductName>

<PublisherName>Visual Studio (BizApps)</PublisherName>

<OfficeApplicationDescription>A Sample Add-in created to show the add-in properties work</OfficeApplicationDescription>

<SupportUrl>http://www.microsoft.com</SupportUrl>

Once you have added these properties to the project file you can save the project and open it in Visual Studio. When you open this project you will get a warning stating that the project has been modified to use custom build steps. Choose the option to Load the project normally and proceed. From now onwards, these properties will be automatically be inserted into the manifest during publish. Any updates you make to these properties will also automatically be picked up by the publish system.

Modifying the targets file is a rather long and elaborate procedure, but once you complete it successfully you have the benefit of being able to specify these properties easily for any project.

Hope you find this post useful. Please let us know your comments.

Saurabh Bhatia, Program Manager