API Filter Property

The API Filter editor provides a form used to choose the API topics that will appear in the help file. It allows you to include or exclude namespaces, types, and members from the documented assemblies as well as those from inherited .NET Framework and third-party dependency assemblies. To access it, select the Visibility category of project properties and click the Edit API Filter button. When clicked, the following dialog box appears.

This topic contains the following sections:

• The API Tree
• Including and Excluding Members
• Searching for Members
• The Search Options
• See Also

When first opened, there is a slight delay as a partial build of the project is performed in order to generate a list of the API members that can appear in the help file. A tree view containing the API members appears on the left side of the dialog. The tree contains two root nodes. The first, Documented APIs, contains all members from the documented assemblies that can appear in the help file. This list is based on the current project settings. Members excluded by the other Document* project properties in the Visibility category will not appear here. The second root node, Inherited APIs, lists the base classes from which the documented APIs inherit. This list will include classes from the base .NET Framework and other third-party dependency assemblies. Information from these classes will appear on the member list pages for each of the documented classes. By unchecking items in this set of classes, you can remove unwanted members that may otherwise clutter the member list pages.

You will notice that some tree nodes are in italic text. This indicates that the node cannot be unchecked by you. Hovering the mouse over the node will show a tool tip describing why it cannot be unchecked. The reasons include:

• It is one of the two root nodes. These are general containers and cannot be unchecked.

• It is a namespace that contains a set of inherited types from the .NET Framework or a dependency assembly. These namespaces will not be represented in the help file. You may exclude individual inherited classes from the namespace as well as inherited class members to control what information appears in a documented class's member list page.

• A namespace is excluded via the Namespace Summaries property or an item is excluded because its XML comments include an <exclude /> tag. This information is merged automatically with the API filter settings. To alter these items, you will need to use the Namespace Summaries property or remove the tag from the item's XML comments.

An icon appears next to each node that provides information about what it represents and its visibility. These icons correspond to the search options in the upper right side of the dialog. Public members show the basic icons from Namespaces through Fields. Protected, internal, and private members will show a combination of the basic icon plus the appropriate visibility icon. The names of the items will appear as they do in the help file. One difference is that parameter information and any overloaded members are not listed. This is because the API filter only goes by name. Parameter information is not used. As such, if one overloaded member is excluded, all overloaded members are excluded.

All checked items will appear in the help file. To exclude an item, simply uncheck it. Checking or unchecking a namespace or type will automatically check or uncheck all of its nested members as well. On a similar note, if you uncheck a majority of the members of a namespace or type, you may notice that the parent node is also unchecked and changes color. Checking a majority of the members will cause the parent node to also become checked and resets the background color. This behavior is normal and is done to produce a more efficient API filter. The different color helps identify namespaces and types in which not all child members are excluded.

The search options appear in the upper right side of the dialog. To search for an item, simply type some text in the search text box, set the filter options as needed, and click the Find button. The search results will appear in the list view below the options. The Members Found column lists the name as it will appear in the help file. The Full Name column lists the item's full name including the namespace and type information. The items are grouped by namespace and type in alphabetical order. Documented API matches are listed first followed by matches from the inherited APIs. The search text can be as simple as a fragment of a member name or it can be a regular expression used to find more complex patterns. See The 30 Minute Regex Tutorial for a brief introduction to regular expressions and how to use them. See the .NET Framework Regular Expressions help topic for complete details about the various regular expression elements and options. A few simple search examples are show in the table below.

In the absence of any regular expression operators, the search will return all members containing the specified text as shown in the first example.

The following options affect how the search is performed and the results that it will return. By default, the searches are case-insensitive, only search the member names as displayed in the tree view, and include members of all types and visibility in the results.

Double-clicking on a member in the search results or clicking the Goto button below the list will take you to the selected member in the tree view. You can select multiple members in the search results by clicking and dragging the mouse or by using the keyboard. Clicking Include or Exclude will include (check) or exclude (uncheck) all of the currently selected members in the search results. To clear the API filter and set it back to its default state, click the Reset button.

Other Resources