Visual Studio Comments Spell Checker

• Download source - 1.2 MB

Introduction

I was looking around for a spell-checker that I could use in a continuous integration process. An ideal candidate would be integrated into Sandcastle. It seems that such a spell-checker is on its way. Unfortunately, I didn’t see any recent news, and, more important, no download links. Besides, I do not need a full-blown editor. All I need is a spell-checker for Visual Studio XML comments, which can be integrated with MSBuild. I figured I can write one myself to meet my limited requirements.

Following is a tutorial on getting the Visual Studio Comments Spell Checker working. (VSCSC; that is a big name for a small tool.)

Brief Overview

VSCSC is based on NHunspell, the free spell-checker used in OpenOffice, Firefox, and Chrome. The tool does not use reflection and does not integrate into any development environment.

VSCSC consists of three projects.

VSCSC.Lib contains the SpellChecker class, which is a wrapper for the NHunspell library. VSCSC.MSBuild contains the SpellCheckerTask class, which is an MSBuild Task. VSCSC.Ui is a user interface containing a couple of buttons and textboxes to allow for a quick test of an XML file or debugging. An MSBuild project file is included to demonstrate the usage of the SpellCheckerTask.

Also included is TestLib: a library that contains a documented Circle class. XML documentation file generated for TestLib is used as input to VSCSC.

Obtaining NHunspell and Dictionaries

VSCSC download comes with precompiled release of NHunspell 0.9.6.0. Latest versions of the library are available on NHunspell homepage.
The spell-checker requires dictionaries to function. NHunspell works with OpenOffice dictionaries available on the OpenOffice website. Note that the original dictionary and affix file names contain an underscore, such as “en_US.dic”. VSCSC expects dictionaries to be named by their culture name, such as “en-US.dic” and “en-US.aff”. Rename the downloaded dictionary files, replacing the underscore with a hyphen. VSCSC download comes with English(United States) dictionary and affix files.

Visual Studio XML Comments File

To generate XML comments file for a project, open the Build tab of Project Properties and check the ‘XML Documentation file’ checkbox. XML comments file contains multiple ‘member’ elements that describe each member of a class. For example, circle class documentation looks as follows:

Spell-checker Summary

VSCSC parses the XML comments file. It searches for a predefined set of elements in each ‘member’ XML element. This set of elements is defined in CommentsSpellChecker\Lib\SpellChecker.cs as:

private List<string> _knownTags = new List<string>
{
"summary", "remarks", "param", "returns", "exception"
};

Once such element is found, its contents are parsed for text node types. Any non-text nodes are ignored. As an example, let’s take ‘summary’ element of Circle constructor from the screenshot above. It contains the following:

Initializes aa new <see cref="T:TestLib.Circle" />.

The <see cref…/> is not a text node and will not be spell-checked.

Building the project produces two DLLs and an executable. The DLLs are the VSCSC library and MSBuild Task. The executable can be used for a quick spell check or testing code changes. It reports errors as follows:

NHunspell implements the IDisposable interface, and so does the VSCSC wrapper.

Using SpellCheckerTask with MSBuild

SpellCheckerTask is an MSBuild task. It has the following properties:

• CultureName. The culture name to use. Optional. Default is “en-US”.
• DictionaryLocation. Directory that contains dictionary and affix files. Optional. Default is an empty string. Leaving DictionaryLocation empty instructs SpellCheckerTask to look for dictionaries in the parent directory of the SpellCheckerTask DLL.
• ContinueOnError. Instructs whether spelling mistakes result in build errors or warnings. Optional. Default is ‘false’, which is to fail the build when spelling errors are found.
• Documents. List of comments files to check. Required.

There are two essential steps to take in order to use the SpellCheckerTask. First, add the <UsingTask> node to the MSBuild project file to declare the task and its assembly. For example, like this:

<UsingTask TaskName="VSCSC.MSBuild.SpellCheckerTask" 
    AssemblyFile="E:\test\CommentsSpellChecker\MSBuild\bin\Debug\VSCSC.MSBuild.dll" />

Second, call the task inside a target, like this:

<SpellCheckerTask Documents="@(XmlCommentFiles)" 
 CultureName="en-US" DictionaryLocation="E:\test\Dictionaries" ContinueOnError="false" />

XmlCommentFiles above is an Item, which may include multiple files. In order to create the list of XML comments files, one may use the FindUnder Task provided in MSBuild Extension Pack. One may adopt a certain naming convention for the XML comments files and search for a specific pattern using the FindUnder task. For example, like this:

<FindUnder TaskAction="FindFiles" Path="E:\test\TestLib\TestLib\bin\Debug" 
	Recursive="true" SearchPattern="*VSCSC.xml">
<Output ItemName="XmlCommentFiles" TaskParameter="FoundItems"/>
</FindUnder> 

An example MSBuild project file, build.proj, is part of the download. Executing that file yields results similar to the following screenshot:

On a side note, it was rather challenging to get the SpellCheckerTask going. The original implementation kept failing when executed by MSBuild. It would fail in the SpellChecker constructor when trying to create an instance of Hunspell. Error message was:

“E:\test\CommentsSpellChecker\MSBuild\build.proj(22,2): error : 
Hunspell AMD 64Bit DLL not found: 
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Hunspellx64.dll”.

At first, I got confused into thinking that MSBuild is not able to resolve binary references to NHunspell DLLs. Modifying AssemblySearchPaths as described in article Resolving Binary References in MSBuild had no effect in my case. After scratching my head a little, I realized that it is not MSBuild that fails to resolve the reference; it is my SpellChecker class. The problem was in the AppDomain.BaseDirectory property. That is where assembly resolver probes for assemblies. When called from MSBuild, its value is set to the parent directory of MSBuild.exe, which is C:\Windows\Microsoft.NET\Framework64\v4.0.30319 in my case.

AppDomain.BaseDirectory is a read-only property. My first hope was inheriting from AppDomainIsolatedTask instead of a Task. That did nothing for me. I was on the brink of executing the SpellChecker in a separate AppDomain just so I could set this property using AppDomainSetup. Thankfully, Gods were kind to me, and I found a magical incantation that saved the day:

AppDomain.CurrentDomain.SetData("APPBASE",…);

Using SpellCheckerTask with Visual Studio

SpellCheckerTask can be used in Visual Studio’s AfterBuild event. Right-click the project in Solution Explorer and select ‘Unload Project’ context menu. Once unloaded, right-click the grayed-out ‘ProjectName (unavailable)’ item, and select ‘Edit ProjectName.csproj’.

As with an MSBuild project file, the Visual Studio project file needs to reference the SpellCheckerTask. It is done using the UsingTask just like before.

Locate the AfterBuild event. The event may be commented out near the end of the file. Uncomment it if necessary, and modify as needed. I suggest something similar to the following example:

<UsingTask AssemblyFile=
	"E:\test\CommentsSpellChecker\MSBuild\bin\Debug\VSCSC.MSBuild.dll" 
TaskName="VSCSC.MSBuild.SpellCheckerTask" />

<Target Name="CheckSpelling" Condition=" '$(DocumentationFile)' != '' ">

<ItemGroup> 
<XmlCommentsFile Include="$(ProjectDir)\$(DocumentationFile)" /> 
</ItemGroup> 

<SpellCheckerTask Documents="@(XmlCommentsFile)" 
DictionaryLocation="E:\test\Dictionaries" CultureName="en-US" ContinueOnError="true" /> 
</Target> 

<Target Name="AfterBuild" DependsOnTargets="CheckSpelling"> 
</Target>

This looks similar to the MSBuild project file discussed before. The differences are: an extra Target, Condition in the new CheckSpelling target, and the XmlCommentsFile item.

The condition verifies that DocumentationFile property is not empty. This property is defined when user chooses to create the XML Comments file on the Build tab of Project Properties. The condition makes sure that CheckSpelling target runs only in case there are comments to check. DocumentationFile combined with ProjectDir make up the full path to the XML comments file. This full path is assigned to the XmlCommentsFile item, which is then passed to the SpellCheckerTask. In case of MSBuild project file, we found XML comments files using the FindUnder task; in the latter case, we provide full filename instead.

Save the project file, reload the project, and rebuild it. The end result, given the example above, is as follows:

Conclusion

This tool has already found spelling mistakes in my comments. Until I find a Sandcastle-integrated tool, and I hope one appears soon, VSCSC is a decent temporary alternative.

History

• 6^th August, 2010: Initial post