共用方式為


Part 4: Building an Installation Package for a Real Outlook Social Connector Provider

Office Visual How To

Summary:  Learn how to create a Microsoft Windows Installer (.msi) package to deploy a custom Microsoft Outlook Social Connector provider.

Applies to: Office 2007 | Office 2010 | Outlook | Outlook 2007 QFE 2276479 | Outlook 2010 | Visual Studio

Published:  January 2011

Provided by:  Michael Case, iSoftStone | Angela Chu-Hatoun, Microsoft Corporation | Patrick Creehan, Microsoft Corporation

Overview

The recommended method to deploy a Microsoft Outlook Social Connector (OSC) provider is to use a Microsoft Windows Installer (.msi) package. After downloading the installation package to a local hard disk, the Outlook end user installs the OSC provider. Once provider installation is complete, the user can connect to the OSC provider and provide logon credentials to their social network account. If the user decides to uninstall the OSC provider, the user can use Programs and Features in the Control Panel to uninstall.

This Visual How To uses the sample OfficeTalk OSC provider written for this series of Visual How Tos as an example, and shows the steps necessary for building an installation package for this OSC provider. These steps include the following:

  1. Creating a custom prerequisites package to install the latest version of the OSC.

  2. Adding a custom installer class to the OSC provider project.

  3. Adding a setup project to the OSC provider solution.

This Visual How To does not show how to create the OSC provider solution nor how to return information from a social network. This Visual How To focuses on creating an installation package for the sample OSC provider. You can use similar techniques to create an installation package for any OSC provider.

Code It

This Visual How To will walk you through the following steps to show how to create an installation package for an OSC provider:

  1. Create a custom prerequisite package to install OSC version 1.1.

  2. Add a custom installer to the OfficeTalkOSCProvider project.

  3. Create an override for the Commit method.

  4. Create an override for the OnBeforeUninstall method.

  5. Create the IsOffice64Bit helper method.

  6. Create the GetRegasmPath helper method.

  7. Create the GetOscProvidersKeyLocation helper method.

  8. Add a setup project to the sample solution.

  9. Add the OSC provider project output to the setup project.

  10. Define custom actions for the setup project.

  11. Define setup launch conditions for the setup project.

  12. Test the installation package.

Creating a Custom Prerequisite Package for OSC Version 1.1

The OSC provider in the sample solution that was written for this series of Visual How Tos requires a custom prerequisite package to ensure that the OSC version 1.1 is installed. The setup project, which you will add to the sample solution later, references the prerequisite package.

A custom prerequisite package includes a set of XML manifest files that specify the metadata to manage the installation of the component. The following files are included in the manifest:

  1. A product manifest, Product.xml, which contains any language-neutral metadata for the package. This contains metadata that is common to all the localized versions of the redistributable component.

  2. Package manifests, Package.xml, which contain locale-specific metadata. A component must have at least one package manifest for each localized version of the component.

For this Visual How To, you will create a product manifest file and a single package manifest file for English.

To be visible to Visual Studio 2010 setup projects, custom prerequisite manifest files must be located in a specific folder. On 32-bit computers, the folder is C:\Program Files\Microsoft SDKs\Windows\v7.0A\Bootstrapper\Packages. On 64-bit computers, the folder is C:\Program Files (86)\Microsoft SDKs\Windows\v7.0A\Bootstrapper\Packages. Each prerequisite package appears in its own subfolder under the Packages folder.

For the OSC 1.1, create a subfolder named OutlookSocialConnector1_1 (on a 32-bit computer, that is C:\Program Files\Microsoft SDKs\Windows\v7.0A\Bootstrapper\Packages\OutlookSocialConnector1_1). The Product.xml file, further described in the following section, is located in this folder.

Product Manifests

The Product.xml file defines a Product element, which is the top-level element in the product file. The Product element sets the ProductCode, which is the unique identifier for the product, to OSC.Install_V1.1.

The Product element contains a RelatedProducts element, which shows that the OSC 1.1 installation depends on the Windows Installer version 3.1.

The Product element also contains a set of RegistryChecks that identify the current version of the OSC, the current version of Office that is installed, and the bitness of the Office installation. These registry key values are used in the Package.xml file, described in the following section, to determine whether version 1.1 of the OSC needs to be installed and, if so, which installation file should be used.

Note

64-bit versions of Office run only on 64-bit versions of Windows. For 64-bit versions of Office, you must create an executable file that evaluates the 64-bit registry keys and modify this file to use an ExternalCheck to evaluate the results.

The following XML is an example of the product manifest.

<?xml version="1.0" encoding="utf-8"?>
<Product
    xmlns="https://schemas.microsoft.com/developer/2004/01/bootstrapper"
    ProductCode="OSC.Install_V1.1">

    <RelatedProducts>
        <DependsOnProduct Code="Microsoft.Windows.Installer.3.1"/>
    </RelatedProducts>

    <InstallChecks>
        <!--Outlook Social Connector version-->
        <RegistryCheck Property="OSCVersion"
                       Key="HKLM\Software\Microsoft\Office\Outlook\SocialConnector"
                       Value="OSCVersion"/>
        <!--Office version-->
        <RegistryCheck Property="OfficeVersion"
                       Key="HKLM\Software\Microsoft\Office\Common"
                       Value="LastAccessInstall"/>
        <!--Outlook 2010 bitness-->
        <RegistryCheck Property="Outlook14Bitness"
                       Key="HKLM\Software\Microsoft\Office\14.0\Outlook"
                       Value="Bitness"/>
    </InstallChecks>
</Product>

Package Manifests

Package manifests are locale-specific and are located in subfolders named after each supported locale. This Visual How To defines a Package.xml file only for English. For this Visual How To, create a subfolder with the name of en for the Package.xml file.

The Package.xml file defines a Package element, which is the top-level element in the package file. The Package element sets the Name attribute to display in the Prerequisites dialog box for setup projects and the package file's Culture attribute.

The Package element contains a set of PackageFile elements, with each PackageFile element representing an OSC installation package that might be installed. Third parties, including OSC providers, cannot redistribute the OSC directly. However, the provider installer can use appropriate g-links to install the OSC on the client computer. A g-link is a specially constructed URL on http://g.live.com that forwards the user to a corresponding webpage to download the OSC. An OSC g-link is formatted as http://g.live.com/0CRLCID/Glink, where LCID and Glink specify the locale, version, and bitness of Outlook on the client computer. Each g-link points to an executable file and is specific to the specified LCID and Glink values.

For this Visual How To, the PackageFile elements define g-links to download the correct version of the OSC for English (LCID 1033). There are PackageFile elements defined for the following versions and bitness of Outlook:

  • The latest version of the 32-bit OSC for Outlook 2003 and 2007.

  • The latest version of the 32-bit OSC for Outlook 2010.

  • The latest version of the 64-bit OSC for Outlook 2010.

For more information about other available locales, see Installation Checklist in the Outlook Social Connector 1.1 Provider Reference.

The Package element also contains a set of Command elements that determine whether the latest version of the OSC version 1.1 needs to be installed and, if so, which PackageFile element should be used for the installation. Each Command element defines a set of InstallConditions elements that evaluate the RegistryCheck values specified in the Product.xml file. The Command element skips installing the latest version of the OSC if OSC 1.1 is already installed, or if the PackageFile element referenced is not for the version of Outlook that is installed on the local computer.

The Command elements check the following scenarios:

  • Outlook 2003 is installed.

  • Outlook 2007 is installed.

  • Outlook 2010 32-bit is installed.

  • Outlook 2010 64-bit is installed.

The following XML is an example of the package manifest.

<?xml version="1.0" encoding="utf-8" ?>
<Package
    xmlns="https://schemas.microsoft.com/developer/2004/01/bootstrapper"
    Name="Outlook Social Connector v1.1"
    Culture="en">

    <PackageFiles>
        <!--G-link to install the latest version of the 32-bit OSC 
            (English version) for Outlook 2003 and Outlook 2007.-->
        <PackageFile Name="outlooksocialconnector-x86-en-us.exe"
                     HomeSite="http://g.live.com/0cr1033/80"
                     PublicKey="3082010a0282010100bd3089fb4572a8536b9e894f0023c0bed41d3db1594038f373918226e6961200
53d91c820e3cce1dbbbdf7428d97d4fc381ae4b9f9e3ecd36103bfa0d3d6754d5c46a9ed5ef0d2e2695b1a73eab31c8d04cd2944a064592f1e
985d6ec7ab18398265c4a7bcab758819ea87971426b37f2676a4d4383984e3b326d518f92be9d2c9165a5421f2978d878629fef4492ce68bf8
043f7dcdcd9692860d7103e2d0fe0c4235ffd7b83fdd8e450a7df6d74bad5bf076721d77237d8935c41c5db250034b476d07a75588980680a6
81ad544ed881d6fabf42c031be550d99d553491230ebe5a5887c5ec47a5a148708b43769a0eb32248c08ebf9d414bae0fccdeaa4150203010001"/>
        <!--G-link to install the latest version of the 32-bit OSC 
            (English version) for Outlook 2010.-->
        <PackageFile Name="osc-kb983403-fullfile-x86-en-us.exe"
                     HomeSite ="http://g.live.com/0cr1033/82"
                     PublicKey="3082010a0282010100bd3089fb4572a8536b9e894f0023c0bed41d3db1594038f373918226e696
120053d91c820e3cce1dbbbdf7428d97d4fc381ae4b9f9e3ecd36103bfa0d3d6754d5c46a9ed5ef0d2e2695b1a73eab31c8d04cd2944a0
64592f1e985d6ec7ab18398265c4a7bcab758819ea87971426b37f2676a4d4383984e3b326d518f92be9d2c9165a5421f2978d878629fe
f4492ce68bf8043f7dcdcd9692860d7103e2d0fe0c4235ffd7b83fdd8e450a7df6d74bad5bf076721d77237d8935c41c5db250034b476d
07a75588980680a681ad544ed881d6fabf42c031be550d99d553491230ebe5a5887c5ec47a5a148708b43769a0eb32248c08ebf9d414ba
e0fccdeaa4150203010001"/>
        <!--G-link to install the latest version of the 64-bit OSC 
            (English version) for Outlook 2010.-->
        <PackageFile Name="osc-kb983403-fullfile-x64-en-us.exe"
                     HomeSite ="http://g.live.com/0cr1033/83"
                     PublicKey="3082010a0282010100bd3089fb4572a8536b9e894f0023c0bed41d3db1594038f373918226e69
6120053d91c820e3cce1dbbbdf7428d97d4fc381ae4b9f9e3ecd36103bfa0d3d6754d5c46a9ed5ef0d2e2695b1a73eab31c8d04cd2944
a064592f1e985d6ec7ab18398265c4a7bcab758819ea87971426b37f2676a4d4383984e3b326d518f92be9d2c9165a5421f2978d87862
9fef4492ce68bf8043f7dcdcd9692860d7103e2d0fe0c4235ffd7b83fdd8e450a7df6d74bad5bf076721d77237d8935c41c5db250034b
476d07a75588980680a681ad544ed881d6fabf42c031be550d99d553491230ebe5a5887c5ec47a5a148708b43769a0eb32248c08ebf9d
414bae0fccdeaa4150203010001"/>
    </PackageFiles>

    <Commands>
        <!--Install latest OSC for Outlook 2003.-->
        <Command PackageFile="outlooksocialconnector-x86-en-us.exe">
            <InstallConditions>
                <!--Install if the OSC version is less than 1.1 and 
                    the Office version is 2003.-->
                <BypassIf Property="OSCVersion" Compare="VersionGreaterThanOrEqualTo" Value="1.1"/>
                <BypassIf Property="OfficeVersion" Compare="ValueNotExists"/>
                <BypassIf Property ="OfficeVersion" Compare="ValueNotEqualTo" Value="11.0"/>
            </InstallConditions>
            <ExitCodes>
                <ExitCode Value="0" Result="Success"/>
                <ExitCode Value="1641" Result="SuccessReboot"/>
                <ExitCode Value="3010" Result="SuccessReboot"/>
                <DefaultExitCode Result="Fail" String="GeneralFailure"/>
            </ExitCodes>
        </Command>
        <!--Install latest OSC for Outlook 2007.-->
        <Command PackageFile="outlooksocialconnector-x86-en-us.exe">
            <InstallConditions>
                <!--Install if the OSC version is less than 1.1 and 
                    the Office version is 2007.-->
                <BypassIf Property="OSCVersion" Compare="VersionGreaterThanOrEqualTo" Value="1.1"/>
                <BypassIf Property="OfficeVersion" Compare="ValueNotExists"/>
                <BypassIf Property ="OfficeVersion" Compare="ValueNotEqualTo" Value="12.0"/>
            </InstallConditions>
            <ExitCodes>
                <ExitCode Value="0" Result="Success"/>
                <ExitCode Value="1641" Result="SuccessReboot"/>
                <ExitCode Value="3010" Result="SuccessReboot"/>
                <DefaultExitCode Result="Fail" String="GeneralFailure"/>
            </ExitCodes>
        </Command>
        <!--Install latest OSC for Outlook 2010 32-bit.-->
        <Command PackageFile="osc-kb983403-fullfile-x86-en-us.exe">
            <InstallConditions>
                <!--Install if the OSC version is less than 1.1 and 
                    the Office version is 2010 and 
                    Office is 32-bit.-->
                <BypassIf Property="OSCVersion" Compare="VersionGreaterThanOrEqualTo" Value="1.1"/>
                <BypassIf Property="OfficeVersion" Compare="ValueNotExists"/>
                <BypassIf Property ="OfficeVersion" Compare="ValueNotEqualTo" Value="14.0"/>
                <BypassIf Property ="Outlook14Bitness" Compare="ValueNotEqualTo" Value="x86"/>
            </InstallConditions>
            <ExitCodes>
                <ExitCode Value="0" Result="Success"/>
                <ExitCode Value="1641" Result="SuccessReboot"/>
                <ExitCode Value="3010" Result="SuccessReboot"/>
                <DefaultExitCode Result="Fail" String="GeneralFailure"/>
            </ExitCodes>
        </Command>
        <!--Install latest OSC for Outlook 2010 64-bit-->
        <Command PackageFile="osc-kb983403-fullfile-x64-en-us.exe">
            <InstallConditions>
                <!--Install if the OSC version is less than 1.1 and 
                    the Office version is 2010 and 
                    Office is 64-bit.-->
                <!--NOTE: 64-bit versions of Office run only on 64-bit 
                    versions of Windows. For 64-bit versions of Windows, 
                    you must create an executable that evaluates the
                    64-bit registry keys and modify the Product.xml file to 
                    use an ExternalCheck to evaluate the results. Then
                    modify these InstallConditions to use the results.-->
                <BypassIf Property="OSCVersion" Compare="VersionGreaterThanOrEqualTo" Value="1.1"/>
                <BypassIf Property="OfficeVersion" Compare="ValueNotExists"/>
                <BypassIf Property ="OfficeVersion" Compare="ValueNotEqualTo" Value="14.0"/>
                <BypassIf Property ="Outlook14Bitness" Compare="ValueNotEqualTo" Value="x64"/>
            </InstallConditions>
            <ExitCodes>
                <ExitCode Value="0" Result="Success"/>
                <ExitCode Value="1641" Result="SuccessReboot"/>
                <ExitCode Value="3010" Result="SuccessReboot"/>
                <DefaultExitCode Result="Fail" String="GeneralFailure"/>
            </ExitCodes>
        </Command>
    </Commands>
</Package>

Adding an Installer to the OfficeTalkOSCProvider Project

Next you will add a custom installer for the OSC provider. When the OSC provider is installed, the custom installer registers the OSC provider and adds the registry keys that are required for the OSC to find the OSC provider. When the OSC provider is uninstalled, the custom installer unregisters the OSC provider and removes the registry settings that were added during the installation process.

To add a custom installer to the OfficeTalkOSCProvider project

  1. Open the sample solution in Visual Studio 2010.

  2. Right-click the OfficeTalkOSCProvider project, point to Add, and then click New Item.

  3. In the Add New Item dialog box, select the Installer class, type a name of OfficeTalkOSCProviderInstaller, and click the Add button.

Now add a reference to the System.Configuration.Install assembly to the OfficeTalkOSCProvider project.

To add a reference to the System.Configuration.Install assembly

  1. Right-click the OfficeTalkOSCProvider project's References folder, and then click Add Reference.

  2. In the Add Reference dialog box, select the .NET tab, select the System.Configuration.Install assembly, and then click the OK button.

Add the following using statements to the top of the OfficeTalkOSCProviderInstaller source code file. These using statements support registering the OSC provider assembly and adding the required registry keys.

using Microsoft.Win32;
using System.Runtime.InteropServices;
using System.Diagnostics;

Creating the Commit Override Method

Override the custom installer's Commit method (shown in the following code), which is called after the installation is complete, to register the OSC provider and to add the required registry keys. The code completes the following steps:

  1. The Commit method first calls the base class's Commit method.

  2. The Commit method registers the OSC provider.

    1. It calls a helper method, GetRegasmPath, to get the correct Regasm.exe version to use based on the current common language runtime (CLR) version, Office bitness, and Windows bitness.

    2. The Commit method creates the command-line arguments that are used to register the OSC provider.

    3. Finally, the Commit method calls Regasm.exe to register the OSC provider.

  3. The Commit method adds the registry keys for the OSC provider.

    1. It calls a helper method, GetOscProvidersKeyLocation, to get the location of the OSC Social Providers registry key.

    2. The Commit method determines whether the OSC provider is being installed for all users.

      If the OSC provider is being installed for all users, the Commit method creates the registry keys in the local machine registry hive. Otherwise, it creates the registry keys in the current user registry hive.

    3. Finally, the Commit method opens the OSC Social Providers registry key and adds the registry keys required for the OSC to recognize the OSC provider.

  4. The Commit method creates a subkey for the OSC provider in the OSC Social Providers registry key by using the OSC provider's type.

  5. The Commit method then sets the OSC provider's registry key's FriendlyName and Url values.

The following code is an example of the Commit override method.

[System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
public override void Commit(IDictionary savedState)
{
    base.Commit(savedState);

    // Register the OSC Provider.
    // Get the correct Regasm.exe version to use.
    String regasmPath = GetRegasmPath();

    // Create the Regasm.exe command-line arguments.
    String regasmArgs =
        String.Format(@"/codebase ""{0}""", this.GetType().Assembly.Location);

    // Call Regasm.exe to register the provider.
    Process process = Process.Start(regasmPath, regasmArgs);
    
    // Wait a maximum of 15 seconds for Regasm.exe to complete.
    process.WaitForExit(15000);


    // Add the registry keys for this OSC provider.
    // Get the location of the OSC Social Providers key.
    // The path to the OSC Social Providers key will be in the Wow6432Node
    // branch if 32-bit Office is installed on a 64-bit OS.
    String oscProvidersLocation = GetOscProvidersKeyLocation();

    // Add registry keys to the local machine hive if installing 
    // for everyone; otherwise, install to the current user hive.
    RegistryKey hive = null;
    RegistryKey oscProvidersKey = null;
    if (this.Context.Parameters["InstallAllUsers"] == "1")
    {
        hive = Registry.LocalMachine;
    }
    else
    {
        hive = Registry.CurrentUser;
    }

    // Open the OSC Social Providers key.
    oscProvidersKey = hive.CreateSubKey(oscProvidersLocation);
    if (oscProvidersKey != null)
    {
        // Add the keys for this OSC provider.
        RegistryKey providerKey =
            oscProvidersKey.CreateSubKey(@"OfficeTalkOSCProvider.OTProvider");

        if (providerKey != null)
        {
            providerKey.SetValue("FriendlyName", 
                "OfficeTalkOSCProvider", 
                RegistryValueKind.String);
            providerKey.SetValue("Url", 
                "http://yoururl", 
                RegistryValueKind.String);
        }
    }
}

Creating the OnBeforeUninstall Override Method

Override the custom installer's OnBeforeUninstall method, shown in the following code, to unregister the OSC provider and to remove the registry keys that were added during the installation process. The code completes the following steps:

  1. The OnBeforeUninstall method first calls the base class's OnBeforeUninstall method.

  2. The OnBeforeUninstall method unregisters the OSC provider.

    1. It calls a helper method, GetRegasmPath, to get the correct Regasm.exe version to use based on the current CLR version, Office bitness, and Windows bitness.

    2. The OnBeforeUninstall method creates the command-line arguments that are used to unregister the OSC provider.

    3. Finally, the Commit method calls Regasm.exe to unregister the OSC provider.

  3. OnBeforeUninstall removes the registry keys for the OSC provider.

    1. It calls the GetOscProvidersKeyLocation method to get the location of the OSC Social Providers registry key.

    2. The OnBeforeUninstall method determines whether the OSC provider was installed for all users.

      If the OSC provider was installed for all users, the OnBeforeUninstall method removes the registry keys from the local machine registry hive. Otherwise, it removes the registry keys from the current user registry hive.

    3. Finally, the OnBeforeUninstall method opens the OSC Providers registry key and deletes the OSC provider registry keys that were added during installation.

The following code is an example of the OnBeforeUninstall override method.

[System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
protected override void OnBeforeUninstall(IDictionary savedState)
{
    base.OnBeforeUninstall(savedState);

    // Unregister the OSC Provider.
    // Get the correct Regasm.exe version to use.
    String regasmPath = GetRegasmPath();

    // Create the Regasm.exe command-line arguments.
    String regasmArgs =
        String.Format(@"/unregister ""{0}""", 
            this.GetType().Assembly.Location);
    
    // Call Regasm.exe to unregister the provider.
    Process process = Process.Start(regasmPath, regasmArgs);
    
    // Wait a maximum of 15 seconds for Regasm.exe to complete.
    process.WaitForExit(15000);


    // Remove the registry keys for this OSC provider.
    // Get the location of the OSC Social Providers key.
    // The path to the OSC Social Providers key will be in the Wow6432Node 
    // branch if 32-bit Office is installed on a 64-bit OS.
    string oscProvidersLocation = GetOscProvidersKeyLocation();

    // Remove registry keys from the local machine hive if installing
    // for everyone; otherwise, remove from the current user hive.
    RegistryKey hive = null;
    RegistryKey oscProvidersKey = null;
    if (this.Context.Parameters["InstallAllUsers"] == "1")
    {
        hive = Registry.LocalMachine;
    }
    else
    {
        hive = Registry.CurrentUser;
    }

    // Open the OSC Social Providers key.
    oscProvidersKey = hive.OpenSubKey(oscProvidersLocation, true);

    if (oscProvidersKey != null)
    {
        // Remove the keys for this OSC provider.
        oscProvidersKey.DeleteSubKeyTree("OfficeTalkOSCProvider.OTProvider", 
            false);
    }
}

Creating the IsOffice64Bit Helper Method

The IsOffice64Bit helper method, shown in the following code, identifies whether a 64-bit version of Office is installed. The code completes the following steps:

  1. The IsOffice64Bit helper method first checks whether the operating system is 64-bit.

    • If the operating system is not 64-bit, the installed version of Office cannot be 64-bit, and the IsOffice64Bit method returns false.

    • If the operating system is 64-bit, the IsOffice64Bit method then checks the bitness of the Office installation.

      1. To check the bitness of the Office installation, the GetOscProvidersKeyLocation method first evaluates the Software\Microsoft\Office\Common\LastAccessInstall registry key value to determine the current version of Office that is installed.

      2. If the version of Office that is installed is not available at that registry location, the IsOffice64Bit helper method evaluates the Software\Wow6432Node\Microsoft\Office\Common\LastAccessInstall registry key value to determine the current version of Office that is installed.

  2. The IsOffice64Bit method then opens the Outlook registry key that is associated with the current version of Office that is installed.

    For Outlook 2010, the location is Software\Microsoft\Office\14.0\Outlook.

  3. Finally, the GetOscProvidersKeyLocation method evaluates the Outlook registry key's Bitness value.

    If the Bitness value is x64, the IsOffice64Bit method returns true; otherwise, it returns false.

The following code is an example of the IsOffice64Bit helper method.

private static bool IsOffice64Bit()
{
    // Determine whether a 64-bit operating system is in use.
    bool is64bitOS = System.Environment.Is64BitOperatingSystem;

    // If the operating system is not a 64-bit, Office cannot be 64-bit.
    if (!is64bitOS)
    {
        return false;
    }

    // Outlook bitness is stored in the Outlook version branch.
    // Get the version of Outlook currently installed.
    int officeVersion = 0;
    RegistryKey hive =
        RegistryKey.OpenBaseKey(RegistryHive.LocalMachine,
        RegistryView.Registry64);

    // Find the version of Office installed.
    // Check the 64-bit registry key.
    RegistryKey officeKey =
        hive.OpenSubKey(@"Software\Microsoft\Office\Common");
    officeVersion =
        (int)officeKey.GetValue("LastAccessInstall", 0);

    // If the Office version was not found, check the 32-bit registry key.
    if (officeVersion == 0)
    {
        officeKey =
            hive.OpenSubKey(@"Software\Wow6432Node\Microsoft\Office\Common");
        officeVersion =
            (int)officeKey.GetValue("LastAccessInstall", 0);
    }

    // Find the Outlook bitness.
    String officeKeyLocation =
        String.Format(@"Software\Microsoft\Office\{0}.0\Outlook",
        officeVersion);
    RegistryKey versionedKey = hive.OpenSubKey(officeKeyLocation);
    String bitness = versionedKey.GetValue("Bitness", String.Empty).ToString();

    // Return true if Outlook is 64-bit; otherwise, return false.
    if (bitness == "x64")
    {
        return true;
    }
    else
    {
        return false;
    }
}

Creating the GetRegasmPath Helper Method

The GetRegasmPath helper method, shown in the following code, returns the full path to the correct version of Regasm.exe based on the current CLR version, Office bitness, and Windows bitness. The code completes the following steps:

  1. The GetRegasmPath helper method first initializes variables that are used to build the Regasm.exe path.

  2. The GetRegasmPath method determines whether the operating system is 64-bit, and calls the IsOffice64Bit helper method to determine whether Office is 64-bit.

    • If the operating system is 64-bit, the GetRegasmPathHelper method determines the installation locations of the 32-bit and 64-bit .NET Framework. To get the installation location of the 32-bit .NET Framework, the GetRegasmPath method opens the local machine registry hive in a 32-bit view and then evaluates the Software\Wow6432Node\Microsoft\.NETFramework\InstallRoot registry key value. To get the installation location of the 64-bit .NET Framework, the GetRegasmPath method opens the local machine registry hive in a 64-bit view and then evaluates the local machine Software\Microsoft\.NETFramework\InstallRoot registry key value.

    • If the operating system is 32-bit, there is only a 32-bit view of the registry, and the GetRegasmPath method evaluates the local machine Software\Microsoft\.NETFramework\InstallRoot registry key value to get the installation location of the 32-bit .NET Framework.

  3. The GetRegasmPath method determines the current CLR version.

  4. GetRegasmPath builds the path to the correct version of Regasm.exe to use based on the current CLR version, Office bitness, and Windows bitness.

  5. The method then returns the path to Regasm.exe.

The following code is an example of the GetRegasmPath helper method.

private static string GetRegasmPath()
{
    // Variables used to build the Regasm.exe path.
    string regasmPath = String.Empty;
    string runtimeFolder32 = String.Empty;
    string runtimeFolder64 = String.Empty;

    // Determine whether a 64-bit operating system is in use.
    bool is64bitOS = System.Environment.Is64BitOperatingSystem;

    // Determine whether Office is 64-bit.
    bool isOutlook64bit = IsOffice64Bit();

    // If the operating system is 64-bit, locate both the 32-bit 
    // and 64-bit versions of Regasm.exe.
    if (is64bitOS)
    {
        // Get the 32-bit runtime folder.
        RegistryKey hive32 =
            RegistryKey.OpenBaseKey(RegistryHive.LocalMachine, 
                RegistryView.Registry32);
        RegistryKey hklmRuntime32Key =
            hive32.OpenSubKey(@"Software\Wow6432Node\Microsoft\.NETFramework");
        runtimeFolder32 =
            hklmRuntime32Key.GetValue("InstallRoot", 
                String.Empty).ToString();

        // Get the 64-bit runtime folder.
        RegistryKey hive64 =
            RegistryKey.OpenBaseKey(RegistryHive.LocalMachine, 
                RegistryView.Registry64);
        RegistryKey hklmRuntime64Key =
            hive64.OpenSubKey(@"Software\Microsoft\.NETFramework");
        runtimeFolder64 =
            hklmRuntime64Key.GetValue("InstallRoot", 
                String.Empty).ToString();
    }
    else
    {
        // Get the 32-bit runtime folder.
        runtimeFolder32 = Registry.GetValue(
            @"HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework",
            "InstallRoot",
            String.Empty).ToString();
    }

    // Determine the current runtime, used as part of the path to Regasm.exe.
    string runtimeVersion = 
        System.Runtime.InteropServices.RuntimeEnvironment.GetSystemVersion();

    // Build the path to the correct version of Regasm.exe.
    if (isOutlook64bit)
    {
        regasmPath
            = System.IO.Path.Combine(runtimeFolder64, 
                runtimeVersion, 
                "regasm.exe");
    }
    else
    {
        regasmPath
            = System.IO.Path.Combine(runtimeFolder32, 
                runtimeVersion, 
                "regasm.exe");
    }
    return regasmPath;
}

Creating the GetOscProvidersKeyLocation Helper Method

The OSC Providers registry keys are located in the Wow6432Node registry branch when a 32-bit version of Office is installed on a 64-bit version of Windows. The Commit and OnBeforeUninstall methods call the GetOscProvidersKeyLocation helper method to get the correct OSC social providers registry key location.

The GetOscProvidersKeyLocation method, shown in the following code, determines whether the operating system is 64-bit. Then it calls the IsOffice64Bit helper method to determine whether Office is 64-bit.

If a 32-bit version of Outlook is installed on a 64-bit version of Windows, the GetOscProvidersKeyLocation method returns a registry key location of Software\Wow6432Node\Microsoft\Office\Outlook\SocialConnector\SocialProviders. Otherwise, it returns Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

The following code is an example of the GetOscProvidersKeyLocation helper method.

private static String GetOscProvidersKeyLocation()
{
    // Determine whether the operating system is 64-bit.
    bool is64bitOS = System.Environment.Is64BitOperatingSystem;

    // Determine whether Office is 64-bit.
    bool isOutlook64bit = IsOffice64Bit();

    // Define the location of the OSC Social Providers key.
    // The location of the OSC Social Providers key
    // is in the Wow6432Node branch when 32-bit Office 
    // is installed on a 64-bit OS.
    String oscProvidersLocation = String.Empty;
    if (is64bitOS && !isOutlook64bit)
    {
        oscProvidersLocation =
            @"Software\Wow6432Node\Microsoft\Office\Outlook\SocialConnector\SocialProviders";
    }
    else
    {
        oscProvidersLocation =
            @"Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders";
    }
    return oscProvidersLocation;
}

Adding a Setup Project to the Sample Solution

Finally, you will create the setup project for the OSC provider in the sample solution. The setup project will reference the OSC version 1.1 prerequisite package and call the OSC provider's installer class that you added earlier.

To add a setup project to the sample solution

  1. Open the sample solution in Visual Studio 2010.

  2. On the File menu in Visual Studio 2010, point to Add, and then click New Project.

  3. In the Add New Project dialog box, expand Other Project Types, expand Setup and Deployment, and then select Visual Studio Installer.

  4. Select the Setup Project template, type a name of OfficeTalkOSCProviderSetup, and click the OK button.

  5. Right-click the OfficeTalkOSCProviderSetup project, and then click Properties.

  6. In the Property Page, click the Prerequisites button.

  7. In the Prerequisites dialog box, select the Outlook Social Connector v1.1 prerequisite defined earlier.

  8. Keep any other existing prerequisites and click the OK button.

  9. In the Property Page dialog box, click the OK button.

Adding the OSC Provider Project Output to the Setup Project

Now, add the OSC provider project's output to the OfficeTalkOSCProviderSetup project to install the OSC provider assemblies.

To add the OSC provider project output to the OfficeTalkOSCProviderSetup project

  1. Right-click the OfficeTalkOSCProviderSetup project, point to Add, and then click Project Output.

  2. In the Add Project Output Group dialog box, select the OfficeTalkOSCProvider project's primary output, and then click OK.

The primary output from the OfficeTalkOSCProvider project is added to the OfficeTalkOSCProviderSetup project. Any assemblies that the OSC provider project references are added to the Detected Dependencies folder at this time, as well. For this Visual How To, the OSCProvider.dll is added to the Detected Dependencies folder.

Defining Custom Actions

The setup project uses custom actions to call the override methods in the custom installer that you added to the OfficeTalkOSCProvider project earlier.

To define custom actions

  1. Right-click the OfficeTalkOSCProviderSetup project, point to View, and then click Custom Actions.

  2. Right-click Install, and then click Add Custom Action. In the Select Item in Project dialog box, double-click Application Folder, and then double-click Primary output from OfficeTalkOSCProvider (Active).

  3. Right-click Commit, and then click Add Custom Action. In the Select Item in Project dialog box, double-click Application Folder, and then double-click Primary output from OfficeTalkOSCProvider (Active).

  4. Under Commit, select Primary output from OfficeTalkOSCProvider (Active). In the Properties window, type /InstallAllusers=[ALLUSERS] for the CustomActionData property. This will pass to the Commit override method the Install for Everyone or Just me option that the user selects during the installation process.

  5. Right-click Uninstall, and then click Add Custom Action. In the Select Item in Project dialog box, double-click Application Folder, and then double-click Primary output from OfficeTalkOSCProvider (Active).

  6. Under Uninstall, select Primary output from OfficeTalkOSCProvider (Active). In the Properties window, type /InstallAllusers=[ALLUSERS] for the CustomActionData property. This will pass to the OnBeforeUninstall override method the Install for Everyone or Just me option that the user selects during the installation process.

Defining Setup Launch Conditions

OSC providers should install only when a supporting version of Microsoft Outlook is present. Versions of Outlook that support the OSC are Outlook 2003, Outlook 2007, and Outlook 2010 (installed on the client computer or delivered by Click-to-Run on the client computer).

In this section, you will verify that a supporting version of Microsoft Outlook is installed by defining launch conditions for the OfficeTalkOSCProvider project. You will add registry search conditions to look up the registry key values you need to evaluate, and then add a launch condition to evaluate the values.

To define the registry search conditions

  1. Right-click the OfficeTalkOSCProviderSetup project, point to View, and then click Launch Conditions.

  2. Right-click Search Target Machine, and then click Add Registry Search.

  3. Rename the Registry Search to Office Version.

  4. In the Properties window, specify Property as OFFICE_VERSION, specify RegKey as Software\Microsoft\Office\Common\LastAccessInstall, and specify Root as vsdrrHKLM.

  5. Right-click Search Target Machine, and then click Add Registry Search.

  6. Rename the Registry Search to Outlook 2010 Click-To-Run.

  7. In the Properties window, specify Property as OUTLOOK2010_CLICKTORUN, specify RegKey as Software\Microsoft\Office\14.0\Common\InstallRoot\Virtual\VirtualOutlook, and specify Root as vsdrrHKLM.

To define a launch condition that evaluates the registration values

  1. Right-click Launch Conditions, and then click Add Launch Condition.

  2. Rename the launch condition to Supported Outlook Version Installed.

  3. In the Properties window, specify Condition as (OFFICE_VERSION==11 OR OFFICE_VERSION==12 OR OFFICE_VERSION==14) OR (OUTLOOK2010_CLICKTORUN <> ""). If the condition statement evaluates to true, the installation will continue. If it evaluates to false, the installation will stop. This condition statement will evaluate to true only when one of the supporting versions of Outlook is installed.

  4. In the Properties window, specify the Message as This OSC Provider requires a version of Outlook that supports the Outlook Social Connector. This message will display during installation when the condition statement evaluates to false.

Testing the Installation

Now that the installation package for the OSC provider has been defined, test the installation package.

To test the installation on your local development computer

  1. Right-click the solution, and then click Build Solution.

  2. Right-click the OfficeTalkOSCProviderSetup project, and then click Build.

  3. Right-click the OfficeTalkOSCProviderSetup project, and then click Install.

  4. Select the defaults from the installation dialog boxes.

  5. Once installation is complete, open Outlook.

  6. In Outlook, click the View tab. Then click the People Pane button and click Account Settings. The Social Network Accounts dialog box will display your OSC provider.

Additional testing is required to verify that the installation package will deploy your OSC provider correctly to all supported environments. For more information about additional testing to perform prior to releasing your OSC provider, see Getting Ready to Release an OSC Provider in the Outlook Social Connector 1.1 Provider Reference.

Read It

Installation packages are used to deploy OSC providers. These installation packages check whether the OSC needs to be updated, update the OSC if needed, register the OSC provider, and add registry keys required for the OSC to recognize an OSC provider. When the OSC provider is uninstalled, the installation package must also unregister the OSC provider and delete the registry keys that were added during the installation process.

The sample solution for this Visual How To includes a custom OSC provider for OfficeTalk. This Visual How To does not cover all of the code in the sample solution. This Visual How To focuses on creating an installation package for the OSC provider in the sample solution.

For more information about creating the OfficeTalk OSC provider, see Part 1: Developing a Real Outlook Social Connector Provider by Using a Proxy Library.

For more information about returning friends social network data, see Part 2: Getting Friends Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility.

For more information about returning activities social network data, see Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility.

See It

 

Watch the video

> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/0103976e-6909-42e4-a6ba-41f9dd0b660e]

Length: 21:20

Click to grab code

Grab the Code

Explore It