Versioning Controlled Build

This document provides basic information for developers who want to build
the add-in themselves.

INTRODUCTION

Current solution (ver. 3.4) is created in Visual Studio 2008.

The tool includes support for Visual Studio 2003/2005/2008/2010/2012 and 2013 
(public preview).


SOLUTION CONFIGURATION

There are two (pairs of) configurations:
- Debug/Release which creates add-in with permanent toolbar and menu bar
- Debug TemporaryBars/Release TemporaryBars which creates add-in with temporary
  toolbar and menubar
  
To clarify the difference between temporary and permanent commandbars, please 
check this article: http://www.mztools.com/articles/2005/MZ2005003.aspx


BUILDING THE SOLUTION

Before building the Setup project, exclude all detected dependencies, except
one instance of MultiTabColorPicker.dll. Namely, Visual Studio automatically 
includes files that are supposed to exist on the target machine already and
need not be distributed with setup.

If you do not need to create add-ins for Visual Studio 2003 and/or 2005,
build procedure and requirements can be vastly simplified as described below.


ADD-IN FOR VISUAL STUDIO 2003

Visual Studio 2003 natively supports only .NET Framework 1.1 so the add-in code
must be compiled for that version of Framework. Since Visual Studio 2008 
cannot build assemblies for .NET 1.1, MSBee Toolkit (http://www.codeplex.com/MSBee) 
must be used to build .NET 1.1 assemblies. Basic usage of MSBee is described
in a separate section below.
Moreover, Visual Studio 2003 add-ins can be activated only by COM registration 
and require separate registration during setup. 

If add-in for VS2003 is not required:

1. Before opening the solution in Visual Studio, remove
   <Import Project="$(MSBuildExtensionsPath)\MSBee\MSBuildExtras.FX1_1.CSharp.targets" />
   tags from ImplementationVS7.csproj, ImplementationVS7TemporaryBars.csproj, 
   Addin.csproj and Shared.csproj files;
2. Remove ImplementationVS7 and ImplementationVS7TemporaryBars projects from the
   solution;
3. Remove primary outputs of above mentioned VS7 projects from setup project(s);
4. Remove registry key
   User/MachineHive\Software\Microsoft\VisualStudio\7.1\AddIns\BuildAutoIncrement.Connect
   from the setup project(s);
5. Remove "Search for Visual Studio 7.1 (2003)" from Launch Conditions in setup
   project(s).


ADD-IN FOR VISUAL STUDIO 2005

Although Visual Studio 2005 supports simpler XML based registration, this add-in
still uses COM based registration in order to display icons on VCB toolbar and 
menu using the same satellite DLL as VS2003 add-in does. If XML based 
registration were used, a separate managed resource file with images would have
to be created.

If add-in for VS2005 (in addition to VS2003) is not required, in addition to 
above steps for VS2003 add-in removal:

1. Remove Addin, ImplementationVS7 and ImplementationVS7TemporaryBars projects 
   from the solution;
2. Remove primary outputs of above mentioned VS8 projects from setup project(s);
4. Remove registry key
   User/MachineHive\Software\Microsoft\VisualStudio\8.0\AddIns\BuildAutoIncrement.Connect
   from the setup project(s);
5. Remove "Search for Visual Studio 8.0 (2005)" from Launch Conditions in setup
   project(s).


USING MSBEE

To enable building .NET 1.1 code with Visual Studio 2008, MSBee must be installed
on development machine. You can download it from:
- http://www.codeplex.com/MSBee or
- http://www.microsoft.com/en-us/download/details.aspx?id=11381
Also, .NET 1.1 SDK (http://www.microsoft.com/en-us/download/details.aspx?id=16217)
must be installed.

Additional details are available here:
- http://msmvps.com/blogs/paulomorgado/archive/2009/10/26/compiling-net-1-1-projects-in-visual-studio-2008.aspx
- http://blogs.msdn.com/b/jomo_fisher/archive/2004/10/01/236879.aspx
- http://devlicio.us/blogs/ziemowit_skowronski/archive/2008/08/22/working-with-net-1-1-in-visual-studio-2008-and-team-server.aspx


PROJECT ORGANIZATION AND DEPENDANCIES

Since different versions of Visual Studio run different versions of .NET
Framework (see http://msmvps.com/blogs/carlosq/archive/2008/11/14/net-frameworks-clrs-and-visual-studio-add-ins.aspx
for details), theoretically, each Visual Studio would require its own add-in.
Fortunately, all versions from Visual Studio 2005 on can run .NET Framework 2.0
assemblies so for Visual Studio 2005 and newer one add-in suffices.

It is important to notice that Visual Studio add-ins must be registered
in order to be activated by Visual Studio. There are two possible approaches
to add-in registration:
- COM based registration which is performed during setup;
- XML file registration which requires placement of a registration file 
  into predefined folder.
Visual Studio 2002 and 2003 supported only COM based registration, while 
Visual Studio 2005 and newer additionally support (simpler) XML based 
registration.
Additional information may be found here:
- http://www.codeproject.com/Articles/43043/NUnit-Starter
- http://www.mztools.com/Articles/2008/MZ2008001.aspx
- http://msdn.microsoft.com/en-us/library/19dax6cz%28v=vs.71%29.aspx
- http://msdn.microsoft.com/en-us/library/19dax6cz.aspx

Originally, this add-in was created for Visual Studio .NET (i.e. 2002) which
supported COM based registration of add-in only and ran .NET Framework 1.0.
VS2003 runs .NET Framework 1.1 and requires COM registration too. Since
.NET 1.0/1.1 are not completely compatible with 2.0, it is necessary to create 
at least two assemblies: for .NET 1.0/1.1 (to run with VS2002/2003) and for .NET
2.0 (to run on VS2005 and newer). Since the logic and code behind different 
versions is mostly the same, to avoid source code multiplication, different 
projects have been created that use the same code, each project conditionally 
including or excluding incompatible parts of code. More details how to 
accomplish this can be found here:
- http://www.codeproject.com/Articles/43043/NUnit-Starter
- http://www.mztools.com/articles/2011/MZ2011012.aspx


Addin Project

Basic idea was to create a common entry point for all Visual Studio versions. 
That entry point is BuildAutoIncrement.Connect class in Addin project. This 
project is built for .NET Framework 1.1 and does not contain any code that 
may be incompatible with .NET 2.0. BuildAutoIncrement.Connect class simply 
detects which version of Visual Studio is it started from and dynamically loads
corresponding Implementation assembly and instantiates an object of
BuildAutoIncrement.Connect2 class by reflection mechanism, using IAddin 
interface as a common interface for all implementations. This way, only 
one (Addin.dll) assembly must be registered for various versions of Visual 
Studio.


Implementation Projects

Implementation assemblies are built for different versions of .NET Framework.
ImplementationVS7 runs on .NET 1.1 (i.e. VS2003), ImplementationVS8 and 
ImplementationVS9 run on .NET 2.0 (VS2005 and newer). ImplementantationVS8
(for VS2005) and ImplementationVS9 (for VS2008 and newer) differ only in
storage of toolbar and menu icons. Although VS2005 supports XML based
registration, this add-in uses COM based registration in order to load 
images from the same satellite DLL used by ImplementationVS7 assembly;
otherwise, extra resources assembly should be created.

ImplementationVS9 uses XML based registration. Since VS2008 and newer can
handle resources in the same assembly, toolbar and menu icons are included
into the assembly and no additional satellite DLL is required. Moreover,
ImplementationVS9 is activated directly (and via not common entry point 
in Addin.dll) so it need not to refer the IAddin interface defined in
Addin project. Thus, ImplementationVS9 does not include reference to
Addin project and Addin.dll need not be installed for VS2008 and newer.

There are two subsets of implementation assemblies:
- for add-ins with permanent toolbar/menus and
- for add-ins with temporary toolbar/menus.

Preferred are temporary toolbar and menus since temporary command bars are
troublesome to uninstall. On the other side, permanent command bars are loaded
faster and time lag when add-in is activated is shorter.
Additional information can be found here:
- http://www.mztools.com/articles/2005/MZ2005003.aspx


Shared Project

Shared project contains code and resources that are common to all 
implementations. In order to be used by ImplementationVS7, it must be built for
.NET Framework 1.1. If add-in for VS2003 is not required, it can be built for 
.NET 2.0 or later as target.


Setup Projects

Solution contains two setups and two corresponding Visual Studio configurations: 
1. for permanent VCB toolbar/menu (BuildAutoIncrementSetup.vdproj setup project
   and straight Debug/Release configurations in Visual Studio)
2. for temporary VCB toolbar/menu (BuildAutoIncrementSetupTemporaryBars.vdproj 
   setup project and Debug TemporaryBars/Release TemporaryBars configurations).