DocProject External UI

Introduction

DocProject's External UI is a managed executable located in DocProject's bin directory (commonly found at C:\Program Files\Dave Sexton\DocProject\bin\DocProject.exe). Its purpose is to provide users of the Visual Studio Express line of products with the full feature-set that Visual Studio Standard and higher supports through the DocProject Add-In. This application is required because express editions do not allow add-ins.

DocProject External UI Example Enlarge
Figure 1: DocProject External UI Example

The interface uses a property grid that works just like the grid found in the Active Projects tools options page that is available in Visual Studio Standard and higher. For more information, see How To Configure DocProject.

With this program express users, and even Standard+ users, can configure and build their DocProjects and DocSites outside of the Visual Studio IDE.

Features

  • Configure DocProjects and DocSites using the same tools that are available in Visual Studio Standard and higher via the Active Projects page.
  • Build DocProjects and DocSites just like in the Visual Studio IDE, with a status notification, progress bar and build trace.
  • Before building, choose the current Configuration and Platform from a drop-down list for your DocProject or DocSite and all of its project references.
  • Any project references that are out-of-date are built first using MSBuild.
  • One-click access to build output such as compiled help files (.chm and .Hxs) and Sandcastle configuration files like MRefBuilder.config and sandcastle.help1x.config.
  • Some program state is automatically persisted. This includes the last position, size and window state, with multi-monitor support, the position of the toolbars and the height of the build trace window.
  • The Include Project Output Dialog is displayed after a build is finished to include certain build output as project items, unless the dialog is disabled using the Don't ask me this again setting.

Link From Visual Studio

You can add a link to the program in Visual Studio for quick access by going to Tools > External Tools... and clicking Add.

By specifying the arguments in the figure below, when you run the external UI from Visual Studio's Tools menu the program will automatically open the active DocProject or DocSite in Solution Explorer (that is, the project of the current file that is opened or the current file/folder that is selected in Solution Explorer).

Visual Studio tools registration
Figure 2: Visual Studio tools registration

Choose a descriptive Title, such as "DocProject External UI". The ampersand character (&) marks the accelerator key as the next character (the letter "U" in the example).

Command can be an absolute path to DocProject.exe or you can use the DocProjectPath environment variable for the path information. The DocProjectPath environment variable is registered on your system when you install DocProject. It points to DocProject's installation directory, commonly found at C:\Program Files\Dave Sexton\DocProject.

The DocProject.exe program accepts a single argument, which is the full path and name of a DocProject or DocSite project file. In the example, $(ProjectDir) and $(ProjectFileName) are used to indicate the full path and project file name, respectively, of the active project in Solution Explorer. The value for Arguments must be wrapped in quotation marks in case the path includes spaces.

Build

DocProject.exe will not only build your DocProject's or DocSite's help, but will also build the project's assembly output and any project references using MSBuild first (DocProjects and DocSites are actually MSBuild projects themselves). During the help build, status information describing the current step is visible as well as a progress bar.

Help builds can be canceled by clicking the Cancel toolbar button or the Cancel menu item.

Note: Currently, DocProjects and DocSites that have managed C++ projects as sources are not supported since they can only be built using a solution file.

Extensibility

The code that is used to configure DocProjects and DocSites in Visual Studio Standard and higher is the same code that is executed by the external UI. This means that if you have created a custom build engine provider for your organization it will automatically work with the external UI. Not only does this include the options in your DocProjectOptions implementation, which will appear as new properties in the grid, but also any Visual Studio toolbars that are created by your provider will appear as well.

Sandcastle and Sandcastle/Deployment are examples of build engine providers that are registered in DocProject's configuration file (commonly found at, C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config). Several of the options that appear in the example image, including the Topic Designer and Topic Management dialogs, are provided by the Sandcastle build engine provider plug-in.

Last edited Jun 9, 2008 at 6:42 PM by davedev, version 12

Comments

No comments yet.