Walkthrough: Creating Your First Project

This walkthrough will guide you through creating your first help file builder project.

  Important

This walkthrough assumes that you are using the standalone GUI for the help file builder. If you are using the Visual Studio extension package, the process is similar but the command locations will be different in some cases. For an overview of the Visual Studio extension package and how to find commands in it related to the standalone GUI, see the Visual Studio Integration Package topic.

Prerequisites

Before creating a help file builder project, be sure that you have installed all of the necessary tools and that you have enabled XML comments in your project and added some comments to your code.

New Projects

Creating a Brand New Project

  1. Select File | New Project

  2. 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 Solution/Project Explorer Window and the Project Properties Window will be opened for you.

  3. 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 .\Tools\Sandcastle.Platform.Windows.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.

  4. 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 .\Tools\Sandcastle.Core.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.

  5. 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 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 cross reference 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.

      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.

  6. 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, MS Help Viewer, Markdown, 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

    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.

If you created the project using the Visual Studio template, the project will contain a content layout file, logo image, and some default conceptual topics (a welcome page and simple version history). See the welcome topic for some general information on adding and managing conceptual content. See the Conceptual Content topic and its subtopics for more specific information on conceptual content. See the Sandcastle MAML Guide help file for more information on the MAML elements that are used to create conceptual topic files.

Next Steps

Now that you have created and built your first project, explore the other sections and topics in the help file to learn more about the other features available in the help file builder.

See Also