June 2006 - Posts
In a previous post, I mentioned that I miss having a working version of NDoc for Visual Studio 2005. And I still do, but that doesn't stop me from documenting my code.
I recently installed Roland Weigelt's GhostDoc. It was featured in James Avery's MSDN article "10 Must-Have Add-Ins" and I thought I'd give it a go. A quote from the GhostDoc website:
GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters.
Take for example this method:
public SqlCommand BuildInsertCommand(DataTable dataTable)
{ // Build the SqlCommand
}
When you add XML documentation using the standard method (by typing ///) you would get this:
/// <summary>
///
/// </summary>
/// <param name="dataTable"></param>
/// <returns></returns>
public SqlCommand BuildInsertCommand(DataTable dataTable)
{ // Build the SqlCommand
}
But if you have GhostDoc installed, you simply right-click anywhere inside the method and you get this:
/// <summary>
/// Builds the insert command.
/// </summary>
/// <param name="dataTable">The data table.</param>
/// <returns></returns>
public SqlCommand BuildInsertCommand(DataTable dataTable)
{ // Build the SqlCommand
}
You will see that a lot of stuff is already there. Based on the method name, it already entered a short description. All you need to do is check (and possibly improve) that descrition, explain a bit more on what the parameters are for and add stuff that you think is missing. If this method implements an existing interface, or was used to override a member of an inherited class, GhostDoc would have retrieved the documentation for that member.
The version for Visual Studio 2003 only supports C# code, but the version for Visual Studio 2005 also works on VB.Net. Although Roland still say's that VB.Net support is experimental.
Here are some more links on GhostDoc I found at Roland's website:
All I need now is a working version of NDoc 2005. A Beta is available at SourceForge, but I can't get it to work. It claims it is missing xslt files. Guess I'll have to wait for the final version.
The Enterprise library team are planning for a new version which will target .Net Framework 3.0. Tom Hollander has a post about the things they are considering for the new version and is asking for input on what we as developers would like to see. So if you use EntLib and would like to see some stuff changed, improved or added, check-out Tom Hollander's post and let them know about it.
We have all done it, I guess. Writing applications that use MAPI or CDO to access a mailbox. With the new version of Exchange, these components will no longer install automatically. To solve this problem, Microsoft have introduced a web download which contains these two components. So what, you might ask.
Well, the great thing is, that this download contains all the components you need to access a mailbox. Microsoft have NOT included the annoying check that displays the dialogbox asking you to allow access to the address book! And since it only contains the mailcomponents, and not a mail client, you can use this download to install these components on a server. For those server applications/services you developed.
Some details about this download:
- The build is 6.5.7830 (From the Exchange 2003 tree).
- The CDO included here is the one normally shipped with Exchange, meaning it does not have the security dialogs that the Outlook 2003 build of CDO has.
- The installer will NOT install MAPI and CDO on machines with either Exchange or Outlook already installed.
- This includes Outlook 2007. The CDO only download will work with Outlook 2007.
- This package is NOT redistributable. We do encourage third party products downloading the installer and running it during their installation as long as the install is not silent.
You can download the files here.
As we all know, C# (and VB.Net 2.0) give you the option of adding XML documentation tags to your code. And as professional developers, we all use this option to document the code. At a certain point, you may need to generate a help file for assemblies you wish to distribute. I myself own a library which I distribute amongst my colleagues and for the .Net 1.1 version, I used NDoc 1.3 to generate the documentation. This week, I finally found time to finish the migration of the library to .Net 2.0. I replaced the delegates I used for events for the generic version, removed objects that were obsolete due to new stuff in .Net 2.0, and cleaned up the code using FxCop 1.35. But then came the task of generating the documentation for the library before distributing the new version. And that's where I ran into trouble.
First of all, the most recent version of Ndoc (1.3), does NOT support .Net 2.0. I checked the NDoc pages on SourceForge, but only found a version from june 2005 which didn't work. Links on that page to more information about generating documentation for .Net 2.0 didn't work either. I then proceeded to google for a new version of NDoc. One of the things I found was that the original developer of NDoc is not really working on that project anymore because of health problems. I hope he well recover soon.
I also found loads of alpha's, beta's and other versions which all claim to work. Unfortunately I haven't yet been able to get any of these versions working. They all have one or more problems, or unknown dependencies, which are working against me. So if you're reading this, and have a version of NDoc which I can install and that works, please respond to this post.
I found the following threads on http://forums.microsoft.com/MSDN which pointed me to the beta's I mentioned above:
When you read those threads, you will find responses from Microsoft employees. And those responses are very interesting, as you can see from the following quote:
26 May 2006, 12:25 AM UTC
As I mentioned in the other thread our plans are to release documentation compilers for .Net 2.0 as a Community Technology Previews (CTP) version by the end of June 2006 and then RTM by the end of August 2006. I will have a detailed post about this before our CTP release next month. Cheers.
Anand. Microsoft Corporation
Group Manager, Developer Division
This is of course really interesting. Apparently, Microsoft will release a CTP version of a documentation compiler somewhere this month. Let's hope they do. All I want is a simple way to generate my documentation again. If it's a new version of NDoc, great. If it's the new Microsoft stuff, fine. I'll keep y'all posted!
Microsoft have introduced the .Net 3.0 Framework (see Erwyn's post, and others). But to keep us all informed, they also opened a community web site to keep us all informed about the all the new stuff. The new community web site features a weblog, forum and download section. Microsoft are positioning this site as a major resource for all sorts of information about .Net 3.0.
NetFx3.com is a new developer community that focuses on the four new technologies included in the Microsoft .NET Framework 3.0 (the technologies formerly known as WinFx):
On June 8 2006, MSDN Wiki (http://msdnwiki.microsoft.com) became available to a broad public audience. Now you can add your snippets, good practices, information about tools and many more to the structured hierarchy build around .NET Framework and Visual Studio 2005 MSDN documentation. On the current site you can add content and edit other people’s contributions in a wiki-like fashion around the official Microsoft-authored documents,
You all know the problem. You run FxCop on your project or solution and it keeps throwing messages at you that for some reason you want to ignore for this project. Say you're building a WinForms application and in the click event for your button, you want to catch all exceptions and display a message to the user. FxCop will show you the message "Do not catch general exception types". And the details for that message are even more specific:
You should not catch Exception or SystemException. Catching generic exception types can hide run-time problems from the library user, and can complicate debugging. You should catch only those exceptions that you can handle gracefully.
Now as a rule, I think FxCop is right. But at some point you will have to do something with these exceptions. You may want to to write them to an error log so that you can actually solve the problem that the application encountered. Or perhaps you want to display a really cool message to your user.
Until now, you had the following options to make sure these rules no longer showed when you ran FxCop:
- Right-click the message in FxCop and choose Exclude.
- Go to the Rules tab in FxCop, find the rule and clear the checkbox.
As of release 1.35, you now have another option. You can add the SuppressMessage attribute to the code and tell FxCop to ignore the message for that method or class. I think this has some advantages over the previous options.
- It is clear in the code that certain code analysis problems are ignored. You can even add comments as to why.
- The other options depend on an FxCop project where the selections are stored. If that project's gone, so is the suppression. And when a another developer runs FxCop on that code again, he or she will have to rethink if the message is valid or not.
One snag, it will only work in Visual Studio 2005. So how would you go about and use this option if you're a C# developer:
- In Solution Explorer, right-click your project and choose Properties.
- In the Properties window, choose the Build tab.
- In the Conditional compilation symbols text box, enter CODE_ANALYSIS.
- In the code where you want to suppress certain messages, add the namespace System.Diagnostics.CodeAnalysis to the using section.
- In FxCop, right-click the message you want to suppress and select Copy As -> SuppressMessage.
- In your C# code, paste the SuppressMessage attribute in your code.
Needless to say that this works with all rules FxCop will apply to your code. It works in VB.Net or C++ as well. How you would go about and do it in those languages can be found here. Visual Studio Managed Code Analysis (FxCop) blog.
Still on the subject of scanning directories 
. On my post at code project, Oleg Shilo replied with the following code which shows how you can scan directores without using recursion. Pretty smart code, although this way you don't exactly walk the directory tree, but gradually work your way down one level at a time. Couldn't resist posting it here:
VS 2005 version:
private void WalkDirectories()
{ int index = 0;
List<string> dirList = new List<string>();
List<string> fileList = new List<string>();
dirList.Add(Environment.CurrentDirectory);
while (index < dirList.Count)
{ foreach (string dir in Directory.GetDirectories(dirList[index]))
dirList.Add(dir);
foreach (string file in Directory.GetFiles(dirList[index]))
fileList.Add(file);
index++;
}
}
VS 2003 version:
private void WalkDirectories()
{ int index = 0;
ArrayList dirList = new ArrayList();
ArrayList fileList = new ArrayList();
dirList.Add(@"C:\");
while (index < dirList.Count)
{ foreach (string dir in Directory.GetDirectories(dirList[index].ToString()))
dirList.Add(dir);
foreach (string file in Directory.GetFiles(dirList[index].ToString()))
fileList.Add(file);
index++;
}
}
First of all, I haven't been in this situation before, but I'm sure it will happen at one stage.
If you need to do this soon, you might want to have a look at this document that Microsoft has just released. The document features:
- Migrating from Business Objects Crystal Reports to SQL Server 2005 Reporting Services Introduction.
- Comparing Business Objects Crystal Reports 8.5+ to SQL Server 2005 Reporting Services.
- Preparing to Convert to SQL Server 2005 Reporting Services.
- Migrating Crystal Report Sections to SQL Server 2005 Reporting Services.
- Migrating Additional Crystal Report Features to SQL Server 2005 Reporting Services.
- Using Alternative Migration Techniques.
- Useful Links for SQL Server 2005 Reporting Services.
In my previous post I explained how you could build a class that uses recursion to scan through directories. On a similar article I wrote for CodeProject.com, I was brought to the attention of a possible issue that might occur when you do this.
It is possible to create an infinitely recursive directory tree on an NTFS drive. So if you don't provide a solution for this, you will create infinite loops in your application without being aware of the problem. An article explaining this issue can be found here. It's also where I found a solution, but you can simply try the following:
- Create a directory in the root of your C: drive, for example AAA.
- Right-click My Computer and select Manage.
- Click on Disk Management.
- In Disk Management, right-click the C drive and select "Change Drive Letter and Paths...".
- From the "Change Drive Letter and Paths for C:" dialog, click "Add"
- Where it says "Mount in the following empty NTFS folder", enter "C:\AAA". Click OK.
Congratulations, you just created an infinitely recursive directory. Just open op the Windows Explorer and select the AAA directory to see what happens. To solve this, you will need to check the attributes of the directory for the ReparsePoint attribute as in the following example:
if ((subDirectory.Attributes & FileAttributes.ReparsePoint) != 0)
{ // This directory has the FileAttributes.ReparsePoint attribute set
}
This fix is obviously available in the code that you can download in my post on How to: Scan directories using recursion.
Update June 4, 2006. I closed comments on this post.