Componentization - Building Assembly level HxS using Sandcastle
The primary goal of componentization is to reduce the size of a run-time image. In addition to helping meet space requirements, componentization has the following benefits:
- Performance - Reducing disk and memory use can significantly improve performance of both the platform and your software.
- Reliability - As a general rule, reliability increases with fewer executable files running and interacting with each other, devices, and the user.
- Customization - Componentization allows for granular customization that is not possible using traditional setup programs.
Componentization using Sandcastle:
Sandcastle now allows us to build API documentation on a per-assembly basis. That is, we can build an HxS that contains documentation only for the types in a given DLL and then combine the HxS into a cohesive document set (e.g., create a unified TOC). We will be shipping "Orcas Beta 2" FxRef documentation as componentized HxS to improve our F1 performance within the VS IDE. This feature is available with Sandcastle June CTP.
How does this help with performance, reliability and customization?
When we shipped Windows SDK in November 2006 (https://blogs.msdn.com/windowssdk/archive/2006/11/08/windows-sdk-for-windows-vista-is-live.aspx) the Framework documentation was a 400 MB monolithic Hxs. This created performance and reliability issues for customer downloads and also impacted the F1 calls in VS IDE. Also customization was an issue when we wanted to ship documentation for certain assembly with VS Express SKUs.
Here are some of the issues we investigated before designing this feature in Sandcastle:
1. Size of HxS - HXS size could theoretically be a problem with an assembly-level HXS, but it won’t practically become a problem any faster than it would under our current practice (used in VS 2005 documentation) of namespace-level HXS. Our largest HXS under the current practice is for the System.Windows.Forms namespace. Those APIs pretty much represent the contents of the System.Windows.Forms.dll assembly, so under the new practice the largest HXS would remain about the same. Sandcastle provides infrastructure which will make it easy to build assembly-level HXS.
2. FX Issues - Building documentation for the APIs in an assembly does require information from other assemblies, not just for inheritance hierarchies, but also for parameter and return types, interface implementations, etc. In order to deal with this requirement, Sandcastle expects to have reflection data files for such other assemblies available while it is building documentation for one assembly.
3. Distributed build ownership – If you are a big corporation (like Microsoft) with different build teams then individual teams can maintain the ownership of building their assembly.
Here is an overview of assembly level build process using Sandcastle. We use MRefBuilder on each assembly to generate reflection data file. SegregateByAssembly generates reflection information for each assembly and BuildAssembler creats documentation (HxS) from the reflection data files. We use AggregateByNamespace utility, which creates a namespace reflection data files from a collection of assembly reflection data files. See a conceptual sketch below that describes this process:
Attached is a componentized builds sample for Sandcastle users. The steps below provide information on using this feature. Please install Sandcastle June CTP before trying the following:
1. Copy the attached file to “c:\program files\sandcastle\examples”;
2. Unzip it to folder “C:\Program Files\Sandcastle\Examples\componentized”;
3. Run “msbuild comp_build.proj”.
4. When done, assembly level Hxs files can be found under output\hxs and its subfolders.
5. You can copy your dlls to “C:\Program Files\Sandcastle\Examples\componentized\dll” and comments files to “C:\Program Files\Sandcastle\Examples\componentized\comments”.
6. The properties in comp_build.proj can be modified per you needs.
< PropertyGroup >
< Name > Sample</Name>
< PresentationStyle > vs2005</PresentationStyle>
< Framework > $(WINDIR)\Microsoft.NET\Framework\v2.0.50727</Framework>
< BuildDir > $(DxRoot)\examples\componentized</BuildDir>
< OutputDir > $(BuildDir)\Output</OutputDir>
< ProductionTools > $(DxRoot)\ProductionTools</ProductionTools>
< ProductionTransforms > $(DxRoot)\ProductionTransforms</ProductionTransforms>
< Presentation > $(DxRoot)\Presentation\$(PresentationStyle)</Presentation>
< Dlls > $(BuildDir)\dll\*.dll</Dlls>
< Comments > $(BuildDir)\comments\*.xml</Comments>
</ PropertyGroup >
Let me know your feedback and I hope you like this feature. Cheers.
Anand..