Select File | New Project

In the Save As dialog box, select the folder in which to save the new project and enter its name. Click Save to create the new project. Once done, the Project Explorer Window and the Project Properties Window will be opened for you.

Ignore the properties window for now and right click on the Documentation Sources node in the Project Explorer. In the context menu, select Add Documentation Source. A documentation source is a file such as an assembly or a Visual Studio solution or project from which information will be extracted to produce API documentation. For this demo, navigate to the help file builder folder (typically C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder) and select the SandcastleBuilder.WPF.dll assembly.

Tip
When selecting either an assembly or an XML comments file, the help file builder will automatically add the partner file for you (i.e. the XML comments file for the like-named assembly or the assembly for the like-named comments file). Multiple files can also be selected and added in one go or dragged from Windows Explorer and dropped on the Documentation Sources node.

Now we will add a reference assembly to the project. References are assemblies that are dependencies of one or more of the documentation source assemblies. They contain information necessary to create inherited member information for the documented classes but that are themselves not wanted in the API documentation. Right click on the References node and select Add File/Project Reference. For this demo, navigate to the help file builder folder (typically C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder) and select the SandcastleBuilder.Utils.dll assembly.

Tip
Given that solutions and projects are supported as documentation sources, you may find it easier to add them as documentation sources instead of the assemblies, comments, and references that they contain. When a solution or project is used, these items are imported from them automatically at build time.

You are now ready to build a basic help file. Select Documentation | Build Project to do so. The help file builder will open the Output Window and start displaying the messages from the build process. Depending on the number of documentation sources, the number of types and members in them, and some other factors, this can take several minutes or, in extremely large projects, several hours.

Tip
All build warnings and errors are reported with a code value. You can look these values up in the Errors and Warnings section of the help file for information about what they mean and possible solutions to fix the problem.

Note

The build process can consume a lot of memory and, if your system has less than 1GB, it may take much more time to complete a build. Another factor that can affect the build time are the Html SDK Link Type, MS Help 2 SDK Link Type, MS Help Viewer SDK Link Type, and Website SDK Link Type project property settings. By default, they are all set to MSDN which causes the BuildAssembler tool to contact the MSDN web service to resolve links to online content for all .NET Framework types and members. If your internet connection is slow, the resulting build will take longer. See the documentation for the above noted SDK link type properties for information on their possible values and the cached build components topic for information on how you can reduce the build time.

Note
When the SDK link type properties are set to MSDN, the build may fail if you are behind a proxy server. See the FAQ for the workaround.

Once the build process finishes, you can select the Documentation | View Help File menu option to view the help file. The default View Help File option displays the help format based on which type or types where built (Help 1, Help 2, MS Help Viewer, or website). You can also select a specific help format to view if multiple formats were built as determined by the Help File Format project property.

Note
In order to view MS Help 2 files, a separate viewer application is required and must be defined in the User Preferences. See the Installation Instructions for information on how to obtain one.

Note
The ASP.NET website is started using the built-in development web server supplied with .NET 2.0 or later. You can alter the settings used for it via the User Preferences.

Select File | New Project from Other Format

Select the project format from the dropdown.

Enter the project name to be converted or click the "..." button to the right of the textbox to browse for a project to convert.

Enter the folder name in which to place the converted project and its related files or click the "..." button to the right of the textbox to browse for a location. This folder must be different from the folder containing the source project being converted. The folder will be created if it does not exist.

Click the Convert button to perform the project conversion. If successful, the converted project is opened ready for use.