How To Diagnose and Resolve Issues

Introduction

This article provides guidance for gathering diagnostic information and fixing failures when using DocProject and also for requesting assistance on the Discussions tab and in community forums.

Errors that occur during normal use of DocProject, such as during installation, project configuration or a build, may derive from a few different components:
  • DocProject Installer
  • DocProject Visual Studio Add-In
  • DocProject plug-ins such as Sandcastle and Sandcastle/Deployment
  • DocProject External UI
  • Visual Studio automation
  • MSBuild
  • Microsoft's external Sandcastle utilities
  • Html Help Workshop
  • Help 2.x COM Services
DocProject provides diagnostic information in a few different places when errors occur, such as Visual Studio's Error List and Build Output window, and your system's Application event log. For more information, see Check the Build Output Window and Check the Application Event Log below.

Read the Release Notes

Before you begin to diagnose failures or request assistance, please make sure that you've followed the setup and configuration instructions in DocProject's Latest Release Notes. If you have not, then uninstall DocProject and its dependencies and try to follow the instructions, which may help to fix the problem(s) that you're experiencing.

You can find a link to the latest release notes in the Wikimap.

Common Issues

Several problems that users often report are related to issues that can be resolved easily.

Installing a Visual Studio SDK
One common issue is installing the Visual Studio 2005 or 2008 SDK, which provides an older Sandcastle CTP and creates a DXROOT user environment variable for it. DocProject uses DXROOT to locate Sandcastle. If you installed an SDK then make sure you delete the DXROOT user environment variable and that the DXROOT system environment variable was installed properly by the latest version of Sandcastle. Its value is commonly, C:\Program Files\Sandcastle\.

Missing documentation comments in output
XML documentation code comments are automatically included in auto-generated reference documentation that's built by Sandcastle. If your comments do not appear in DocProject's output then make sure you have enabled XML documentation output for your source projects. For more information, see Sandcastle Help, XML Documentation.

DocProjectPath is not available to Visual Studio
When the DocProjectPath environment variable is not understood by Visual Studio and MSBuild you'll get an error when loading or building a project. If you experience the following error:

C:\DaveSexton.DocProject.targets project could not be imported

then try to restart Visual Studio. If that doesn't work, try restarting your computer.

The installer creates the DocProjectPath environment variable with system-wide scope when you install for Everyone and user-scope when you install for Just Me. If Visual Studio was left open while you installed DocProject, then it will not use the new environment variable unless it's restarted. Because the addition of a new environment variable requires updates to the registry, the entire system may need to be restarted as well for the changes to take affect.

Known Issues

There are some known issues that you should be aware of before you use DocProject.

DocSite Windows Security Issue
See Docsite Templates, Windows Security Issue about an issue that affects the Download Compiled Help link for all DocSite templates when clicked on a Windows Operating System.

Sandcastle/Deployment and FTP
When using the Sandcastle/Deployment build engine provider, if you specify an FTP url for the target location the source directory structure must already exist on the target machine. Browse to the FTP site in Windows Explorer and create the directory structure as it appears in your project. You must only create those folders that are selected as part of the deployable content.

ClickOnce Issue
Projects that build an executable that is deployed using ClickOnce cannot be referenced by other projects in Visual Studio 2005. The work around for both DocProjects and DocSites is to add these programs as external sources instead of project references.

For information about external sources, see How To Configure DocProject.

Installation Issues

If the DocProject installer fails you should check the Application event log for error events with DocProject or Windows Installer as the source. For help accessing the Application event log, see Check the Application Event Log below.

Installation errors may occur if you are running Vista with UAC enabled and you don't right-mouse click and select Run as Administrator to begin setup. You may also experience errors if the installer cannot copy the templates or the Add-In to their target directories for Visual Studio.

Resolving installation errors might not be possible depending upon whether the issue you're experiencing is the fault of a bug in DocProject's custom installer action or something else. If you need assistance then please create a new thread in the Discussions area. For more information, see Requesting Assistance below.

Build Issues

When building a DocProject or DocSite you may receive warnings and errors in Visual Studio's Error List.

Warnings are commonly generated by Sandcastle's Build Assembler program, describing issues with code comments or reflection data, and can usually be ignored safely.

Errors may occur as a result of configuration issues or other problems with DocProject, Visual Studio or Sandcastle and can be resolved in a number of ways.

Activate the Add-In

Some issues can occur if the Add-In is not activated. As the first step to resolving problems with DocProject in Visual Studio you should ensure that the Add-In is loaded and enabled.

Note: This procedure does not apply to Express editions of Visual Studio since they do not support Add-Ins.

Visual Studio's Add-in Manager
Check that the Add-In is Activated and executed at Startup:
  1. Go to Tools > Add-in Manager....
  2. Check all of the columns for the DocProject Add-In and click OK.
Loading the Add-In
The DocProject installer places the Add-In in a directory where Visual Studio should load it automatically. The Add-In is not regsitered using the registry. If the DocProject Add-In doesn't appear in the Available Add-ins list then Visual Studio did not load it, probably because the Add-In is not in one of Visual Studio's predefined Add-In directories.

First, locate the Add-In to see if it's installed in the correct place. For Just Me installations it will most likely be copied to your My Documents\Visual Studio 2005\Addins folder, but if you've configured a different location for Visual Studio to use then it should have been copied to the location that you specified. If you've chosen to install DocProject for Everyone, then the Add-In will most likely be in your Application Data folder. For pre-Vista systems this is usually located at C:\Documents and Settings\All Users\Application Data\Microsoft\MSEnvShared\Addins and for Vista, C:\ProgramData\Microsoft\MSEnvShared\Addins.

Note: If you've changed the locations where Visual Studio searches for Add-Ins then the DocProject installer should have copied the Add-In to one of your custom folders.

A copy of the Add-In is located in DocProject's installation directory, commonly found at C:\Program Files\Dave Sexton\DocProject\Setup\Addin\DocProject.AddIn. If the Add-In file does not exist in any of Visual Studio's registered locations then you should close all instances of Visual Studio and copy the file from DocProject's installation directory to one of the aforementioned locations. Then restart Visual Studio and check that the Add-In appears in the Add-in Manager as per the instructions above.

Check the Documentation Scope

DocProjects and DocSites are configured, by default, to only document public APIs. If your source projects do not expose any public types then you may discover build errors with Sandcastle programs or the Html Help Workshop program unless you have set the scope of the documentation to include internal types and members.

To document internal members, set the Tools > Options > DocProject > Active Projects > Build > Documentation Scope setting to Complete. For more information see, How To Configure DocProject.

As of the June 2007 CTP, Sandcastle does not issue any warnings or errors if it does not find any types to be documented; however, the MRefBuilder step will write a single line to the Build Output window indicating that no types were documented:

MrefBuilder (v2.2.64000.4)

Copyright c Microsoft 2006
Info: Loaded 1 assemblies for reflection and 1 dependency assemblies.
Info: Wrote information on 0 namespaces, 0 types, and 0 members

If you see the last Info: message with all zeros then you should either make one or more types public or change the Documentation Scope setting as indicated above; otherwise, if you've configured your project to produce Help 1.x output, then the Html Help Workshop program may fail, producing error information such as this:

HHC5003: Error: Compilation failed while compiling html\.htm.
HHC6000: Error: An internal file could not be created. Make certain there is enough disk space on the drive where you are compiling your file.
HHC5007: Error: Fatal navigational compilation error. This is likely the result of an invalid contents (.hhc) file.
The following files were not compiled:
html\.htm

Check for Missing Dependencies

The MRefBuilder step may produce an error about one or more missing dependencies. These errors will appear in Visual Studio's Error List when the build fails.

DocProject attempts to resolve dependencies automatically, and usually succeeds, but there are some circumstances where DocProject might not be able to resolve all of your project's dependencies.

If you are experiencing this failure then as of the 1.7.0 Release Candidate and 2008 Beta you can manually add missing dependencies to the Tools > Options > DocProject > Active Projects > Build > Missing Dependencies dialog. For more information see, How To Configure DocProject.

Check the Build Output Window

DocProject provides information about the help-build process to Visual Studio's Build Output window during a help-build. The output includes information about the current executing step, any messages that each build step produces as they are executed and error information if the process fails.

Note: To view the build output during a help-build you must set Tools > Options > Projects and Solutions > Build and Run > MSBuild project build output verbosity to a value of Normal or higher. Normal may be the default setting in Visual Studio Standard and higher, but Express users may have to configure this setting manually.

If you are experiencing difficulty building a DocProject or DocSite then check the Build Output window for more information about unexpected behavior and errors, such as the steps in which errors have occurred and any informational messages that may have been produced.

Check the Application Event Log

DocProject creates an error event in your system's Application event log when an error occurs in one of DocProject's configuration dialogs or when a help-build fails. A stack trace is provided in logged error events along with other information that may be useful in diagnosing problems.

Since DocProject does not output a stack trace in the Build Output window when an exception is thrown, you should check the Application event log to gather more information about exceptions:
  1. Go to Start > Administrative Tools > Event Viewer
  2. Select the Application event log and look for events with DocProject in the Source column.
Note: On Windows Vista the Application event log is located under the Windows Logs folder.

Try Using MSBuild on the Command-Line

If you still can't determine the cause of an error after gathering information from the build output window and the Application event log, you may want to try building your DocProject or DocSite on the command-line using the MSBuild.exe program to determine whether Visual Studio automation may be a factor.

For instructions see How To Build Compiled Help With MSBuild.

If you're not able to build on the command-line then the problem you're experiencing does not have to do with Visual Studio's automation interfaces; however, there may be an issue in DocProject's interfaces for MSBuild.

Note: Managed C++ projects are built using automation interfaces on the command-line as well. Therefore, you cannot rule out a problem with VS automation if you're building help for a managed C++ project and you still can't build your DocProject or DocSite using MSBuild.

Requesting Assistance

If you are having trouble using DocProject and you've already followed the instructions in the latest release notes and this article, you may be able to find assistance in the community.

Please follow these guidelines when participating in community discussions and forums:
  1. Search first before asking. The forums already contain answers to many problems, so please make sure that your question hasn't already been asked before starting a new thread.
  2. Use the appropriate forums. If you ask your question in the appropriate forum then you may receive a better, faster response; otherwise, you may not receive any response at all.
  3. Be explicit. Include a description of the problem, the software being used, version numbers, steps for reproduction and any error messages and diagnostic information that may be available.
  4. Be patient. The forums are not like instant messaging software, so please check back for a response periodically. Depending upon the activity of the forum, it may take anywhere from a few seconds to several days, or even weeks or months, before you get an answer to your question.
  5. Follow-up. When someone responds to your question please indicate whether they have solved your problem. If they haven't solved the problem yet then more information may be required from you. Indicating which posts were helpful will also be useful to other community members experiencing the same problems as you.

Sandcastle Forum

DocProject does not generate documentation itself. Sandcastle, the Html Help Workshop compiler and the Help 2.x compiler are used to generate HTML documentation and compiled help.

For questions relating to:
  • xml comment tags
  • missing documentation
  • style and format issues
  • language filters
  • problems using compiled help (.chm and .HxS)
  • warnings and errors produced by Sandcastle tools and the help compilers
please search Microsoft's Developer Documentation and Help System forum for answers.

For problems that are not related to the software on which DocProject depends, please search for a solution in DocProject's Discussions area or start your own thread if your question has not been asked already.

Start a New Thread

When you start a new thread in DocProject's Discussions area or Microsoft's forums, be sure to provide the error number and message, your OS version, the versions of Visual Studio that you have installed on your system and any other software that may be related to or affect DocProject. If you can obtain an exception stack trace or more information from the build output window and the Application event log that should be extremely useful as well.

Here's an example of a decent post that should provide enough information for an initial diagnosis:

{quote:}
I get a NullReferenceExcpeption when I try to build my DocProject. Here is the error message from the build output window, along with the last few messages from the current build step (Step #15):
...

I was able to retrieve a stack trace from the Application event log as well:
...

I'm running Windows Vista with UAC enabled and Visual Studio 2005 Standard SP1. I've followed the instructions in the release notes and installed Sandcastle June 2007 CTP, HTML Help Workshop and DocProject 1.7.0 RC, in that order.
{quote}

Private Issues

For private issues or when you must post proprietary data for the problem to be diagnosed you can contact Dave Sexton directly; otherwise, the Discussions area is preferred so that information about the problem and its potential solutions may help other community members as well.

Last edited Jun 11, 2008 at 1:18 AM by davedev, version 9

Comments

No comments yet.