MSBuild / Visual Studio aware error messages and message formats
MSBuild recognizes error messages and warnings that have been specially formatted by many command line tools that typically write to the console. For instance, take a look at the following error messages - they are all properly formatted to be MSBuild and Visual Studio friendly.
Main.cs(17,20): warning CS0168: The variable 'foo' is declared but never used
C:\dir1\foo.resx(2) : error BC30188: Declaration expected.
cl : Command line warning D4024 : unrecognized source file type 'foo.cs', object file assumed
error CS0006: Metadata file 'System.dll' could not be found.
These messages confirm to special format that is shown below, and comprise 5 parts - the order of these parts are important and should not change:
Origin (Required)
Origin can be blank. If present, the origin is usually a tool name, like 'cl' in one of the examples. But it could also be a filename, like 'Main.cs' shown in another example. If it is a filename, then it must be an absolute or a relative filename, followed by an optional paranthesized line/column information in one of the following forms:
(line) or (line-line) or (line-col) or (line,col-col) or (line,col,line,col)
Lines and columns start at 1 in a file - i.e. the beginning of a file is 1, and the leftmost column is 1. If the Origin is a tool name, then it must not change based on local - i.e. it needs to be locale neutral.
Subcategory (Optional)
Subcategory is used to classify the category itself further, and should not be localized.
Category (Required)
Category must be either 'error' or 'warning'. Case does not matter. Like origin, category must not be localized.
Code (Required)
Code identifies an application specific error code / warning code. Code must not be localized and it must not contain spaces.
Text (Optional)
User friendly text that explains the error, and *must* be localized if you cater to multiple locales.
So, how does MSBuild use Errors and Warnings emitted by external tools?
When MSBuild calls command line tools (for instance, csc.exe or vbc.exe), it looks at the output emitted by the tool to standard out / standard error streams. Any lines that match the error format that I just described will be treated specially - i.e. lines that are recognized as errors or warnings will be turned into build errors and warnings respectively.
So, what's the big deal about this anyway? (Here comes the really cool part) :)
To see the real benefit of this, you have to be building from within Visual Studio. Because MSBuild treats these messages specially, they get logged as first class warnings and errors in the Visual Studio task list. If the Origin specifies line/column information, then double clicking on the message will take you to the source of the error in the offending file.
[ Author : Faisal Mohamood ]
