Sandcastle and Proxy Servers

Note: Much of the information in this article has been provided by Eric Woodruff from his FAQ topic for the Sandcastle Help File Builder.

Sandcastle uses the MTPS web service to resolve references to .NET Framework topics and automatically creates the appropriate hyperlinks to MSDN online in your documentation. If you're using a proxy server then Sandcastle must be configured appropriately so that it can connect to the web service, although you can disable this feature instead using the None reference resolution link type in the sandcastle.config file.

If you are behind a proxy server and Sandcastle is not configured appropriately then it will most likely fail with an error similar to the following:

{quote:}
HTTP status 407: Proxy Authentication Required
{quote}

Configuring DocProject to use a Proxy Server
If you are using DocProject and:
Configuring Sandcastle to use a Proxy Server
It has been reported that adding the <defaultProxy> Element to the BuildAssembler.exe program's managed configuration file may solve this problem.
  1. In Windows Explorer, browse to the Sandcastle installation directory, commonly C:\Program Files\Sandcastle (same as the value of the %DXROOT% environment variable).
  2. Browse to the ProductionTools folder.
  3. Create a new file named, BuildAssembler.exe.config.
  4. Add a proxy configuration that is appropriate for your environment (see below for examples).
  5. Save the file. The next time you run BuildAssembler.exe it should use the new proxy settings.
Example 1: System settings (commonly used)
<configuration>
    <system.net>
        <defaultProxy useDefaultCredentials="true">
            <proxy usesystemdefault="true"/>
        </defaultProxy>
    </system.net>
</configuration>

Example 2: Specifying the proxy server address
<configuration>
    <system.net>
      <defaultProxy enabled="true" useDefaultCredentials="true">
        <proxy bypassonlocal="True"
            proxyaddress="http://yourproxy:8080" />
      </defaultProxy>
    </system.net>
</configuration>

Example 3: Using a proxy configuration script
<configuration>
    <system.net>
      <defaultProxy useDefaultCredentials="true">
        <proxy scriptLocation="http://your.server.com/proxy.pac"
            usesystemdefault="True" />
      </defaultProxy>
    </system.net>
</configuration>