Filtering APIs using Sandcastle


 


API filters in Sandcastle is a very useful feature and allows namespaces, types, and members to be removed or shown in the reflection XML file, and ultimately in the compiled docs. They can be set up so that only certain topics are dropped, or so that a parent type has all children hidden with only specific ones shown. The API filter configuration can be found in ProductionTools\MRefBuilder.config file and is contained within an apiFilter element.


If no apiFilter element exists the default is to expose everything. This is the same as having an empty apiFilter element that is exposed such as


<apiFilter expose="true"></apiFilter>


 


 


Setting expose to false will hide everything, which is useful if you wish to expose only certain namespaces, types, or methods.


 


<apiFilter expose="false"></apiFilter>


 


 


Filter Inheritance


Filters inherit from their parent filter, with the exception of nested types which look to their parent type(s) before the namespace filter.


 


In the example below, only ThirdNamespace will be exposed. All other namespaces will be left out. Also, all types in ThirdNamespace and methods within those types will be shown. Types and methods in other namespaces will be left out.


 


<apiFilter expose="false">


    <namespace name="ThirdNamespace" expose="true"></namespace>    


</apiFilter>


 


This filter shows everything except for ThirdNamespace and it types and members.


 


<apiFilter expose="true">


    <namespace name="ThirdNamespace" expose="false"></namespace>   


</apiFilter>


 


 


If a filter is exposed within a non-exposed filter it will still be shown. The example below results in only the single method being exposed along with its declaring types. No other children of the declaring types are exposed. Without the filter for MyMethod, or with the filter set to false, everything will be hidden.


 


<apiFilter expose="false">


  <namespace name="MyNamespace" expose="false">


        <type name="MyClass" expose="false">


              <member name="MyMethod" expose="true" />                    


        </type>


  </namespace>           


</apiFilter>


 


A filter to show all types within MyClass, but leave out MyMethod and MyMethod2 would look like this


<apiFilter expose="false">


  <namespace name="MyNamespace" expose="false">


        <type name="MyClass" expose="true">


              <member name="MyMethod" expose="false" />                   


              <member name="MyMethod2" expose="false" />   


        </type>


  </namespace>           


</apiFilter>


 


Nested Types


Nested types inherit from their parent type. If a type is nested within other nested types it will go through the parent types until it finds a filter.


In the examples below are filters for a class with contains a class called MyNestedNestedClass which is nested within MyNestedClass. MyNestedClass is nested with a class called MyClass.


MyNamespace
     - MyClass
        - MyNestedClass
            -MyNestedNestedClass


This filter will hide everything except for MyNestedClass and its types. Since we set MyNestedNestedClass to be hidden it will not show up. MyClass is also hidden since MyNamespace is not exposed.


<apiFilter expose="false">


  <namespace name="MyNamespace" expose="false">


      <type name="MyNestedClass" expose="true"></type>


      <type name="MyNestedNestedClass" expose="false"></type>


  </namespace>           


</apiFilter>


Here MyNestedNestedClass will also be shown since its declaring type (MyNestedClass) is shown.


<apiFilter expose="false">


  <namespace name="MyNamespace" expose="false">


        <type name="MyNestedClass" expose="true"></type>


  </namespace>           


</apiFilter>


 


Exposing members within nested types works the same as with regular types. Using this filter only MyNestedMethod will be shown, leaving MyNestedNestedClass hidden, and all other members within MyNestedClass.


<apiFilter expose="false">


  <namespace name="MyNamespace" expose="false">


        <type name="MyNestedClass" expose="false">


              <member name="MyNestedMethod" expose="true" />           


        </type>


  </namespace>           


</apiFilter>


 


 


General Examples


The following example filters out three namespaces, and 11 types within the System namespace.


<apiFilter expose="true">


      <namespace name="System" expose="true">


        <type name="BrowsableAttribute" expose="false" />


        <type name="DefaultMemberAttribute" expose="false" />


        <type name="IntPtr" expose="false" />


        <type name="MulticastDelegate" expose="false" />


        <type name="NonScriptableAttribute" expose="false" />


        <type name="ParamArrayAttribute" expose="false" />


        <type name="RuntimeFieldHandle" expose="false" />


        <type name="RuntimeTypeHandle" expose="false" />


        <type name="UIntPtr" expose="false" />


        <type name="Void" expose="false" />


      </namespace>


      <namespace name="System.ComponentModel" expose="false" />


      <namespace name="System.Runtime.CompilerServices" expose="false" />


      <namespace name="System.Runtime.InteropServices" expose="false" />


</apiFilter>


 


Hope this helps. Cheers.


 


Anand..


 

Comments (4)

  1. SelormeyPaul says:

    @Anand: Hope this helps.

    Yes, thank you very much.

    Now, I wish you could add configuration of the IntellisenseComponent2 component 🙂

    Can we use contents of your blog for Sandcastle tools and components documentations?

    With the Sandcastle Assist project, we hope to provide configuration classes for all the built-in components and the documentations will help a lot.

    Best regards,

    Paul.

  2. Garry Trinder says:

    Hi Paul,

    Please feel free to reuse the docs from this site and also update them. Yes I will send you answers to the Intellisense component.

    Anand..

  3. cjm55 says:

    Hi

    I’m hoping I can use the filtering to only emit documentation for types and members that are marked with a certain attribute.

    For example, I might want specific documentation for [WebService], [WebMethod], [Serializable]

    In my case, I want to emit any types and members attributed with a custom attribute that is used for reflection-based interoperability between .NET and a non-CLR language.

    Could you provide an example please?

    Thanks for your great work and dedication!

Skip to main content