Sandcastle September 2007 Release: VersionBuilder
Sandcastle September 2007 release includes the VersionBuilder tool under \ProductionTools folder to provide support for documenting multiple versions of a project. The VersionBuilder tool generates a single reflection data file from multiple version-specific reflection files. The output reflection file can then be used in the Sandcastle build to generate reference documentation in which each API's topic contains information about the versions that support the API. For example, if you have three versions of the same DLL, with some APIs present in all three versions and other APIs present in only one or two versions, the topic for each API can include a Version Information section that lists the versions that include the API.
For Orcas RTM, the Version Information section of the documentation is as follows:
A member that’s been in all versions of .NET will say:
Supported in: 3.5, 3.0 SP1, 3.0, 2.0 SP1, 2.0, 1.1, 1.0
A member introduced in 2.0 SP1 will say:
Supported in: 3.5, 3.0 SP1, 2.0 SP1
A member introduced in 3.0 SP1 will say:
Supported in: 3.5, 3.0 SP1
To fully understand the version information, it’s important to understand how .NET 3.5 is built. Unlike versions 1.0, 1.1, and 2.0., .NET 3.5 (and 3.0) use dlls from the previous versions of .NET and adds its own as well. For example, there is no 3.5 version of mscorlib.dll. Instead, .NET 3.5 uses the same version that .NET 2.0 uses. But installing 3.5 on a computer updates the 2.0 version of mscorlib.dll. In fact, you can get the updated dll without installing 3.5; you can get the new dll by installing .NET 2.0 SP1. That means that any APIs added to mscorlib.dll after .NET 2.0 RTM are part of 2.0 SP1.
We think of Orcas as using .NET 3.5, but in reality, Orcas allows you to target .NET 2.0, 3.0, or 3.5. You’re not targeting the RTM versions of 2.0 or 3.0, though, because Orcas installs .NET 3.5, which includes the updated dlls for 2.0 and 3.0. As a result, when you target 2.0 or 3.0, intellisense shows the APIs that have been added since either version RTM’ed. But the recommendation to our customers is to only use the new APIs if you target .NET 3.5 because it’s difficult to tell whether a user has the RTM version of .NET 2.0 or .NET 2.0 SP1. Please see https://www.danielmoth.com/Blog/labels/Orcas.html and the video at https://channel9.msdn.com/Showpost.aspx?postid=333940 to understand the complexities of the Framework versions with the Orcas release.
Sequence of processing in VersionBuilder:
· Run MRefBuilder on each version's DLL set. Note that the DLL set for each version of a project includes the complete set of DLLs, not just the DLLs that are new or changed.
· Run the MergeDuplicates.xsl transform on each of the version-specific reflection files.
· Run VersionBuilder with the version-specific reflection files as input and the combined reflection file as output
· Proceed with the rest of the Sandcastle build using the combined reflection file
VersionBuilder command line:
The VersionBuilder command line has two switches.
/config:versionCatalog
versionCatalog is the path of a configuration file that specifies the reflection files for each version
/out:outputFile
outputFile is the path of the file where VersionBuilder writes the combined reflection file. If not specified, VersionBuilder writes output to the console. VersionBuilder throws an exception if the outputFile specifies a directory that does not exist.
For example:
VersionBuilder.exe /config:%projectPath%\config\versionBuilder.config /out:%projectPath%\reflection_allversions.xml
VersionBuilder configuration file:
The VersionBuilder configuration file specifies the input reflection files that MrefBuilder generated for each version. It also specifies a name for the project and names for each version. The names correspond to the ids of shared content items for the project and version names that appear in the Version Information section of an API's documentation.
Here is the content of a typical VersionBuilder configuration file:
<versions>
<versions name="ourproject">
<version name="ourproject30" file="%versionReflectionFolder%\reflection_ourproject30.xml" />
<version name="ourproject20" file="%versionReflectionFolder%\reflection_ourproject20.xml" />
<version name="ourproject10" file="%versionReflectionFolder%\reflection_ourproject10.xml" />
</versions>
</versions>
Additional shared content items for version names
In a reflection file generated by VersionBuilder, each <api> node has a <versions> child node that contains information about the versions that include the API. When the <versions> node is present, the build transforms insert a Version Information section in each API's topic to list the versions that support the API. For example:
Version Information
Our Project
Supported in: 3.0, 2.0
The project name ("Our Project") and the version number strings ("3.0" and "2.0") come from a shared content items that you must define. For example, you can create a file named ourSharedContent.xml that has the following contents:
<content xml:space="preserve">
<!-- This shared content item string is used for the heading in the Version Information section -->
<item id="ourproject">Our Project</item>
<!-- These shared content item strings are used in the Version Information section. -->
<item id="ourproject30">3.0</item>
<item id="ourproject20">2.0</item>
<item id="ourproject10">1.0</item>
</content>
Then you need to update the BuildAssembler configuration file to include a reference to the ourSharedContent.xml file.
<!-- resolve shared content -->
<component type="Microsoft.Ddue.Tools.SharedContentComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
<content file="%DXROOT%\Presentation\vs2005\content\shared_content.xml" />
<content file="%DXROOT%\Presentation\vs2005\content\reference_content.xml" />
<content file="%DXROOT%\Presentation\shared\content\syntax_content.xml" />
<content file="%DXROOT%\Presentation\vs2005\content\feedback_content.xml" />
<content file="c:\ourSharedContent.xml" />
</component>
Hope this helps. Cheers.
Anand..