Setup Projects

Just found some useful stuff for beginners of VSTO programming. Hope this helps!

This section describes how to enhance the Setup project that is created when you create an Outlook add-in project. In this you learn how to:

  • Modify the Setup project so that it installs the prerequisites: the Visual Studio 2005 Tools for Office Runtime, (optionally) the Visual Studio 2005 Tools for Office Language Pack, and the Office primary interop assemblies.
  • Add a step to the Setup project to grant security trust to the customization assembly.
  • Add launch conditions to the .msi file to prevent installation if the prerequisites are not installed.

Creating the Project

In this step, you create an Outlook add-in project in Visual C#.

To create a new project

  1. Create an Outlook add-in project in Visual C# with the name OutlookAddin.
  2. Verify that Create a new document is selected.Visual Studio opens the new Outlook add-in in the designer and adds the OutlookAddin project to Solution Explorer.

Signing the Assembly

Later in this article, you grant trust to the customization assembly based upon a strong name and its location. However, you must first sign the assembly.

To sign the assembly

  1. In Solution Explorer, right-click the OutlookAddin node, and then click Properties.
  2. Click the Signing tab.
  3. Select the Sign the assembly check box.
  4. In the Choose a strong name key file list, click .
  5. Type the name OutlookAddin into the Key file name box.
  6. Type a password into the Enter password and Confirm password boxes.
  7. Click OK.
  8. Close the Properties pages.

Adding Code to the Add-in

In this step, you add a message box to the Microsoft.Office.Tools.Outlook.Application.Startup event handler of the Outlook add-in. This enables you to verify that the solution is working when you start Outlook.

To add a message box to an initialization event

  1. In Solution Explorer, right-click ThisApplication.cs, and then click View Code.
  2. Add the following code to the ThisApplication_Startup event handler inside the ThisApplication class to show a message box during initialization.
     [Visual C#]
      private void ThisApplication_Startup(object sender,
                System.EventArgs e)
      {
       MessageBox.Show(
          "The Outlook add-in has been deployed successfully.");
      }
  3. Press F5 to run the project.Outlook starts and the message box appears.
  4. Close the message box.
  5. Exit Outlook.

Adding the Prerequisites to the Setup Project

This step relies on you having prepared the development environment.

Add the prerequisites that are installed by the bootstrapper. A later step addresses adding launch conditions.

To add the prerequisites

  1. In Solution Explorer, right-click the OutlookAddinSetup node, and then click Properties.
  2. In the Property Pages dialog box, click the Prerequisites button.
  3. In the list of prerequisites, select Microsoft Office 2003 Primary Interop Assemblies and Microsoft Visual Studio 2005 Tools for Office Runtime.
  4. Select Microsoft Visual Studio 2005 Tools for Office Runtime Language Pack if any users run your solutions with non—nglish settings for Windows. These users must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows.
  5. Click OK twice.

Adding a Custom Action to Grant Trust to the Assembly

Grant trust to the customization assembly using the supplied custom action sample.

To add the supplied project

  1. Using Windows Explorer, copy the SetSecurity project from the {SamplesDir}\projects directory to the directory containing the OutlookAddin Solution.
    Tip: By default, the {SamplesDir} directory is C:\Program Files\Microsoft Visual Studio 2005 Tools for Office Resources\VSTO2005 Windows Installer Sample
  2. In Solution Explorer, right-click the OutlookAddin node.
  3. Point to Add on the shortcut menu, and then click Existing Project.
  4. Select the SetSecurity project.
  5. Click OK.
  6. In Solution Explorer, right-click the SetSecurity project, and then click Build.
  7. Add the primary output of the SetSecurity project to the Setup project.This enables the Windows Installer file to run the custom action that edits the application manifest.

To add the primary output of the custom action project to the Setup project

  1. In Solution Explorer, right-click the OutlookAddinSetup node.
  2. Point to View on the shortcut menu, and then click Custom Actions.
  3. In the Custom Actions editor, right-click the Custom Actions node, and then click Add Custom Action.
  4. In the Look In list, click Application Folder, and then click Add Output.The Add Project Output Group dialog box opens.
  5. Click SetSecurity in the Project list.
  6. Select Primary output from the list of output types, and then click OK.
  7. Verify that Primary output from SetSecurity (Active) is added to the list of primary outputs for the Setup project, and then click OK.
  8. Add the required custom action data.

To add the custom action data for the Install method

  1. In the Custom Actions editor, expand Install.
  2. Right-click Primary output from SetSecurity (Active), and then click Properties Window.
  3. In the Properties window, set the CustomActionData property to the following string:
       /assemblyName="OutlookAddin.dll" /targetDir="[TARGETDIR]\"
       /solutionCodeGroupName="MyCompanyName.OutlookAddin"
       /solutionCodeGroupDescription="Code group for OutlookAddin"
       /assemblyCodeGroupName="OutlookAddin"
       /assemblyCodeGroupDescription="Code group for OutlookAddin"
       /allUsers=[ALLUSERS]

To add the custom action data for the Rollback method

  1. In the Custom Actions editor, expand Rollback.
  2. Right-click Primary output from SetSecurity (Active), and then click Properties Window.
  3. In the Properties window, set the CustomActionData property to the following string:
    /solutionCodeGroupName="MyCompanyName.OutlookAddin"

To add the custom action data for the Uninstall method

  1. In the Custom Actions editor, expand Uninstall.
  2. Right-click Primary output from SetSecurity (Active), and then click Properties Window.
  3. In the Properties window, set the CustomActionData property to the following string:
    /solutionCodeGroupName="MyCompanyName.OutlookAddin"

Note Although the Commit method was not overridden by the custom action, the base Windows Installer class provides an implementation. Thus, you must still call the method. However, it does not require any custom action data.

Adding Launch Conditions to the .msi File

Recall that when the user runs Setup.exe, the Windows Installer checks for the prerequisites, and installs them if necessary. Alternatively, the user can double-click the .msi file to install the solution. In that case, the prerequisites are not installed and the solution cannot run. In other cases, Setup might fail because resources it needs are not present; for example, custom actions might require the .NET Framework.

This section shows you how to use the Launch Conditions editor to add launch conditions to the .msi file to prevent installation if certain dependencies are not installed.

To view the Launch Conditions editor

  1. In Solution Explorer, right-click the OutlookAddinSetup node.
  2. Point to View on the shortcut menu, and then click Launch Conditions.

Add a launch condition for the Visual Studio 2005 Tools for Office Runtime.

To add a launch condition for the Visual Studio 2005 Tools for Office Runtime

  1. In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Windows Installer Launch Condition.
  2. Select the newly added search condition, Search for Component1.
  3. Rename the search condition to Search for VSTO Runtime.
  4. In the Properties window, type {D2AC2FF1-6F93-40D1-8C0F-0E135956A2DA} into the ComponentId property.
  5. Change the value of Property to COMPONENTEXISTS_VSTOR.
  6. Select the newly added launch condition, (Condition1).
  7. Rename it to Display message, if the Visual Studio 2005 Tools for Office Runtime is not installed.
  8. In the Properties window, change the value of the Condition property to COMPONENTEXISTS_VSTOR.
  9. Leave the InstallURL property blank.
  10. Change the value of the Message property to The Visual Studio 2005 Tools for Office Runtime is not installed. Please run Setup.exe.

If any users run your solutions with non—nglish settings for Windows, they must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows. Add a launch condition to check for the Language Pack.

To add a launch condition for the Visual Studio 2005 Tools for Office Language Pack

  1. In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Windows Installer Launch Condition.
  2. Select the newly added search condition, Search for Component1.
  3. Rename the search condition to Search for VSTO Language Pack.
  4. In the Properties window, type {2E3A394E-C9BD-40C3-9990-BA7AF7C8B4AF} into the ComponentId property.
  5. Change the value of Property to COMPONENTEXISTS_VSTOLP.
  6. Select the newly added launch condition, (Condition1).
  7. Rename it to Display message if the Visual Studio 2005 Tools for Office Language Pack is not installed.
  8. In the Properties window, change the value of the Condition property to COMPONENTEXISTS_VSTOLP.
  9. Leave the InstallURL property blank.
  10. Change the value of the Message property to The Visual Studio 2005 Tools for Office Language Pack is not installed. Please run Setup.exe.

Follow these instructions to add a launch condition for the Excel, Outlook, Word, and Smart Tag primary interop assemblies.

Tip In practice, your solution may require a different set of primary interop assemblies. For example, the Excel solution deployed in this walkthrough only requires the Outlook 2003 primary interop assemblies. You can modify the following instructions to add or remove checks for individual primary interop assemblies as required.

When you create the launch conditions for the Visual Studio 2005 Tools for Office Runtime and the Visual Studio 2005 Tools for Office Language Pack, you must right-click the Requirements on Target Machine node. This created both the search condition and the corresponding launch condition.

To create a launch condition to search for four primary interop assemblies, you must create four separate search conditions (one for each primary interop assembly) and then one launch condition that logically combines the four search conditions.

To add a search condition for the Excel 2003 primary interop assembly

  1. In the Launch Conditions editor, right-click Search Target Machine, and then select Add Windows Installer Search.
  2. Select the newly added search condition, Search for Component1.
  3. Rename the search condition to Search for Excel 2003 PIA.
  4. In the Properties window, type {A1FE0698-609D-400F-BF10-F52238DD6475} into the ComponentId property.
  5. In the Properties window, change the value of Property to COMPONENTEXISTS_EXCEL_PIA.

To add a search condition for the Outlook 2003 primary interop assembly

  1. In the Launch Conditions editor right-click Search Target Machine, and then select Add Windows Installer Search.
  2. Select the newly added search condition, Search for Component1.
  3. Rename the search condition to Search for Outlook 2003 PIA.
  4. In the Properties window, type {14D3E42A-A318-4D77-9895-A7EE585EFC3B} into the ComponentId property.
  5. Change the value of Property to COMPONENTEXISTS_OUTLOOK_PIA.

To add a search condition for the Word 2003 primary interop assembly

  1. In the Launch Conditions editor, right-click Search Target Machine, and select Add Windows Installer Search.
  2. Select the newly added search condition, Search for Component1.
  3. Rename the search condition to Search for Word 2003 PIA.
  4. In the Properties window, type {1C8772BD-6E6F-4C9D-8FF8-B5EA072F86EF} into the ComponentId property.
  5. Change the value of Property to COMPONENTEXISTS_WORD_PIA.

To add a search condition for the Smart Tag primary interop assembly

  1. In the Launch Conditions editor right-click Search Target Machine, and then select Add Windows Installer Search.
  2. Select the newly added search condition, Search for Component1.
  3. Rename the search condition to Search for Smart Tag PIA.
  4. In the Properties window, type {53C65973-D89D-4EA0-8567-8788C14E0A02} into the ComponentId property.
  5. Change the value of Property to COMPONENTEXISTS_SMART_TAG_PIA.

To create a launch condition for the primary interop assemblies

  1. In the Launch Conditions editor right-click Launch Conditions, and then select Add Launch Condition.
  2. Select the newly added launch condition, (Condition1).
  3. Rename it to Display message if the Primary Interop Assemblies are not installed.
  4. In the Properties window, change the value of the Condition property to COMPONENTEXISTS_EXCEL_PIA AND COMPONENTEXISTS_OUTLOOK_PIA AND COMPONENTEXISTS_WORD_PIA AND COMPONENTEXISTS_SMART_TAG_PIA.
  5. In the Properties window, leave the InstallURL property blank.
  6. Change the value of the Message property to The Office 2003 Primary Interop Assemblies have not been installed Please run setup.exe.

Testing the Installation

To test your Windows Installer, you must run it on a computer other than your development computer, because many of the prerequisites are already installed. Remember to run the Setup.exe file to test the bootstrapper. Remember first to build your Setup project.

To build Setup

  • In Solution Explorer, right-click the OutlookAddinSetup project, and then click Build.