Using Sandcastle to Generate Documentation

Sandcastle is Microsoft's documentation compiler. It uses reflection of source assemblies and integrates the XML comments placed in the code by the developer to generate comprehensive MSDN-like documentation. Actually, it is used internally by Microsoft to build the .Net Framework documentation.

The problem with Sandcastle's current version (October CTP) is that it's not very user friendly, since it does not include a graphical interface and the developer has to go through several steps to generate the documentation for his projects. Fortunately, the developer community has released a few helpful tools that do most of the work for you.

Here's how I do it…

Pre-Requisites

To use Sandcastle you only need two things (and probably, you already have them):

  • .Net Framework 2.0 (Download it here)
  • HTML Help Workshop (Download it here)

Of course, you need the latest release of Sandcastle (Download the October CTP here).

Graphical Interface

Download the latest version of Sandcastle Help File Builder (from here) and install it.

Generating the Documentation

After you installed all the pre-requisites, Sandcastle and the Help File Builder, you can start generating your documentation.

The only thing you must do is make sure that you build your assemblies with the XML documentation option. In Visual Studio 2005, follow these steps:

  • Go to the properties page of you project
  • Select the Build tab
  • Check the XML documentation file option, in the Output section
  • Define an output path and file name for the documentation file (or leave it with the default value)
  • Compile your project

With this option, the compiler will build your assembly and output an XML file with all the developer comments. You can now use the Sandcastle Help File Builder and load the assemblies and their respective XML documentation files, and produce MSDN-like documentation as chm files.

SharePoint Tip #18: Reading from and Writing to a User or Group column

Each field type has a different way to be read from and written to. The most used ones (single line of text, multiple lines of text, number, currency, date and time and yes/no) are easy to use because SharePoint's object model makes it very simple to set its value:

item["MyTextField"] = "My Text Value";

However, some of the field types store more than one value and, for that reason, must be handled differently. That is the case with the Person or Group field type (SPFieldUser class) which stores two values: the User ID and the User Login Name. The User ID is and integer number that SharePoint associates with each user (kind of like the ID that is generated for each item of a list), and User Login Name is something like Domain\UserName.

Since you must set both these values in a single column, SharePoint's API includes a special class, SPFieldUserValue, which allows you to do so. The following example shows how it's used:

SPWeb web = SPContext.Current.Web;
int userId = web.CurrentUser.ID;
String username = web.CurrentUser.LoginName;

item["MyUserField"] = new SPFieldUserValue(web, userId, username);

If you try to read the value of such a field, you will get something like 4;#MyDomain\AndreVala in which 4 is the User ID and MyDomain\AndreVala is the user's Login Name.