Monday, February 6, 2012

Sandcastle Version Information - Part 3/3

Building the Platform Information
This is the final part of this series and we will discuss how to create the platform information using the illustrative samples from the previous article.
The platform information simply provides additional metadata to the build system, making is possible to display extra information about the API. You will see this extra information as platform icons displayed by the API, showing which API is supported by a given platform.
Note that this feature is not currently customizable, that is it applies only to MSDN defined customization. With the current MSDN release, there are two main framework groups or version frameworks; the .NET Framework and the Silverlight Framework, under these various platforms are defined as outlined below:
  • .NET Framework Group
    • .NET Framework (main platform): Not icon supported.
      Versions: 4.5, 4.0, 3.5, 3.0, 2.0, 1.1, 1.0
    • .NET Framework Client Profile: No icon supported.
      Versions: 4.0, 3.5 SP1 (Cannot tell what happened with 4.5).
    • .NET Compact Framework: Not available in newer versions of the MSDN.
      Versions: 3.0, 2.0, 1.0.
    • XNA Framework: Icons are displayed by newer MSDN, but versions are displayed only by the older MSDN.
      Versions: 3.0, 2.0, 1.0
    • Portable Class Library: No platform and version identifiers are defined by the Sandcastle.
      Version: Portable Class Library.
  • Silverlight Framework Group
    • Silverlight (main platform): No icon supported.
      Versions: 5.0, 4.0. 3.0 (earlier versions are not available in MSDN).
    • Silverlight for Windows Phone: Sandcastle does not current define version identifier for the Windows Phone OS 7.1, but could be easily added.
      Versions: Windows Phone OS 7.1, Windows OS 7.0
    • XNA Framework: The icon supported is the same was that under the .NET Framework by the Sandcastle. However, the MSDN currently displays different icon for this.
      Versions: XBox 360, Windows Phone OS 7.0
Clearly, the newer platforms (Portable Class Library, .NET Framework Client Profile etc) and versions (.NET Framework 4.5, Silverlight 5.0 etc) are not supported by the current release of the  Sandcastle. Versions identifiers (IDs) are easy to extrapolate (even though some inconsistency exists in the naming), but platform identifiers (IDs) are not.
Also, the current MSDN elevated Silverlight to its own framework group, but is not well supported by the current Sandcastle, since at the time of release, no Silverlight documentation existed in the MSDN.
These issues can be fixed if required, and we will be looking into them as part of the Sandcastle Assist release issues.

Platform Builder
The platform metadata is defined in a file specifying the platform (marked by the platform ID) under which each API in a documentation is supported.
Sandcastle is open source project developed internally by Microsoft, but the sources for some tools such as the VersionBuilder.exe are not released. The platform file format and the tool for building it are also not released.
The information we are presenting here are obtained from the study of the platform build component, transformation styles and the resource contents. We take the responsibility for any error contained in this article.

Platform File
From the study, this is the format of the platform file we came out with, it is an XML file:

<?xml version="1.0" encoding="utf-8" ?>
    <platform name="platformId" version="versionId">
        <namespace  name="api" include="boolean">            
            <type name="api" include="boolean">
                <member name="apidata/@name eg. ToString" include="boolean"/>
                <member name="apidata/@name" include="boolean">
                    @api: This is the member API. Eg: M:System.Object.ToString
                    @types: The parameter types, separated by comma
                    @name: The parameter names, separated by comma
                    <overload api="api" types="" names="" include="boolean"/>
                    <overload api="" types="" names="" include="boolean"/>

The following points are not obvious from the format as presented above:
  • Multiple Platform IDs
    You can have multiple platform IDs for a specific version. The multiple platform IDs are separated by comma (,).
  • Multiple Versions IDs
    Similar to the multiple platform IDs, you can have multiple version IDs for a particular platform. The multiple version IDs are separated by comma (,).
Except to keep it compact, using multiple platform IDs or version IDs does not make any special difference in the file format, since these are split up by the build component that consumes this file. We have not found any use of the multiple version IDs. However, for the multiple platform IDs we have, and the provided code for building the platform file handles this automatically.
The following is a partial platform file generated from the attached sample:

<?xml version="1.0" encoding="utf-8"?>
  <platform name="SilverlightPlatforms,silverlight" version="silverlight_v4">
    <namespace name="N:TestProject" include="true">
      <type name="T:TestProject.TestClass" include="true">
        <member name="ToString" include="true" />
        <member name="Equals" include="true" />
        <member name="MemberwiseClone" include="true" />
        <member name=".ctor" include="true" />
        <member name="Method1" include="true" />
        <member name="Property1" include="true" />
      <type name="T:TestProject.TestOther" include="true">
        <member name="GetHashCode" include="true" />
        <member name="GetType" include="true" />
        <member name="Finalize" include="true" />
        <member name="MemberwiseClone" include="true" />
        <member name=".ctor" include="true">
          <overload api="M:TestProject.TestOther.#ctor" types="" 
   names="" include="true" />
          <overload api="M:TestProject.TestOther.#ctor(System.String)" 
   types="System.String" names="name" include="true" />
        <member name="Method1" include="true" />
        <member name="Name" include="true" />
        <member name="Property1" include="true" />
        <member name="Value" include="true" />
  <platform name="Xbox360,xnafw" version="xnafw10">
    <namespace name="N:TestProject" include="true">
      <type name="T:TestProject.TestClass" include="true">
        <member name="MemberwiseClone" include="true" />
        <member name=".ctor" include="true" />
        <member name="Method1" include="true" />
        <member name="Property1" include="true" />
        <member name="Property11" include="true" />

Platform File Builder
In this section, we will present information on the tool used to generate the platform information file starting with the input files.

PlatformBuilder: Reflection Data Input Files
In the second part of this series we discussed the VersionBuilder tool, which uses as input the raw reflection data files and combines this to create a raw single reflection data file.
Unlike the VersionBuilder, our PlatformBuilder uses the processed reflection data files as input files. That is, after the document model is applied to the reflection data. It might be possible to use the raw reflection data, but for simplicity and our desire to minimize the memory requirements by using XmlWriter, we found the processed format more easier to consume.
Now, revisiting the version building process, the platform building process can be added in a modified diagram as shown below (the extension is shown in blue, the version builder part is removed for simplicity):

PlatformBuilder: Configuration Input File
This is really not a requirement of the code presented with this article. The code is presented in the source form as private static methods so that it can be modified and used in various forms.
For this article, we used this procedure, which we think will fit in most applications; reuse the VersionBuilder configuration file. We exposed one public static method which uses this and has this declaration:

public static bool Create(string configFile, string platformFile,
    bool isSilverlight);

  • configFile: The VersionBuilder configuration file generated in the version information processing.
  • platformFile: The output platform file.
  • isSilverlight: Specifies whether we are dealing with the Silverlight Framework Group or the .NET Framework Group. This parameter is currently not used.
This method will parse the configuration file, retrieve the raw reflection data files, change the extensions to .xml (from the .org), load the processed reflection data files and then build the platform file.

  • This method will not convert the raw reflection data files to processed reflection data files, it assumed this was done and processed files are in the same directory as the configuration file.
  • Using this procedure will limit you to creation of a single platform information file, even though this is not a requirement of the build component.
In the third sample project to demonstrate the platform information, we modified the PreBuilder.bat to add the support for transforming the raw reflection data files to the processed reflection data files.

Processing the Documentations
After creating the platform file(s), the only other requirement for platform information is to configure the build component.
The build component used here is: PlatformsComponent.
The configuration of this component is similar to the following:

<component type="Microsoft.Ddue.Tools.PlatformsComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
    <!-- The order of filter files in this config determines the order of platforms in the output. -->
    <filter files=".\PlatformFile.xml" />

Note that this build component is not added to the default Sandcastle configuration file and you must add it yourself.
This is a Pre-Transform component and the position selected is based on sample configuration files found in the Sandcastle source repository. We have not tested other pre-transform positions in the configuration file, you are invited to experiment.

We are ready for the processing, so lets consider some test configurations. Since platform icons are not supported by user/custom platform IDs, we will reconfigure the previous version information file to use the standard platform and version IDs. You do not have to worry about the VersionSharedContent.xml file since its content is useless and will not have any effect on the build process.

.NET Framework Group
For the .NET Framework Group, we will use the following version build configuration (VersionBuilder.config) to demonstrate the platform information:

    <versions name="netfw">    
        <version name="netfw35_1" file=".\" />
        <version name="netfw35" file=".\" />
    <versions name="netcfw">
        <version name="netcfw37" file=".\" />
    <versions name="xnafw">
        <version name="xnafw10" file=".\" />

NOTE: We are now using the right order; placing the latest versions first in the configuration file.

With this configuration, these are some of the images of the output:

Silverlight Framework Group

For the Silverlight Framework Group, we will use the following version build configuration to demonstrate the platform information:

    <versions name="silverlight">    
        <version name="silverlight_v4" file=".\" />
        <version name="silverlight_v3" file=".\" />
    <versions name="silverlight_mobile">
        <version name="silverlight_mobile_v1" file=".\" />
    <versions name="xnafw">
        <version name="xnafw10" file=".\" />

With this configuration, these are some of the images of the output:

NOTE: As you can observe when you compare the second images from each output, the framework members are not displayed or are filtered out in the Silverlight group. This same issue affects the user/custom platform.
The only reason we could attribute to this is; Sandcastle currently treats the Silverlight (and its related frameworks) as sub-platforms on the .NET Framework - this being the main platform. We can modify the transformation styles to resolve this issue if required.

Sample Test Applications
The test applications in this article are available for download. Use this to test the platform information.

The sample and codes are released under the Ms-PL license, which is used by the Sandcastle. You can use it anyway you like.
NOTE: This is a zip file shared from the Google Docs. If the download button is not displayed when clicked, you can download the zip file from the File menu.

This completes the information required to build a better platform and version information using the Sandcastle tools.
In the Sandcastle Assist project, we hope to make the Sandcastle tools easier to use, and as with the Sandcastle conceptual topics supports, which we documented and exposed to all, we have documented and hopefully exposed the platform/version information support to all.

We will work on the remaining issues with the platform and version information support. If you have any issue or suggestion, please leave a comment here or on the Sandcastle project forum. Thank you.