How To Use The Source Code

Introduction

DocProject is an open source development effort. Please review the license in the License area of this website and make sure that you understand it before attempting to modify or redistribute DocProject's source code. The source code is available for download in the Source Code area of this website.

You can use DocProject's Visual Studio 2008 solution and projects to make modifications to the add-in or project templates. You can also attach the Visual Studio debugger to your DocProjects and DocSites while they are being used in another instance of Visual Studio to step through DocProject's code.

Getting Started

First make sure that you have a development computer with all of the required prerequisites installed. Then follow the instructions below to prepare DocProject's solution so that you can build it.

Requirements

  • Visual Studio 2008 Standard or higher with Visual C#, Visual Basic and Visual C++ installed.
  • The latest supported version of Sandcastle.
  • The HTML Help Workshop (for Help 1.x).
  • The Visual Studio 2005 or 2008 SDK (for the Help 2.x COM API).
  • IExpress, if you plan to build the installer as a self-extracting executable like the one available on the Releases page.
    • Note: This utility is available on Windows XP and later. You can verify whether it's available on your computer by going to Start > Run, typing iexpress and pressing OK.
See the Latest Release Notes for more information and links to downloads.

Note: The solution may be opened in Express editions or in full editions that don't have Visual C++ installed, but then you must remove all code that depends upon features that you don't have on your system. That is beyond the scope of this article, however.

Preparation

  1. Download and install the software on which DocProject depends, which includes all required and optional software according to the Latest Release Notes.
  2. Download and install the latest version of DocProject. (It must be installed to debug the source code.)
  3. Download the latest changeset from the Source Code area of this website.
  4. Download and install the DSZip utility if you plan on rebuilding the DocProject installer.
For help with installation, see How To Install DocProject.

Setting Up The Solution

DocProject's solution contains all of the projects that are required for DocProject to run. The solution requires Visual Studio 2008 and all of the projects target the .NET Framework 2.0.

After you have prepared your computer and downloaded the latest changeset:
  1. Extract the changeset ZIP file onto your development computer.
    1. Note: The location is not important, but something like C:\Projects\DocProject is recommended to keep the file paths short.
  2. Double-click the DaveSexton.DocProject.sln file in the Main\Source\DocProject\ folder to open it in Visual Studio.
  3. Click Cancel each time you're asked to connect to source control, for each project, until you are no longer prompted.
    1. Note: This step only applies if you have installed Team Explorer. If you haven't you may just receive a message about the source control bindings being invalid instead.
    2. Express editions of Visual Studio show warnings that DocProject's solution folders will be added as unloaded projects. They may be safely deleted from the solution. Note that a few other projects of unsupported types will also be unavailable in Express editions.
  4. When the final dialog is presented, select Permanently remove source control association bindings and click OK.
    1. Note: You might be asked whether you want the bindings removed; in that case click Yes.
  5. If prompted for a password by the Import Key File dialog, just click Cancel.
  6. Wait for Visual Studio to open the solution.
After the solution has finally opened:
  1. Find the DaveSexton.Sandcastle project in the Projects > Utilities solution folder, expand its Properties folder and delete the DocProjectPrivate.pfx file.
  2. Save the solution.
  3. Try building the solution now. If the build fails see the Troubleshooting section of this document.
    1. Note: You will attempt to debug the add-in later in Testing The Solution.
Note: If the BuildAssemblerLibrary reference in the DaveSexton.DocProject project has a warning icon then you must add the reference manually by first deleting the broken reference and then using the Add Reference... dialog to browse to the Sandcastle installation directory. The BuildAssemblerLibrary assembly can be found in the ProductionTools folder.

Strong-Name Key Files
The key files that are used to sign various assemblies are provided with the source code and cannot be changed.

The DocProject installer places a dependency on the assemblies that it installs in the global assembly cache (GAC). The installed assemblies cannot be removed from the GAC until the package is uninstalled. If you were to create your own key files to sign DocProject's assemblies you would be changing the signature of the assemblies, so when DocProject's post-build events install the newly built assemblies into the GAC they wouldn't replace the installed versions; instead, they would be installed side-by-side. Visual Studio will end up loading both copies in memory and you'll receive errors such as, SomeClass cannot be cast into SomeClass.

Projects

DocProject's main solution consists of multiple projects: one Visual Studio Add-In project, two DocProject Plug-In projects, one installer actions project, one Setup and Deployment project, two custom control libraries, one WinForms project, one utility library and one Sandcastle build component library. There are also multiple template projects that are not built with the solution; their only purpose is to hold the files that will be added to the templates when they are generated by the InstallAction project's post-build event.

DaveSexton.DocProject.ExternalUI

WinForms project that builds the DocProject.exe program, which provides external configuration and build capabilities originally intended for the Visual Studio Express line of products.

For more information, see DocProject External UI.

DaveSexton.Controls.HtmlEditor

This project builds the HTML editor control that is used by the Topic Management, Topic Designer and Help 2.x Project Configuration dialogs, as well as the Topic Editor tool window. It's used as both an XML documentation editor and an editor for raw HTML files.

All of the editors that use the HTML editor control are provided by the Sandcastle build engine provider, not the DocProject core assemblies.

The HtmlEditor has a dependency on Microsoft's MSHTML primary interop assembly, Microsoft.mshtml. This PIA will be installed on all systems that have Visual Studio Standard edition or higher. Systems with only Visual Studio Express editions will have to install Microsoft's vs_piaredist.exe redistributable or the .NET Framework SDK in order to acquire this prerequisite; however, the DocProject installer will offer to install this redistributable if it detects missing dependencies before DocProject is installed. (See the Installer project below for more information.)

A post-build event is used to install the latest build of the assembly into the GAC for debugging purposes.

DaveSexton.Controls.XmlTreeView

This project builds the XML tree view control that is used by the Topic Management dialog and the Topic Explorer tool window. The control supports internal and external drag/drop operations, label edits, recursive checking, owner draw, a data manager class and an IXPathNavigable data source.

The XML tree view control is only used by the Sandcastle build engine provider, not the DocProject core assemblies.

A post-build event is used to install the latest build of the assembly into the GAC for debugging purposes.

DaveSexton.DocProject

This project creates the add-in assembly for Visual Studio and also provides the MSBuild task used by the DocProject and DocSite templates. The assembly produced by this project is DocProject's core assembly, providing the foundation on which help generation tools can plug-in to Visual Studio; e.g., the Sandcastle build engine provider plugs in to Visual Studio by building on top of the public APIs that are exposed by this core assembly.

A post-build event is used to install the latest build of the assembly into the GAC for debugging purposes. The next time you build the solution and attach to a new instance of Visual Studio, the latest version of the add-in will be loaded and all DocProjects and DocSites will automatically use the latest version.

DaveSexton.DocProject.Sandcastle

This project provides the Sandcastle build engine provider plug-in, which appears in the drop down list in the first step of the New Project Wizard. It also builds all of the tools related to Sandcastle such as the Sandcastle toolbar, the Topic Management and Topic Designer dialogs, as well as Visual Studio tool windows like Topic Explorer and Topic Editor, for example.

The plug-in is registered with the Visual Studio add-in's configuration file, DaveSexton.DocProject.dll.config, which is installed by the Windows Installer package into the {target}\bin directory along with the Add-In assembly itself.

A post-build event is used to install the latest build of the assembly into the GAC for debugging purposes.

DaveSexton.DocProject.DeploymentSandcastle

This project provides the Sandcastle/Deployment build engine provider plug-in, which appears in the drop down list in the first step of the New Project Wizard. Its purpose is to extend the DaveSexton.DocProject.Sandcastle project by adding automatic deployment capabilities.

The plug-in is registered with the Visual Studio add-in's configuration file, DaveSexton.DocProject.dll.config, which is installed by the Windows Installer package into the {target}\bin directory along with the Add-In assembly itself.

For more information, see Sandcastle Deployment Plugin.

A post-build event is used to install the latest build of the assembly into the GAC for debugging purposes.

DaveSexton.Sandcastle

This project is intended to contain various Sandcastle extensibility features like custom build components and syntax generators, for example. It is used by DocProject but it also may be distributed without DocProject, as a stand-alone utility for use with other automation tools and command-line builds.

Currently, it only contains ResolveExternalLinksComponent, which is a custom Sandcastle build component that enhances the behavior of see and seealso elements in XML documentation and the link element in MAML topics.

DaveSexton.DocProject.DocSites

Utility library that provides administrative, navigational and search functions for the DocSite Templates.

This project defines the QueryExpressionFactory, and supporting classes, which are used to parse a search query into an in-memory graph of QueryExpression objects. It also defines the DocSiteMemorySearchProvider class, and the supporting search provider codebase, which is used by default for producing an in-memory, full-text search index.

A post-build event is used to install the latest build of the assembly into the GAC for debugging purposes.

Note: DocSite templates have a reference to this assembly in the GAC, but Copy Local is true so that it's copied to the project's output directory when the project is built. This assembly must be deployed with DocSites to a production web server, although it may reside in the project's bin folder instead of the GAC; DocProject does not have to be installed on the web server.

Template Projects

The template projects provide an easy way to configure the templates that are installed with DocProject. For more information about the templates, see DocProject Templates.

The template projects are not intended to build with the solution, and therefore are configured to be excluded. Although building the solution will not build the template projects, you may notice errors in the Error List that belong to one or more of these projects. You can safely ignore these errors. See Troubleshooting below for more information.

The contents of each template project is automatically added to the Visual Studio Content Installer file (.vsi) generated by the InstallActions project each time it's built.

Note: The templates' project files that are part of DocProject's solution (e.g., .csproj, .vbproj) are not included in the template ZIP files; instead, the project files are copied from the Installer Content > Project Templates solution folder so that they may contain replacement tokens.

DaveSexton.DocProject.Installer

This project builds the Windows Installer file (.msi) that installs DocProject. No manual configuration or preparation is necessary due to the build automation process of the InstallActions project. Building the Installer project will automatically cause the InstallActions project to build first if it's configured to build with the solution; otherwise, you must build the InstallActions project manually before building the Installer project.

Make sure to exclude all of the dependencies in the "Detected Dependencies" folder except for the "MIcrosoft .NET Framework" dependency.

The .vsi file and the zipped templates that are created by the InstallActions project, and also the .AddIn files found in the subfolders of Main\Source\DocProject\Install\Addin, are all imported by the Installer project. If you want to create a custom template using the solution then you must add your template to the Installer. For more information, see Creating New Templates.

The Windows Installer file (.msi) that is generated by this project is patched automatically after it's built via a post-build event on the Installer project. The batch script that performs the update is named, UpdateMSI.bat and it's located in the Build Scripts > Install solution folder.

For help building the Installer project, see Building the Installer below.

DaveSexton.DocProject.InstallActions

The InstallActions project has a few functions relating to the preparation of the Installer project.
  • Post-build event that builds the templates into zip files, using the DSZip utility. Zipped templates are required by Visual Studio.
  • Post-build event that builds the Visual Studio Content Installer file that is included in the Windows Installer package.
    • Note: As of the 1.5.0 RC, the VS Content Installer is no longer used by the Windows Installer package; however, it's still copied to the installation directory for users, if needed.
  • Contains the custom installer action that is executed by the installation wizard. It is part of the InstallActions assembly, which is copied by the installer to a folder named, Setup on the target computer so that it can be executed during the installation.
The first two items in the list are performed by the InstallerActionsPostBuild.bat file (found in the Build Scripts > Install solution folder) after a successful build of the InstallActions project. The last item, a custom installer action, is executed by the Windows Installer wizard when you install DocProject.

The Installer project depends upon the InstallActions project being built successfully. The InstallActions project depends upon the Add-In project being built, but will execute its script even if the project output has not been updated. This features allows you to make changes to the template projects only and still have the InstallActions project perform its preparation tasks, even though the project output was never updated.

Custom Installer Action
The assembly output of the InstallActions project contains the installer action that is used by the Windows Installer package (.msi). The action installs the add-in and the templates onto the target computer.

A directory named, Setup is created by the installer on the target machine. The InstallActions project output and the required content files (e.g., templates and add-in) are copied there by the installation wizard before the installer action is executed. The installer action uses this directory when it performs its work.

Depending upon whether the user selected Everyone or Just me in the installation wizard, the installer action will copy the content files to either a shared directory or the user's personal folder, respectively.

If you have configured Visual Studio's user project templates folder then the installer action will attempt to copy the files to the specified location. If you have modified the list of automation folders in which Visual Studio will search for add-ins, the installer action will still attempt to install the content into the preferred location; otherwise, if the location doesn't exist, the content will be installed in one of the specified locations.

DSZip Utility
The InstallActions project relies on the DSZip utility to perform the tasks in the ZipTemplates.bat file (found in the Build Sripts > Install solution folder). Download and install the DSZip program from the Releases page if you haven't already. Without this utility you'll have to create the Visual Studio Content Installer file (.vsi) and the zipped template files manually if you're planning on using the Installer project. Otherwise, if you aren't going to use the Installer, then you can remove the InstallActions and Installer projects from the solution.

Building the Visual Studio Content Installer File
When the InstallActions project is built, the post-build event runs the InstallerActionsPostBuild.bat file, which then runs the ZipTemplates.bat file, which performs all of the work to compile the Visual Studio Content Installer file (.vsi). The .vsi file is not included as a project item since it's built for the first time as a result of building the InstallActions project. It's located in the Main\Source\DocProject\Install folder.


The templates' project items are copied to a pre-configured directory for the template under the Main\Build\Install folder each time the InstallActions project is built. The content of each template directory is built into a ZIP file, which includes the content that already exists in the Main\Build\Install\Project Templates subfolders. Each zipped template file is then added to the Visual Studio Content installer file (.vsi) as the last step of the InstallActions project's build process.

Each of the zipped template files are copied to a subfolder of the Main\Source\DocProject\Templates folder, from where the Installer project will copy them into the installer package.

Note: The entire ZIP process is actually executed twice: once for Visual Studio 2005 content and again for Visual Studio 2008 content.

The template project files themselves (e.g., .csproj, .vbproj) and source control files are not copied, but the source code and content files are. The copy is a deep copy, meaning that all files and folders that aren't excluded by the xcopyx.txt file will be imported, recursively. The files and folders that are copied are found on disc, not in the projects; therefore, all files that exist in the template project directories may be copied, even if they are not project items.

Here is an overview of what the ZipTemplates.bat file does, in order:
  1. Copy the source files of each template project into their pre-configured content directories.
  2. Using the DSZip utility, each of the pre-configured template content directories are zipped.
  3. Using the DSZip utility again, all of the template zip files are zipped together into an aggregate zip file.
    1. Note: Additional files are included in the aggregate zip file, such as the Add-In and EULA.
  4. The aggregate zip is renamed with the vsi extension. Therefore, changing the extension of the .vsi file back to .zip will allow you to see its contents in Windows Explorer.
  5. The zipped templates are copied to a subfolder of the Main\Source\DocProject\Templates folder so that the Installer project can include them.

Testing The Solution

  1. Close all instances of Visual Studio.
  2. Locate the add-in directory on your computer, commonly under My Documents/Visual Studio 2005/Addins.
    1. Locate the DocProject.Addin file and copy it to the same directory.
    2. Rename the original file to DocProject.Addin so that Visual Studio will ignore it (Note the underscore_).
    3. Rename the copy to DocProject - For Testing.Addin.
  3. Open the DaveSexton.DocProject solution in Visual Studio.
  4. Add the copied file to the Visual Studio solution for quick access. It doesn't matter where it's added, but it may be easier to locate as a solution item (not within any particular project).
  5. Open the file and change the assembly path to the bin directory of the project's output.
    1. Note: There are two assembly tags. The first one should be modified. The tag that is defined for the tools options page near the bottom of the file should be left alone. The tools options page assembly tag points to the assembly in the GAC, which the add-in keeps up-to-date each time it's built.
  6. Set the DaveSexton.DocProject project as the startup project. (It's the only project in the Projects > Visual Studio Add-In solution folder.)
  7. Open the Properties window for the DaveSexton.DocProject project.
    1. Select the Debug tab.
    2. Under Start Action check Start external program and browse to the Visual Studio executable (commonly found at C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe).
    3. Enter the following Command line arguments in the box below: /ranu /rootsuffix Exp /resetaddin DaveSexton.DocProject.DocProjectAddIn.
      1. Note: The /ranu /rootsuffix Exp portion causes the Visual Studio Experimental Hive to open instead of a normal instance of Visual Studio. This is useful for debugging purposes since the hive can easily be reset at any time.
    4. Set the Working directory to the directory in which the devenv.exe program is located.
    5. Close the project properties and save the solution.
  8. Press F5 to build the project and to attach to a new instance of Visual Studio.
From here you can create or open a solution, add a new DocProject or DocSite, and test the build process with full debugger support. For more information on adding a DocProject or DocSite to a solution see How To Build Compiled Help With DocProject.

Building the Installer

Follow these instructions to build the Installer project and to create a self-extracting cabinet installer that contains the Windows Installer file (.msi) and the Setup.exe bootstrapper, like the installer that is available on the Releases page:
  1. Build the solution.
  2. Locate the vs_piaredist.exe redistributable on your computer and copy it to the Main\Build\Install\Bootstrapper\vs_piaredist folder.
    1. Note: You can find this file in %ProgramFiles%\Common Files\Merge Modules\ with Visual Studio 2005 installed. If you only have Visual Studio 2008 then you must use vs90_piaredist.exe instead (you'll find it in the same folder) and simply rename it.
  3. Build the InstallActions project manually (it's not configured to build with the solution in DEBUG mode.)
  4. Build the Installer project manually (it's not configured to build with the solution in DEBUG mode.)
Important: Automatic prerequisites are no longer used as of DocProject 1.11.0 RC and also the self-extracting executable is now generated automatically by the build process. The setup.exe bootstrapper that was built for earlier versions of DocProject is included in the Bootstrapper folder and it's copied to the working folder by a batch script when the self-extracting executable is being created. The script executes automatically after the Installer has been built.

Troubleshooting

For additional troubleshooting information, see How To Diagnose and Resolve Issues.

Template Projects
Ignore the template errors since they are not configured to build with the solution. The Project column will indicate whether the error corresponds to a template project.

Installer Project
Errors related to the DaveSexton.DocProject.Installer project usually indicate an error in one of the projects that build with the solution, even though the installer project itself does not.

Fixing the errors in projects that build with the solution usually fixes the installer errors. Actually building the solution may fix the installer errors as well.

Note: You may get a warning that states, "Found conflicts between different versions of the same dependent assembly". It's referring to a binding redirect in the External UI project's app.config file, but the warning must be ignored. (Although, if you double-click the warning and choose to let VS fix the issue it probably won't have any effect anyway.) The custom action provided by the InstallActions project automatically updates the External UI's configuration file after it's installed on the target machine. Depending upon certain factors, such as the version of MSBuild that is currently installed, the custom action may add or remove various binding redirects that are required for the program to function properly. For debugging purposes in Visual Studio 2008, the redirects that are currently present in the configuration file must remain unchanged.

Projects That Build With The Solution
Try to locate the errors that belong to the DaveSexton.Controls.HtmlEditor, DaveSexton.Controls.XmlTreeView, DaveSexton.DocProject, DaveSexton.DocProject.Sandcastle, DaveSexton.DocProject.DeploymentSandcastle, DaveSexton.Sandcastle and DaveSexton.DocProject.ExternalUI projects since they are configured to build when you build the solution in DEBUG mode. Resolving errors related to these projects is usually enough to build the solution.

Note: Warnings related to these projects are usually resolved by fixing their errors first.

DSZip
Don't forget to look at the information in the Build Output window when you try to build the InstallActions project. You may notice an error indicating that the DSZip utility could not be located.

You have two options if the DSZip utility has not been installed:
  • Install the DSZip utility (it must be downloaded separately).
-or, if you don't want to build the installer-
  • Remove the InstallActions and Installer projects from the solution.

Last edited Jun 11, 2008 at 1:14 AM by davedev, version 57

Comments

No comments yet.