Did you ever want to build Visual Studio-quality reference documentation from your XML code comments by simply referencing a NuGet package?
Well now you can!

The latest release of White Tie includes full support for generating documentation using Sandcastle. No configuration necessary. (You must install Sandcastle yourself though - see the details below).

Add a reference to White Tie's NuGet Package and then simply build your project in Release mode to generate reference documentation.

Details

If you haven't installed Sandcastle, then White Tie gracefully skips generating documentation. You must install Sandcastle yourself if you want White Tie to generate documentation for your project. Note that you may have to reboot your computer after installing Sandcastle for its changes to take effect. At the very least, you'll have to restart Visual Studio.

White Tie's only requirements are that you must install Microsoft's HTML Help v1 Compiler and Sandcastle's tools. The required steps are highlighted in the following image of the Sandcastle Guided Installer. The other options provided by the installer, such as SHFB Visual Studio Package, are not used by White Tie at all. Of course, you're free to install them anyway if you'd like.

After you've installed Sandcastle, documentation is generated automatically when you build your project in Release mode. This is configurable via MSBuild properties, as is almost everything in White Tie (see the following section for details). The result is a compiled help file (.chm) in your project's output folder (typically, bin\Release\). In addition, White Tie packs the compiled help file into the NuGet package that it generates for your project as well.

Documentation Configuration

The purpose of White Tie is to make packaging and deployment of OSS projects, or any other kind of project, really simple. White Tie uses sensible default configurations across all of its features. However, it's also highly configurable to allow for customizations.

White Tie offers many configuration options in the form of MSBuild properties and items that control if and how documentation is generated, a NuGet package is generated, static analysis is executed and output is copied to a local deployment directory.

The configuration options for generating documentation (as of White Tie v1.3.5) are as follows.
See the official documentation for details.

MSBuild Properties

• $(BuildDocumentationEnabled)
• $(DocumentationProjectName)
• $(DocumentationProductName)
• $(DocumentationCompanyName)
• $(DocumentationCopyright)
• $(DocumentationVersion)
• $(DocumentationProjectSummary)
• $(DocumentationRootTopicEnabled)
• $(DocumentationRootTopicTitle)
• $(DocumentationFeedbackEmail)
• $(DocumentationFeedbackLinkText)
• $(DocumentationHeader)
• $(DocumentationFooter)
• $(DocumentationStyle)
• $(DocumentationLanguage)

MSBuild Items

• @(DocumentationContent)
• @(DocumentationImage)
• @(DocumentationNamespace)
• @(DocumentationSource)
• @(DocumentationReference)
• @(DocumentationFrameworkReference)

Undocumented Sandcastle Configuration Properties and Items

Advanced users of Sandcastle may be wondering how to configure Sandcastle's many other options that are missing from the list above.

Well, in addition to the properties and items listed above, White Tie supports several properties and items that are specific to Sandcastle; however, I've decided to separate these options from the primary group because they aren't general enough for White Tie. In the future, White Tie may support other documentation generators, and perhaps even replace its dependency on Sandcastle entirely. As a result, if you restrict your use to only those configuration options listed above, then in the future you shouldn't have to change anything in order to take advantage of whatever new ways White Tie generates documentation for your project. For example, I can imagine Microsoft offering a very fast and light-weight Roslyn documentation generator and in the future I'd like any project depending on White Tie to switch automatically, with little to no changes necessary, by simply upgrading to a newer version of White Tie.

If you really want to use Sandcastle-specific features anyway, then here they are:

• $(_SandcastleCopyrightUrl)
• $(_SandcastleVisibleItems) - Default value is "Attributes, ExplicitInterfaceImplementations, InheritedMembers, InheritedFrameworkMembers, Protected, ProtectedInternalAsProtected"
• $(_SandcastleMissingTags) - Default value is "IncludeTargets"
• $(_SandcastleIntelliSenseOutputEnabled) - Default value is "true"
• $(_SandcastleCodeRemoveRegionMarkers) - Default value is "false"
• $(_SandcastleHelpFileFormat) - Default value is "HtmlHelp1"
• $(_SandcastleSdkLinkTarget) - Default value is "Blank"
• $(_SandcastleSyntaxFilters) - Default value is "Standard"
• $(_SandcastleHelp2SdkLinkType) - Default value is "Msdn"
• $(_SandcastleContentPlacement) - Default value is "AboveNamespaces"
• $(_SandcastleNamingMethod) - Default value is "Guid"
• $(_SandcastlePreliminary) - Default value is "False"
• $(_SandcastleBuildAssemblerVerbosity) - Default value is "OnlyWarningsAndErrors"
• $(_SandcastleNamespaceGrouping) - Default value is "True"
• $(_SandcastleMaximumGroupParts) - Default value is "2"
• $(_SandcastleCatalogName) - Default value is "VisualStudio12"
• $(_SHFBApiFilter) - Default value is "<ApiFilter />"
• @(SandcastleColorizer) - Default list is "cs;vb"
• @(SandcastleComponent) - Default list is empty; however, the Code Block Component, API Token Resolution and IntelliSense Component are included immediately before building, so you cannot remove them.
• @(_SandcastleHelpAttribute) - Default list is "DocSet;DocSet;TargetOS". The Value metadata of these items are {@HtmlHelpName}, NetFramework and Windows, respectively.
• @(_SHFBTransformArguments) - Default list is empty. You may include: logoFile, logoHeight, logoWidth, logoAltText, logoPlacement, logoAlignment, maxVersionParts and defaultLanguage. Set the Value metadata to the desired value for each item.
• @(_SandcastleContentLayoutFile) - Default list is empty.
• @(_SandcastleCodeSnippet) - Default list is empty.
• @(_SandcastleTokensFile) - Default list is empty.
• @(_SandcastleResourceItems) - Default list is empty.

In this post, I'll introduce you to my new OSS project called White Tie and I'll describe how it relates to Rxx a bit.

I'll also introduce you to a new feature of another OSS project of mine, Visual Studio Settings Switcher.  This new feature allows you to easily share VS settings files with your solution, and OSS contributors to easily take advantage of it.

White Tie and VS Settings Switcher provide a set of features that I've specifically intended to be used by OSS developers, though anyone can benefit from them really.

I know that some of the ideas in these projects are probably not new, but perhaps the way in which I've implemented those ideas as features is new enough, and simple enough, to make them better than competing projects.

Your feedback is welcome.

White Tie

I've recently created the White Tie project on CodePlex.  I like to think of it as "formal buildware for use after 6PM".

White Tie is basically just a couple of unintrusive MSBuild files that are imported by your VS projects.  It's primarily intended for OSS developers who use Visual Studio (or MSBuild) to build their projects into NuGet packages, and optionally use Code Contracts, run static analysis and like to copy all build output into a local aggregate directory.  There are also work items currently under consideration to build reference documentation via Sandcastle and to enable remote deployment scenarios, for example.

White Tie makes building, packaging and deployment easier by offering sensible, out-of-the-box configuration, though it's also highly customizable by adding particular MSBuild properties and items to your project file.  (Read the Configuration documentation for details.)

White Tie is delivered as a NuGet package, so it's really easy to integrate into your projects.  Simply build your project in Release mode and a NuGet package will be generated automatically.  No configuration is necessary for existing projects, in general, though read the note at the bottom here for details about build errors caused by missing assembly-level attributes in new projects.

One of White Tie's key features is the NuGetFlavor item group.  By adding project references as NuGetFlavor items, rather than as ProjectReference items, White Tie will automatically include the referenced projects' output into the primary project's NuGet package.

For example, let's say that you have a primary class library project called Project A, which targets the full .NET Framework 4.5.1.  If you add a NuGet reference to White Tie, then whenever Project A is built in Release mode (by default), White Tie will generate a NuGet package for Project A.  Now let's say that you also have a portable class library project called Project B, which targets a portable profile that includes Windows 8 and Windows Phone 8.  Project B is intended to be the same as Project A, only targeting different platforms.  You might refer to Project B as a "flavor" of Project A.  Now you can simply edit the project file of Project A to add a NuGetFlavor item that points to the project file of Project B.  Whenever you build Project A in Release mode, White Tie ensures that Project B is built as well, and it also includes the portable library built by Project B into the NuGet package that it builds for Project A, and in the correct target framework subfolder.

White Tie offers several more features and configuration options.  Take a look at the documentation to get started, and let me know what you think.

White Tie's Origins and Future

White Tie is something that I've been working on for a few years, in one form or another.  Much of the work began as part of the Rxx project, such as its support for NuGet, though some features even predate Rxx.

Since Rxx it has evolved into something a bit more useful, though I've only been using it internally for my own OSS projects and business-related products (under the name DaveSexton.Build).  I finally decided recently that if I was ever going to "officially" release Rxx again, I'd have to bring its build system and project configurations up-to-date first.  White Tie is basically the best of DaveSexton.Build, formalized and revised (or "reimagined", if you prefer advertising jargon) to take advantage of NuGet 2.8 features, including complete support for portable libraries.  My transition to White Tie is not yet complete, and there are currently some road blocks, but I'm committed to getting it working fully.

Note that this isn't a guarantee that I'm going to build another NuGet package for Rxx, although it's certainly a large step in the right direction.  Not only have I checked in updates to Rxx's source code to include references to White Tie already, but I've also begun to think about and make changes to the portable library configurations that Rxx will target in the future.  But even after that, I'm still going to have to comb over all of its APIs before I'll release an "official" package again.  I have OCD and I haven't reviewed its source code or work items thoroughly since Rx 2.0 was released, so my confidence level in Rxx is (unreasonably, perhaps) lower than it should be.  :)

Visual Studio Settings Switcher

I've recently released version 1.2 of the Visual Studio Settings Switcher project on CodePlex, also available in the Visual Studio Gallery.

The latest release adds a new feature that I think OSS developers really want: Solution Settings Files

If you have an OSS project, VS Settings Switcher makes it really easy to generate a Visual Studio settings file that you can check into source control along with your solution, for your OSS contributors to use.  This settings file is in the typical VS settings file format.  It's also XML, which makes it easy to edit in Visual Studio, which you should definitely do before checking it in.  I highly recommend removing all of the extraneous settings that nobody wants to be shared in OSS projects, like the positions of your VS tool windows and other environment settings.  Typically, you'll want to reduce this file to only a small subset, such as your code formatting settings for your project's programming language.

This feature is also great for those of us that contribute to OSS projects.  It makes applying an OSS project's Visual Studio settings a breeze, without any manual intervention required.  If a solution has a .vssettings file with the same name and in the same directory, then VS Settings Switcher will automatically apply its settings whenever your open that solution.  And when you close that solution or open a different solution later, your original settings are automatically restored.

Spread the word: It's a good idea now to check in a partial .vssettings file with your solution!