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?
• My build fails because I am behind a proxy server and it cannot connect to the cross reference service. How do I fix it?
• My builds seem to hang during the BuildAssembler step. Why?
• 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.

If the SDK link type project property related to the help file format you are building is set to MSDN, BuildAssembler will attempt to contact the cross reference service to resolve links to SDK topics. If you are behind a proxy server, this will most likely fail and will abort the build process with an error similar to "HTTP status 407: Proxy Authentication Required" or "HTTP status 417: Expectation Failed". The simplest fix is to set the HtmlSdkLinkType and WebsiteSdkLinkType properties to None and the MSHelpViewerSdkLinkType property to Id. The downside for the HTML Help 1 and website formats is that you will not get links to online SDK content. For the MS Help Viewer formats, the noted value generates links to the local help content when merged with the collection.

It has been reported that creating a BuildAssembler.exe.config file in the same folder as BuildAssembler.exe (the root help file builder installation folder) and putting one of the following in it may allow it to work with the proxy server:

<configuration>
  <system.net>
    <defaultProxy useDefaultCredentials="true">
      <proxy usesystemdefault="true"/>
    </defaultProxy>
    <!-- Add this setting if you get an HTTP 417 error. -->
    <settings>
      <servicePointManager expect100Continue="false" />
    </settings>
  </system.net>
</configuration>

<configuration>
  <system.net>
    <defaultProxy enabled="true" useDefaultCredentials="true">
      <proxy bypassonlocal="true"
        proxyaddress="http://yourproxy:8080" />
    </defaultProxy>
    <!-- Add this setting if you get an HTTP 417 error. -->
    <settings>
      <servicePointManager expect100Continue="false" />
    </settings>
  </system.net>
</configuration>

<configuration>
  <system.net>
    <defaultProxy useDefaultCredentials="true">
      <proxy scriptLocation="http://your.server.com/proxy.pac"
        usesystemdefault="true" />
    </defaultProxy>
    <!-- Add this setting if you get an HTTP 417 error. -->
    <settings>
      <servicePointManager expect100Continue="false" />
    </settings>
  </system.net>
</configuration>

If your builds seem to hang during the BuildAssembler step, set the HtmlSdkLinkType and WebsiteSdkLinkType properties to None and the MSHelpViewerSdkLinkType property to Id. This will get it to run faster with the side-effect that you will not have links to online SDK content for the HTML Help 1 and website help formats. The only other alternative is to be patient and wait for it to finish. On a slow connection, it can take a very long time. If you are building an MS Help Viewer (MSHC) file, you can set the related option as noted above so that it generates links to the local help content when merged with the collection.

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 build is running out of memory during the BuildAssembler step, you can utilize the cached build components which can drastically reduce the amount of memory used by BuildAssembler as they utilize databases to cache the information. You will need to add the legacy data caching component NuGet packages to the project. Add the components to the project using the Components category in the project properties window. There are two version (ESent and SQL Server) and each is comprised of three separate components (Comments Index Cache, Reflection Index Data Cache, and Resolve Reference Links Cache). Be sure to add them as a matched set to get the full benefits. The ESent build components are the easiest to use as they require no additional set up. They use ESE databases created on first use to cache the information. It takes a good 30 minutes to an hour to build the initial caches when they don’t exist for the base framework information. Once done, subsequent builds are faster than the first and require much less memory. The SQL Server components index the base framework data a lot faster thus the initial cache building process is quicker but it does require access to a SQL server instance (Full, Express, and LocalDB versions are supported). Once the caches exist, subsequent builds are pretty much equivalent to the ESent version with regard to speed and memory usage. It is suggested that you only caching the base framework data first. If BuildAssembler still runs out of memory, you can enable caching of the project data as well. This caches just about everything in the database and frees up the most memory but that comes at the expense of longer build times.

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