September 2007 Sandcastle release: Generating Framework Reflection data for resolving links

  • Article

 

Sandcastle September 2007 release was shipped without the Framework reflection data. This allowed us to reduce the Sandcastle installer size to 1.5 MB. In our previous releases we shipped the reflection files under the \Data\Reflection folder. For the September release we expect the users to generate this information.

Why do we need this reflection data?

The reflection files are used to resolve any reference links to the Framework. Please see https://www.dnrtv.com/default.aspx?showNum=84 for additional details.

Why did we leave the reflection files from our Install?

We could have generated the reflection files and shipped it with our installer. In our previous releases we shipped the reflection files for Framework 2.0 under Data\Reflection folder. However the reflection files we shipped were specific to a document model.

VS2005 and Hana presentation styles follow a document model (ApplyVSDocModel.xsl) and Prototype style follows another document model (ApplyPrototypeDocModel.xsl). We shipped the reflection files with VS2005 document model and users using Prototype style ended up using it. With Orcas RTM the users targeting 3.5 will need access to various versions of Framework reflection files. 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.

With Framework versions 2.0, 2.0 SP1, 3.0 and 3.5 things are getting complicated and it became very clear to us that shipping all the reflection files for all the document models will increase the Sandcastle installer size by 20 plus MB.

How do the users generate reflection data?

If you are using VS2005 or Hana presentation styles do the following:

1. Run MrefBuilder on all the Framework dlls

2. Apply the ApplyVSDocModel transforms.

If you are using Prototype presentation style do the following:

1. Run MrefBuilder on all the Framework dlls

2. Apply the ApplyPrototypeDocModel transforms.

Alternatively you can generate them by executing one of the the following under /Example/Sandcastle directory:

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=VS2005

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=hana

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=prototype

Note: If you are have 3.0 or 3.5 installed please change the NetFxVer accordingly.

Generating Reflection data as a part of test project:

We have shipped a sample command line batch script and msBuild project with the /Example/Sandcastle directory. Users can run the following to build the test project CHM or HxS and also to generate the reflection data information.

1. Using the command line option for the batch file under Examples/Sandcastle folder to build VS2005 or Hana or Prototype style CHM or HxS file

1. Build_sandcatle.bat vs2005 test

2. Build_sandcatle.bat prototype test

3. Build_sandcatle.bat hana test

Note: The reflection files should be generated for the first time only. Please comment the following section in the Build_Sandcastle.bat files after generating them for the first time.

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=%1

2. Using msbuild to generate build for VS2005 or Hana or Prototype, CHM or HxS file

1. Msbuild build.proj /property:PresentationStyle=vs2005

2. Msbuild build.proj /property:PresentationStyle=hana

3. Msbuild build.proj /property:PresentationStyle=prototype

Note: The reflection files should be generated for the first time only. Please comment the following section in the build.proj files after generating them for the first time.

<Exec Command="$(Framework)\msbuild fxReflection.proj /property:PresentationStyle=$(PresentationStyle)" />

Hope this helps. Cheers.

Anand..