 ----
 Debugging the Visual Studio Add-in
 ----
 ----
~~Licensed to the Apache Software Foundation (ASF) under one
~~or more contributor license agreements.  See the NOTICE file
~~distributed with this work for additional information
~~regarding copyright ownership.  The ASF licenses this file
~~to you under the Apache License, Version 2.0 (the
~~"License"); you may not use this file except in compliance
~~with the License.  You may obtain a copy of the License at
~~
~~    http://www.apache.org/licenses/LICENSE-2.0
~~
~~Unless required by applicable law or agreed to in writing,
~~software distributed under the License is distributed on an
~~"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~KIND, either express or implied.  See the License for the
~~specific language governing permissions and limitations
~~under the License.

Debugging the Visual Studio Add-in

  If you are looking to contribute to the code in the Add-in, you will find it helpful at times to be able to step
  through it in the Visual Studio debugger. The following steps show how to do so.

    [[1]]  Install the Addin using the MSI for a recent release (or built with
           the distribution options). This will create the necessary Addin file for
           editing below - if you already have it then this step can be
           skipped

    [[2]]  Check out the source code for NPanday if you haven't already. More information on how to build it is
           available in {{{./building.html} Building NPanday}}.

    [[3]]  Open solution file: <<<dotnet\NPanday.sln>>>. You may need to choose 'Load project normally' in a
           warning dialog. The solution is for Visual Studio 2010 - if you are using a more recent version it may ask
           you to upgrade the project as well.

    [[4]]  Build the whole solution using the normal Visual Studio build solution command.

    [[5]]  Open this file using a text editor (notepad will do):
           <<<My Documents\Visual Studio 2010\Addins\NPanday.VisualStudio.AddIn>>>. This should be the file for the
           version of Visual Studio you intend to debug it in, so change 2010 to 2005/2008 if desired
           (it need not be the same as the one you have the main solution open in).

    [[6]]  Change the value of the <<<\<Extensibility\>\<AddIn\>\<Assembly\>>>> to the following file within your
           checkout: <<<dotnet\assemblies\NPanday.VisualStudio.Addin\target\NPanday.VisualStudio.Addin.dll>>>. You must
           use the full path, for example: <<<C:\Users\[username]\checkouts\npanday\assemblies\...>>>

    [[7]]  Change the value of <<<\<Extensibility\>\<AddIn\>\<Description\>>>> to the correct version (including -SNAPSHOT) 
           in order to get an additional output pane showing the debug log.

    [[8]]  Back in Visual Studio, from the NPanday solution, right click on the <<<NPanday.VisualStudio.Addin>>>
           project. Set it to be the <Start up project> of the solution.

    [[9]]  Right click on <<<NPanday.VisualStudio.Addin>>> again and select <Properties>

    [[10]] Go to the Debug tab and select <Start External Program> in the <Action> section. Locate the <<<devenv.exe>>>
           of the version of Visual Studio that you want to debug. This is likely to be either
           <<<C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\devenv.exe>>> (Visual Studio 2010) or
           <<<C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe>>> (Visual Studio 2008) or
           <<<C:\Program Files\Microsoft Visual Studio 8.0\Common7\IDE\devenv.exe>>> (Visual Studio 2005)

    [[11]] You can now set any breakpoint on the project and press the "Run" button to open a new instance of
           Visual Studio with the current Add-in code loaded. <<<Connect.cs>>> is the main class of the Add-in and
           is the place to look for code to set breakpoints in to start with.

    [[12]] The Visual Studio will lock the Add-in libraries as long as it runs. So it is recommended to disable the
           Add-in (rename AddIn-file to *.AddIn_) whenever you open the main solution. After the main solution
           is opened you can enable it again before you start/debug again.