Using Sandcastle as a documentation tool

Recently, we evaluated several documentation tools, like ndoc, doxygen etc. We found that SandCastle (together with SandCastle Help File Builder GUI app - http://shfb.codeplex.com/) is the most appropriate tool for generation of rich documentation to .NET libraries.

It can create HTML DOC 1.1, 2.0 and pure HTML output, and here is an example of our work.

http://corp-web.b2bits.com/fixanet/doc/html/

What bugs we has found
1) When we add a picture to the headers of help content files, some fonts will be smaller then it was supposed. Perhaps the tool adds additional div and corrupts styles somehow
2) Sync topics button doesnt work in FireFox (but it is OK in other browsers)

In generally, it is the best free tool for .NET, I believe, while there are also several commercial tools one may consider - a list of them can be found there http://stackoverflow.com/questions/546053/anyone-using-ndoc-or-a-similar-tool-to-help-with-system-documentation/1200561#1200561

Avoid verbose log formatting in .NET TraceListeners

The problem is:

when you use any of default TraceListeners (for example, I need ConsoleTraceListener), and when you call Trace.LogInfo , Trace.LogError or Trace.LogWarning, you wil have something like

Your application name: Information : : And here is a text of your message
Your application name: Warning : : And here is a text of your warning
....

Well, I don't need application name and I want to exactly control how the log is formatted. Setting traceOutputOptions in app.config will not change the situation, because with traceOutputOptions you can add date, timestamp or even full stack to the log, but there is no way to remove something out from there. Damn, now I understand why we have been used Log4Net for logging instead of System.Diagnostics.Trace! But in the current project I can't use Log4Net

Ok, to solve the problem I try to understand how the MS code works, when going from the point where you call LogInfo (message) to the point where it outputs to the stream.
I noticed that

When I call Trace.LogInfo(message), the following happens

1) TraceListener.Write is called with parameter like "application_name: message_type: 0 "
2) TraceListener.WriteLine is called with my message

So actually they write a log message in 2 turns, OK, sound great for me, as far as we can handle it now in the following way:

1) I created a simple class LaconicTraceListener, and the code you will find below. You need to override just one function there
2) And I added new cutom listener to the app.config file to the section.



And it works!


///

/// Class overrides one function of standard ConsoleTraceListener
/// to make output less verbose
///
public class LaconicConsoleTraceListener: System.Diagnostics.ConsoleTraceListener
{

public LaconicConsoleTraceListener(): base()
{
}

public LaconicConsoleTraceListener(bool useErrorStream)
: base(useErrorStream)
{
}

public override void Write(string message)
{
/*
A trick to avoid verbose logging.
LogInformation function works in following way -
For each call of LogInformation(Message) it actually calls:
1) Write("AssemblyName: MessageType: MessageIndent");
2) WriteLine(message)

We don't want to have an assembly name in each trace line, so we will exclude it
*/
if (!message.StartsWith(this.GetType().Assembly.GetName().Name,
StringComparison.InvariantCultureIgnoreCase))
{
base.Write(message);
}
}
}

Using SET ROWCOUNT to limit number of deleted records

I was given MS SQL database with no normalization, no primary keys in tables and lot of duplicates.
How can you delete a duplicate rows from the table, if you have 2 rows where no unique key exists, all fields are equal, so there is no way to distinguish one row from another?

In Oracle you always have row_id so 2 between 2 rows you can delete a row with max(row_id)

In MS SQL you can use SET ROWCOUNT to limit the number of deleted records.

Run the following example, and you wil get and idea.

create table t
(
id int,
name varchar(100)
)
GO

insert t values(1, 'Number One')
insert t values(2, 'Number Two')
insert t values(3, 'Number Three')
insert t values(1, 'Number One')

GO


SELECT count(*) FROM t /* will return 4 */

GO

SET ROWCOUNT 1
DELETE from t where ID = 1 /* will delete only one record from 2 records with ID = 1 */

GO

SELECT count(*) FROM t /* will return 3 */

GO