Export (0) Print
Expand All
Debugging: Root Out Elusive Production Bugs with These Effective Techniques
Smart Tags: Simplify UI Development with Custom Designer Actions in Visual Studio
Ten Essential Tools: Visual Studio Add-Ins Every Developer Should Download Now
XML Comments: Document Your Code in No Time At All with Macros in Visual Studio
Expand Minimize

Support for Multiple Versions of the Same Component with Visual Studio .NET 2003

Visual Studio .NET 2003
 

Izzy Gryko
Visual Studio Team
Microsoft Corporation

July 2003

Applies to:
   Microsoft® Visual Studio® .NET 2003

Summary: This paper shows how you can support multiple versions of the same component on a single machine in Visual Studio .NET 2003. (4 printed pages)

Contents

Introduction
Component Installation
Guidelines for Releasing a Component
How Visual Studio .NET 2003 Supports Multiple Component Versions
Conclusion

Introduction

If you support multiple versions of the same component, then your users will be able to do the following:

  • On a machine that has MyComponent version 1.0 and MyComponent version 2.0 installed side-by-side, the user can create a project in Visual Studio .NET 2003 and add a reference in that project to MyComponent, version 2.0 (either by browsing to a filename or using the .NET tab from the Add Reference dialog box). When the project is re-opened, Visual Studio .NET 2003 resolves the MyComponent reference to the proper version of the component (version 2.0).
  • On a machine that has MyComponent version 1.0 installed, the user can create a project in Visual Studio .NET 2003 and add a reference in that project to MyComponent, version 1.0. If the user also installs MyComponent version 2.0 side-by-side with the existing version 1.0, then when the project is reopened, Visual Studio will resolve the MyComponent reference to the proper version of the component (version 1.0).

    To upgrade the project to version 2.0 of MyComponent, the user will need to delete the original reference to version 1.0 and add a new reference to version 2.0.

Component Installation

Components must be properly registered for Visual Studio .NET 2003 to support multiple versions. Proper registration includes the following steps:

  • Install the component on the user's hard drive in a location other than the Global Assembly Cache (GAC). If you want the component to be shared among multiple applications, then you should also install it in the GAC.
  • Register the installed location of the component in the AssemblyFolders subkey by creating the appropriate registry key under one of the following keys:
    • HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.1\AssemblyFolders
    • HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\7.1\AssemblyFolders
    • HKEY_CURRENT_USER\Software\Microsoft\.NETFramework\AssemblyFolders
    • HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AssemblyFolders
      Note   Only register the installed location of a component in one AssemblyFolder.

To register your component, you first need to decide on the component access level and then register it in the appropriate AssemblyFolder location according to the following rules:

  • If the component is to be registered for a single user and only for Visual Studio .NET 2003, then register in HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.1.
  • If the component is to be registered for all users on a machine, and only for Visual Studio .NET 2003, then register in HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\7.1.
  • If the component is to be registered for a single user for all versions of Visual Studio, then register in HKEY_CURRENT_USER\Software\Microsoft\.NETFramework.
  • If the component is to be registered for all users on a machine, and for all versions of Visual Studio, it should be registered in HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework.
    Note   If a path on disk contains more than one component, then you only need to create one AssemblyFolder registry entry. This entry will be used to find all components in the registered path.

Guidelines for Releasing a Component

Use the following guidelines for releasing a new version of a component that will be installed side-by-side with previous versions:

  • Install the new version of the component in a different directory on the user's hard drive.
    Note   It is important to distinguish between the directory where the new component is installed and the Global Assembly Cache (GAC). Although you might choose to install your component into the GAC for use during run time, you must also install your component into a separate directory on the user's hard drive for use during design time.
  • Create a new registry key for the new component under one of the four registry keys specified.
  • Do not remove the registry key or keys for previous component versions from the registry.

Use the following guidelines to release a component that replaces a previous version of the same component:

  • Use the same assembly name and file name for the current version of the component as was used for the version being replaced. If the file name changes, then users who have referenced a previous version of the component will not automatically reference the new version.
  • Install the new version of the component into the same directory on the user's hard drive as the version being replaced.
    Note   It is very important to distinguish between the directory where the new component is installed and the Global Assembly Cache (GAC). Although you might choose to install your component into the GAC for use during run time, you must also install your component into a separate directory on the user's hard drive for use during design time. The new and old components can be installed side-by-side in the GAC. This allows administrators to use policy to control which version of the component is loaded at run time.
  • Register the new version of the component in the same registry key as the old version.
Note   Do not place your component in the %windir%\Microsoft.NET\Framework\v1.<x> directory, where <x> is the version of the .NET Framework.

How Visual Studio .NET 2003 Supports Multiple Component Versions

Unlike previous versions, Visual Studio .NET 2003 automatically persists the name of the AssemblyFolder from which a component was referenced together with other reference information, such as assembly name. These keys are persisted as part of the <Reference> XML element in the project file in the AssemblyKeyName attribute. The value of this attribute is a string that depends on the registry location of the AssemblyFolder. Visual Studio applies the following rules to determine the persisted value of the attribute:

  • HKEY_CURRENT_USER \SOFTWARE\Microsoft\VisualStudio\7.1\AssemblyFolders\<keyname>

    The persisted string in the project file will be "hkcu\<keyname>"

  • HKEY_LOCAL_MACHINE \SOFTWARE\Microsoft\VisualStudio\7.1\AssemblyFolders\<keyname>

    The persisted string in the project file will be "hklm\<keyname>"

  • HKEY_CURRENT_USER \SOFTWARE\Microsoft\.NETFramework\AssemblyFolders\<keyname>

    The persisted string in the project file will be "hkcu\dn\<keyname>"

  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\AssemblyFolders\<keyname>

    The persisted string in the project file will be "hklm\dn\<keyname>"

The AssemblyKeyName attribute is persisted in the following circumstances:

  • User adds a reference to an assembly from the .NET tab of the Add Reference dialog box. In this case, Visual Studio .NET 2003 knows the name and location of the AssemblyFolder automatically.
  • User browses to an assembly file on disk and the path to that file is registered in one or more AssemblyFolders. In this case, Visual Studio .NET 2003 searches the list of all AssemblyFolders on the machine in the order specified under Component Installation. The first AssemblyFolder with a registered path that matches the path to the file is persisted in the AssemblyKeyName attribute.
    Note   If the user browses to an assembly in the .NET Framework SDK directory, the AssemblyFolder name is not persisted. The .NET Framework SDK directory is treated specially, and no component vendor should ever attempt to register the .NET Framework SDK directory in any AssemblyFolder location.

Limitations

The following limitations apply to multiple component version support in Visual Studio .NET 2003:

  • A project upgraded from Visual Studio .NET 2002 will not persist the name of the AssemblyFolder from which a component was referenced. To persist this information, the user has to manually remove and read the reference to the affected component or components once the project has been upgraded to Visual Studio .NET 2003.
  • This feature cannot be used to support referencing multiple versions of the same component in the same project.
  • This feature also cannot be used to support referencing multiple versions of the .NET Framework.

Conclusion

This article has demonstrated how to properly install, register, and release a component that will be installed side-by-side with previous versions of the same component in Visual Studio .NET 2003. Using this information, you can release updated versions of your component in Visual Studio .NET without causing versioning problems for your users.

Show:
© 2014 Microsoft