Partager via

Walkthrough: Deploying a VSPackage

  • Article

In this walkthrough, you can examine a basic way to deploy a VSPackage.

Getting Started

Use two computers for this walkthrough, as follows:

  • A development computer that has Visual Studio and Visual Studio SDK installed.

  • A target computer that has Visual Studio installed but does not have Visual Studio SDK installed.

Notes

If you only have one computer, you can develop and deploy on the same computer. However, if you do, you cannot clean up the system registry by using the Reset the Visual Studio 2010 Experimental instance utility. If you have Virtual PC installed on the computer, you can deploy to a virtual image.

To complete this walkthrough, you must install the Visual Studio 2010 SDK. For more information about the Visual Studio SDK, see Visual Studio Integration SDK. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN Web site.

Locations for the Visual Studio Package Project Template

The Visual Studio Package project template can be found in three different locations in the New Project dialog:

  1. Under Visual Basic Extensibility. The default language of the project is Visual Basic.

  2. Under C# Extensibility. The default language of the project is C#.

  3. Under Other Project Types Extensibility. The default language of the project is C++.

Creating a Basic VSPackage

First, create a basic VSPackage to deploy. This VSPackage just opens a dialog box in response to a menu command.

To create a basic VSPackage

  1. Create a VSPackage named DeployPackage with the Visual Studio Package project template. Click OK.

  2. On the Select a Programming Language page, select Visual C# or Visual Basic.

  3. Do not change the default values on the Basic VSPackage Information page.

  4. On the Select VSPackage Options page, select Menu Command. Click Next.

  5. Change Command name to My Deploy Command. Click Next.

  6. Clear Integration Test Project. Click Finish.

    The template generates the DeployPackage solution.

Xcopy Deployment by Using CodeBase

One way to deploy a VSPackage is by using xcopy deployment, which is named after the DOS tool that copies a file to a location. You just copy your VSPackage to the folder of your choice on the target computer. A deployment such as this will definitely fail, because the appropriate system registry keys have not been initialized on the target computer.

You can initialize the system registry by using a .reg file that contains the desired keys and values. You can generate the .reg file for your VSPackage by using the Regpkg.exe utility.

Notes

The preferred way to register packages in Visual Studio is by using .pkgdef files. This enables extension deployment without requiring access to the system registry. Pkgdef files are created by using the CreatePkgDef Utility.

To generate the system registry file

  1. In the System Definition Model Command window, navigate to the folder that contains DeployPackage.dll. This is typically located in the project \bin\Debug\ directory.

  2. Type the following line at the command prompt.

    regpkg /regfile:DeployPackage.reg /codebase DeployPackage.dll

  3. Open the resulting DeployPackage.reg file in Notepad.

DeployPackage.reg should resemble the following code:

REGEDIT4

[HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\10.0\InstalledProducts\DeployPackage]
@="#110"
"Package"="{bad3390c-b2a2-4bfc-a3ad-87e8119df413}"
"ProductDetails"="#112"
"PID"="1.0"
"LogoID"="#400"
[HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\Packages\{bad3390c-b2a2-4bfc-a3ad-87e8119df413}]
@="Company.DeployPackage.DeployPackage, DeployPackage, Version=1.0.2796.21244, Culture=neutral, PublicKeyToken=125cdbd1e07e0d79"
"InprocServer32"="C:\\Windows\\system32\\mscoree.dll"
"Class"="Company.DeployPackage.DeployPackage"
"CodeBase"="D:\\DeployPackage\\DeployPackage\\bin\\Debug\\DeployPackage.dll"
[HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\Menus]
"{bad3390c-b2a2-4bfc-a3ad-87e8119df413}"=", 1000, 1"

The CodeBase key is generated when regpkg.exe is run with the /codebase switch, as follows.

"CodeBase"="D:\\DeployPackage\\DeployPackage\\bin\\Debug\\DeployPackage.dllL"

To deploy your VSPackage to a target computer, you must perform the following tasks:

  • Update the CodeBase path.

  • Copy the VSPackage .dll files and .reg files to the target computer.

  • Update the system registry on the target computer.

  • Initialize the Visual Studio menu system on the target computer.

To deploy to the target computer by using xcopy

  1. Change the CodeBase path in DeployPackage.reg to the path where DeployPackage.dll will be installed on the target computer. For example, if you install DeployPackage.dll to the root directory of drive D, the CodeBase key and value should resemble the following:

    "CodeBase"="D:\\DeployPackage.dll"

  2. Ensure that the InprocServer32 path is the location of mscoree.dll on the target computer. For example, if the operating system is installed on drive D, the InprocServer32 key and value should resemble the following:

    "InprocServer32"="D:\\Windows\\system32\\mscoree.dll"

  3. Save the changes to DeployPackage.reg and copy both DeployPackage.reg and DeployPackage.dll to the target computer. Be sure to copy DeployPackage.dll to the path given in the CodeBase key.

  4. Run the Visual Studio Command window on the target computer as administrator.

  5. At the command prompt, navigate to where you installed DeployPackage.dll and then type the following two lines:

    regedit /s deploypackage.reg

    devenv /setup /nosetupvstemplates

    The first line installs the various keys and values in the system registry. The second line initializes Visual Studio and its menu system on the target computer.

    Notes

    Because we are not adding project or item templates, we can use the /nosetupvstemplates switch to decrease setup time.

  6. Start Visual Studio on the target computer.

  7. On the Tools menu, click My Deploy Command. You should see a message box that has the following message:

    Inside Company.DeployPackage.DeployPackage.MenuItemCallback()

Congratulations! You have successfully deployed your VSPackage!

CodeBase Versus Assembly Deployment

To use CodeBase deployment, you install your VSPackage in the folder given by the CodeBase key. This folder is typically named after a company or technology, for example, D:\MyCompany.

Assembly deployment is another way to deploy your VSPackage. By using assembly deployment, you install your VSPackage in the Visual Studio PrivateAssemblies folder or subfolder. 

You would typically choose CodeBase deployment when your VSPackage is primarily used by your own product, and is not known to other products. You would choose assembly deployment when your VSPackage is meant to be shared by other products. For example, a spelling checker would probably be deployed to the PrivateAssemblies folder.

Notes

Assembly file name clashes are possible in the PrivateAssemblies folder.

Because each version of Visual Studio has its own PrivateAssemblies folder, you can use assembly deployment for a VSPackage that is designed for side-by-side scenarios. If you have a VSPackage that is designed to run under several versions of Visual Studio, then you should consider installing it to the GAC.

Notes

For performance reasons, don't strong-name sign assemblies that you put in the PrivateAssemblies folder, or anyplace other than the GAC.

Xcopy Deployment by Using PrivateAssemblies

VSPackage assembly deployment to the PrivateAssemblies folder uses a different system registration than CodeBase deployment. You can use the regpkg.exe utility to create the necessary keys, subkeys, and values for assembly deployment.

To generate the system registry file

  1. In the System Definition Model Command window, navigate to the folder that contains DeployPackage.dll. This is typically located in the project's \bin\Debug\ directory.

  2. Type the following line at the command prompt:

    regpkg /regfile:DeployPackage.reg /assembly DeployPackage.dll

  3. Open the resulting DeployPackage.reg file in Notepad.

The CodeBase key is replaced with the Assembly key, as follows:

"Assembly"="DeployPackage, Version=1.0.2796.21244, Culture=neutral, PublicKeyToken=125cdbd1e07e0d79"

To deploy your VSPackage to a target computer, you must copy the VSPackage .dll files to the PrivateAssemblies folder of the target computer. You must also copy the .reg files to the target computer, update the system registry on the target computer, and initialize the Visual Studio menu system on the target computer.

To deploy to the PrivateAssemblies folder

  1. Ensure that the InprocServer32 path is the location of mscoree.dll on the target computer. For example, if the operating system is installed on drive D, the InprocServer32 key and value should resemble the following:

    "InprocServer32"="D:\\Windows\\system32\\mscoree.dll"

  2. If you have already installed your VSPackage by using CodeBase, delete the folder and its contents.

  3. Copy DeployPackage.reg and DeployPackage.dll to the PrivateAssemblies folder on the target computer. The typical location for this folder is Visual Studio installation path\Common7\IDE\PrivateAssemblies\.

    Notes

    Administrative credentials may be required to copy to this folder.

  4. Run the Visual Studio Command window on the target computer as administrator.

  5. At the command prompt, navigate to the PrivateAssemblies folder and then type the following two lines:

    regedit deploypackage.reg

    devenv /setup

    The first line installs the various keys and values in the system registry. The second line initializes Visual Studio and its menu system on the target computer.

    Deploypackage.reg is no longer required. You can delete it.

  6. Start Visual Studio on the target computer.

  7. On the Tools menu, click My Deploy Command. You should see a message box that has the following message:

    Inside Company.DeployPackage.DeployPackage.MenuItemCallback()

Congratulations! You have deployed your VSPackage to the PrivateAssemblies folder!

Deployment By Using a Setup Project

An easier approach to deploying a VSPackage is to use a Visual Studio setup project. Setup projects produce Windows Installer (.msi) files, which handle many deployment tasks for you, for example:

  • Making sure that prerequisites are met, such as installing the common language runtime (CLR) on the target computer.

  • Providing a user interface to enable selection of the target folder for the installation.

  • Running custom build steps, such as merging menus.

For more information, see Setup Projects.

The following setup project procedure imports registry information from a .reg file created for CodeBase deployment. If you haven't already created this file, complete the following procedure first.

To generate the system registry file

  1. In the System Definition Model Command window, navigate to the folder that contains DeployPackage.dll. This is typically located in the project \bin\Debug\ directory.

  2. Type the following line at the command prompt:

    regpkg /regfile:DeployPackage.reg /codebase DeployPackage.dll

Now you are ready to create and configure the setup project.

To create and configure the setup project

  1. Open the DeployPackage solution in Visual Studio on your development computer.

  2. Right-click the solution node, click Add, and then click New Project.

  3. Expand Other Project Types and then select Setup and Deployment.

  4. Create a Setup Project named Setup.

    The template adds the setup project to your solution.

  5. Right-click the setup project node, click Add, and then click Project Output.

  6. Click OK to add the Primary output of the DeployPackage project.

    The dependency checker runs and adds dependencies to the setup project. Most of these dependencies refer to binaries that are already present on a target computer that has Visual Studio installed.

  7. Select all detected dependencies except Microsoft .NET Framework, right-click the selection, and then click Exclude.

  8. Click the Setup project node.

    The project properties appear in the Properties window.

  9. Change the ProductName property to My Deploy Package.

  10. Change the Title property to My Deploy Package Setup.

  11. Click the Registry Editor icon on the Solution Explorer toolbar.

    The Registry editor appears.

  12. Right-click Registry on Target Machine and then click Import.

    The Import Registry dialog box appears.

  13. Navigate to the \bin\Debug\ folder of the DeployPackage project and select DeployPackage.reg. Click Open.

    The registry keys you generated for CodeBase deployment are added to the HKEY_LOCAL_MACHINE node in the Registry editor.

If you examine the registry keys in the \Software\Microsoft\VisualStudio\9.0\Packages\ node, you find two hard-coded paths. These must be replaced by paths that are determined during installation.

To remove the hard-coded paths

  1. In the Registry editor, select the CodeBase key, then select the Value property in the Properties window.

  2. Change the path to be relative to the target installation directory, as follows:

    [TARGETDIR]deploypackage.dll

  3. In the Registry editor, select the InProcServer32 key and then select the Value property in the Properties window.

  4. Change the path to be relative to the target system directory, as follows:

    [SystemFolder]mscoree.dll

After you install on the target computer, you must run devenv.exe with the /setup switch. You can add this to the installation as a custom action. To create a custom action, you must first add a project to create a class that derives from the Installer class.

To add an Installer class project

  1. On the File menu, point to New and then click Project.

    The New Project dialog box appears.

  2. Create a Visual C# or Visual Basic Class Library named DevenvSetupCustomAction.

  3. Delete the Class1.cs or Class1.vb file.

  4. Right-click the DevenvSetupCustomAction project node, click Add, and then click New Item.

  5. Create a new Installer Class named DevenvSetup.

  6. Right-click the DevenvSetup.cs or DevencSetup.vb node and then click View Code.

  7. Add the following lines to the using or Imports statements:

    Imports Microsoft.Win32
Imports System.Diagnostics

    using Microsoft.Win32;
using System.Diagnostics;

  8. Override the Install method by adding the following code to the DevenvSetup class, just after the constructor:

    Public Overloads Overrides Sub Install(ByVal stateSaver As IDictionary)
    MyBase.Install(stateSaver)

    Using setupKey As RegistryKey = Registry.LocalMachine.OpenSubKey("SOFTWARE\Microsoft\VisualStudio\9.0\Setup\VS")
        If setupKey IsNot Nothing Then
            Dim devenv As String = setupKey.GetValue("EnvironmentPath").ToString()
            If Not String.IsNullOrEmpty(devenv) Then
                Process.Start(devenv, "/setup").WaitForExit()
            End If
        End If
    End Using
End Sub

    public override void Install(IDictionary stateSaver)
{
    base.Install(stateSaver);

    using (RegistryKey setupKey = Registry.LocalMachine.OpenSubKey(
          @"SOFTWARE\Microsoft\VisualStudio\9.0\Setup\VS"))
    {
        if (setupKey != null)
        {
            string devenv = setupKey.GetValue("EnvironmentPath").ToString();
            if (!string.IsNullOrEmpty(devenv))
            {
                Process.Start(devenv, "/setup").WaitForExit();
            }
        }
    }
}

    This code searches the registry on the target computer for the EnvironmentPath named value of the \Software\Microsoft\VisualStudio\9.0\Setup\VS\ key. The value of EnvironmentPath is the full path to devenv.exe. The Install method runs devenv.exe with the /setup switch and waits for it to finish.

    Notes

    If you are not installing project or item templates, you can significantly shorten installation time by adding the /nosetupvstemplates switch, as follows:

    Process.Start(devenv, "/setup /nosetupvstemplates").WaitForExit()

    Process.Start(devenv, "/setup /nosetupvstemplates").WaitForExit();

Now that you have a custom action, you can add it to the Setup project.

To add a custom action to the Setup project

  1. Right-click the Setup project node, click Add, and then click Project Output.

    The Add Project Output Group dialog box appears.

  2. Select DevenvSetupCustomAction on the Project list.

    Primary output from DevenvSetupCustomAction (Active) is added to the Detected Dependencies node.

  3. Select the Setup project node and then click the Custom Actions Editor icon on the Solution Explorer toolbar.

    The Custom Actions editor appears.

  4. Right-click the Install node and then click Add Custom Action.

    The Select Item in Project dialog box appears.

  5. Double-click the Application Folder and then select Primary output from DevenvSetupCustomAction (Active). Click OK.

    The custom action is added to the Install node.

To test the Setup project

  1. Build the DeployPackage solution.

    DeployPackage.dll and DevenvSetupCustomAction.dll are created.

  2. Build the Setup project.

    Setup.exe and Setup.msi are created.

  3. Close Visual Studio.

  4. Copy setup.exe to the target computer. You can run setup.exe on the development computer if no target computer is available.

    Notes

    The computer must have Visual Studio installed. The version of Visual Studio must match the registry key that is used by the custom action.

  5. Run setup.exe on the target computer.

    Notes

    Running devenv /setup may take a while. You can follow its progress by using Task Manager.

  6. Install DeployPackage, and accept all defaults.

  7. Run Visual Studio.

  8. On the Tools menu, click My Deploy Command. You should see a message box that has the following message:

    Inside Company.DeployPackage.DeployPackage.MenuItemCallback()

  9. Close the message box and exit Visual Studio.

  10. In the Control Panel, (Windows Vista) select Programs and Features or (Windows XP) Add or Remove Programs.

  11. Uninstall My Deploy Package.

  12. Run Visual Studio.

  13. Verify that My Deploy Command no longer appears on the Tools menu.

Deployment By Using the Windows Installer XML Toolset

Another approach to deploying a VSPackage is to use the Windows Installer XML toolset. The Toolset compiles .wxs files to produce .msi files. Custom actions, such as merging menus, are easier to create by using .wxs files than by using Windows Installer setup projects.

For more information about the Toolset, see http://wix.sourceforge.net/.

You can use the RegPkg utility to create a .wxs file to register a VSPackage in the system registry. You insert this file into a more complete .wxs file that deploys your VSPackage and merges its menus into Visual Studio. You then compile this .wxs file with the candle.exe and light.exe tools to produce an .msi file for your VSPackage deployment.

First, create the outer DeployPackage.wxs file and add it to the DeployPackage project.

To create the DeployPackage.wxs file

  1. In Solution Explorer, right-click the DeployPackage project node, click Add, then click New Item.

    The Add New Item dialog box is displayed.

  2. Select the Text File item template, name the file DeployPackage.wxs, and then click Add.The empty file appears in the editor.

  3. Add these lines to the file:

<?xml version='1.0' encoding='windows-1252'?>

<?define VisualStudioRegistryRoot = "Software\Microsoft\VisualStudio\9.0" ?>

<Wix xmlns='https://schemas.microsoft.com/wix/2003/01/wi'>
  <Product Name='DeployPackage' Id='54748C47-DC70-43ec-A296-ECD7F30A548C'
    Language='1033' Codepage='1252' Version='1.0.0' Manufacturer='My Company'>

    <Package Id='????????-????-????-????-????????????' Keywords='Installer'
      Description="Deploy Package Installer"
      Comments='Demonstrates VSPackage deployment' Manufacturer='My Company'
      InstallerVersion='100' Languages='1033' Compressed='yes' SummaryCodepage='1252' />

    <Media Id='1' Cabinet='Sample.cab' EmbedCab='yes' />

    <!-- Properties -->
    <Property Id="DEVENV_EXE_PATH">
      <RegistrySearch Id="RegSearch_DevenvExe_Path" Root="HKLM" Key="$(var.VisualStudioRegistryRoot)\Setup\VS" Name="EnvironmentPath" Type="raw" />
    </Property>

    <!-- Launch conditions -->
    <Condition Message="An administrator must approve or install [ProductName]."> Privileged </Condition>
    <Condition Message="[ProductName] requires Visual Studio 2010."> DEVENV_EXE_PATH </Condition>

    <!-- Root directories -->
    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder" Name="PFILES">
        <Directory Id="INSTALLDIR" Name="MyFolder" >

          <Component Guid="7D6D266D-4197-439b-ADB4-D51876269055" Id="MainExecutable">
            <File Id="Deploy.dll" Name="Deploy.dll" LongName="DeployPackage.dll" Source="bin\Debug\DeployPackage.dll" Vital="yes" DiskId="1" />
            <?include DeployFragment.wxs ?>
          </Component>
        </Directory>
      </Directory>
    </Directory>

    <Feature Id='Complete' Level='1'>
      <ComponentRef Id='MainExecutable' />
    </Feature>

    <InstallExecuteSequence>
      <Custom Action="CA_DeployPackage" Before="InstallFinalize" />
    </InstallExecuteSequence>

    <CustomAction Id="CA_DeployPackage" Property="DEVENV_EXE_PATH" ExeCommand="/setup /nosetupvstemplates" Impersonate="no" Execute="deferred" />

  </Product>
</Wix>
  1. Save your changes.

The outer DeployPackage.wxs file refers to an intermediate file named DeployFragment.wxs, which you generate from DeployPackage.dll.

To generate the DeployFragment.wxs file

  1. In the System Definition Model Command window, navigate to the folder that contains DeployPackage.dll. This is typically located in the project \bin\Debug\ directory.

  2. Type the following line at the command prompt:

    regpkg /wixfile:..\..\DeployFragment.wxs /codebase DeployPackage.dll

    RegPkg creates the DeployPackage.wxs file in the DeployPackage project folder.

  3. In Visual Studio, right-click the DeployPackage project node, point to Add, and then click Existing Item.

    The Add Existing Item dialog bos is displayed.

  4. Navigate to the DeployPackage project folder.

  5. Set the file filter to show All Files, select the DeployFragment.wxs file, and then click Add.

    The DeployFragment.wxs file is added to the DeployPackage project.

  6. Open the DeployFragment.wxs file for editing.

  7. Change the value of the Registry element named CodeBase so that it matches the Name attribute of the DeployPackage.wxs File element.

    <Registry Name="CodeBase" Value="[#Deploy.dll]" Type="string" />

  8. Save your changes.

While a full explanation of the elements of the .wxs file is beyond the scope of this walkthrough, here are a few key points to get you started.

  • Many Toolset elements take a GUID as an Id. These GUIDs should be replaced when you create a new .wxs file. GUIDs within the Include tags should not be replaced, because they belong to the VSPackage.

  • The File element has a Name attribute that uses a short (DOS 8.3) formatted name, and is used only for identification purposes. The actual VSPackage is given by the LongName and Source attributes. By convention, the Id attribute is the same as the Name attribute.

  • The Name attribute of the DeployPackage.wxs File element must match the value of the DeployFragment.wxs Registry element named CodeBase. Remember that the Name attribute is a short (DOS 8.3) formatted file name.

  • The CustomAction element specifies the custom action. The Impersonate and Execute attributes are set so that Visual Studio has elevated privileges under Windows Vista while the custom action runs. The ExeCommand attribute uses the /nosetupvstemplates switch to take advantage of the fact that you are not installing item or project templates. This greatly decreases Setup time.

Now that your .wxs file is complete, you can compile it to create the .msi setup file.

To compile the DeployPackage.wxs file

  1. In the System Definition Model Command window, navigate to the DeployPackage project folder. This folder contains the file DeployPackage.wxs.

  2. Add the full path of the Toolset to the Environment Path variable. For example,

    set Path=%Path%;C:\Program Files\Microsoft Visual Studio 2010 SDK\VisualStudioIntegration\Tools\Toolset

  3. Type the following line at the command prompt.

    candle DeployPackage.wxs

    This creates the DeployPackage.wixobj object file.

  4. Type the following line at the command prompt.

    light DeployPackage.wixobj

    This creates the DeployPackage.msi object file.

To test the .msi deployment file:

  • Install the VSPackage on the target computer.

  • Test that the VSPackage runs on the target computer.

  • Uninstall the VSPackage from the target computer.

To test the Setup project

  1. Copy DeployPackage.msi to the target computer. You can run it on the development computer if no target computer is available.

    Notes

    The computer must have Visual Studio installed. The version of Visual Studio must match the registry key that is used by the launch condition and by the custom action.

  2. Run DeployPackage.msi on the target computer.

    Notes

    No wizard appears. It is possible for light.exe to add a wizard by using a Toolset library. For more information, see http://wix.sourceforge.net/.

  3. Run Visual Studio.

  4. On the Tools menu, click My Deploy Package. You should see a message box that has the following message:

    Inside Company.DeployPackage.DeployPackage.MenuItemCallback()

  5. Close the message box and close Visual Studio.

  6. In the Control Panel, (Windows Vista) select Programs and Features or (Windows XP) Add or Remove Programs.

  7. Uninstall DeployPackage.

  8. Run Visual Studio.

  9. Verify that My Deploy Command no longer appears on the Tools menu.

See Also

Other Resources

Installing VSPackages

Installing VSPackages By Using Windows Installer