Build Failures

This topic covers common questions and issues related to general build failures.

• Why does the build fail telling me that it cannot find the Sandcastle or help compiler tools?
• Why does my build fail with an error saying that it cannot find an assembly?
• Why does my build fail with an "Unresolved assembly reference" error?
• Why can't Sandcastle resolve all dependent assembly references automatically?
• After building a help file, I cannot rebuild the projects for the documented assemblies due to an error that says they are already in use by another process. Why?
• Why does my build fail with an error saying "No APIs found to document"?
• Why does my build fail in MRefBuilder with a NullReferenceException related to OrcasNamer.WriteType?
• I'm getting an Out of Memory exception during a very large build. How do I prevent it?
• I want to create a help file without an assembly. When I try to build the help file, it fails and tells me I need at least one documentation source. Why?

First and foremost, be sure that you have installed the latest version of the help file builder and any required help compiler(s). The help compilers are not part of the help file builder and must be downloaded and installed separately. See the Installation Instructions topic for information on where to download the required tools. If you have the tools installed, but in a non-standard location, you may need to specify the paths to the tools. See the Paths Category Properties topic for more information.

When you added documentation sources to the project, you may have specified the wrong name or perhaps chose the assembly from the wrong folder (i.e. .\Debug instead of .\Release). Check the assembly path and filename and verify that it does exist. If the path is correct, make sure the assembly actually exists. Rebuild your project if necessary to recreate it.

If using a solution or project as the documentation source, be sure that the configuration and platform settings are correct and that the assemblies exist for the given combination of configuration and platform. Check both the global settings and, if necessary the documentation source settings to find out what configuration and platform are expected. The build log may also indicate which configuration and platform where found and used.

If the build fails in the Generating reflection information step with an error that starts "Error: Unresolved assembly reference", you need to add the named assembly as a reference. This is done by adding a reference to it in the References node in the Project Explorer window. See the References topic for more information on adding reference items.

Another common cause of this error is not setting the project's Framework Version property correctly. For example, you may have left it set to .NET Framework 4.5 but you are actually documenting a .NET Portable or Silverlight framework assembly. You can typically tell if this is the case as the version number in the error message will not match the framework version in the project. Correcting the project framework version should resolve the issue. Using a Visual Studio solution or project as the documentation source is recommended as the help file builder will figure out the framework version and references automatically based on the project settings.

In some cases, the documented assembly may reference an assembly with a version that is different than the one you have or may reference an assembly that you do not have. In such cases the Assembly Binding Redirection Plug-In can be added to the project to resolve these issues. See the referenced topic for more information.

Sandcastle, specifically MRefBuilder, uses CCI (Common Compiler Infrastructure) for assembly reflection. CCI searches the current directory for dependent assemblies as well as any directories specified by the /dep (Dependencies) command line option. CCI does not attempt to open a dependent assembly until some information from that assembly is needed. CCI is used because technically, CCI never "loads" any assembly; it just parses the data in the assembly file. That is why CCI can reflect over a foreign mscorlib while System.Reflection cannot. This allows Sandcastle to be used for documenting assemblies built with any version of the .NET Framework. CCI is also used by FxCop.

The build engine searches the project folder and all subfolders as well as the project's Component Path property folder if specified for Managed Extensibility Framework (MEF) components that can be used for build components, plug-ins, syntax generators, and presentation styles. Unfortunately, MEF does not unload assemblies that it does not need. If your documented assemblies are in a subfolder below where the help file builder project is stored or the specified Component Path location, they will be loaded during the component search and will not be released until you close Visual Studio or the standalone GUI.

The solution is simple. Move the help file builder project to its own sub-folder so that it does not get to search the folders containing the assemblies being documented. If using the Component Path property to specify a location to search for components, place them in a sub-folder or another location so that it will not find the documented assemblies as well.

Classes need to be declared public in your code, you need to enable the Document Privates and/or Document Internals project property so that Sandcastle documents the internal/private members, or you need to include at least one assembly and at least one namespace to document. There should be at least one assembly, solution, or project file listed in the Documentation Sources node in the Project Explorer window. Use the Namespaces Summaries or API Filter project property editor to be sure that you have at least one valid item that is checked and thus included. If you are using the API Filter property, check it to make sure you have not accidentally excluded everything.

The most likely cause of this problem is that you have the project's Framework Version property set to .NET 1.0 or .NET 1.1 but you are trying to document a .NET 2.0 or later assembly. Check the property to make sure that it is set appropriately for your assembly.

When performing a build that generates an extremely large amount of output, you may encounter an OutOfMemoryException if verbose logging is enabled in the help file builder GUI. If this occurs, turn off the Build window verbose logging enabled option in the user preferences. Full details are still written to the log file and can be viewed after the build.

If the error persists, you may be trying to document too many assemblies or one that contains an extremely large number of namespaces and/or types. The only solution in this case is to break up the project so that it documents fewer namespaces and/or types thus reducing the amount of memory required. If you are building the help on a 32-bit system, switching to a 64-bit system with more memory may allow the build to complete.

If the Help 1 compiler fails due to an out of memory condition, it is doubtful that there is much that can be done. Since it’s a 32-bit process, the Help 1 compiler won’t use more memory than the maximum addressable by a 32-bit process (somewhere between 2GB and 4GB depending on various factors). Switching to an alternate output format such as MS Help Viewer or breaking the project up into smaller parts are probably the only solutions for it.

Sandcastle was designed to document code based on a set of XML comments and API information found in a reflection information file. As such, it requires at least one assembly in order to produce a help file containing API documentation. If you do not include at least one assembly with a namespace containing at least one public class, the help file cannot be produced.

However, you can use the Additional Content Only Plug-In to produce a help file based on conceptual content alone. To do so, add the plug-in to the project via the Plug-Ins project property category, add conceptual content to the project, and build the help file. See the Conceptual Content topic for more information about how to utilize conceptual content.

Other Resources