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 SDKOne 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 outputXML 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 StudioWhen 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 importedthen 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 IssueSee
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 FTPWhen 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 IssueProjects 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 ManagerCheck that the Add-In is
Activated and executed at
Startup:
- Go to Tools > Add-in Manager....
- Check all of the columns for the DocProject Add-In and click OK.
Loading the Add-InThe 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:
- Go to Start > Administrative Tools > Event Viewer
- 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:
- 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.
- 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.
- 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.
- 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.
- 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.