What's the right way for a task to log errors & warnings such that they will be recognized correctly by any build system (build.exe, Visual Studio, etc.)?

Firstly, here is a document that describes the canonical error format to be used by command-line build tools, such that the errors will be recognized correctly by systems like build.exe and Visual Studio. Both build.exe and Visual Studio have logic to try and parse the initial text of the errors to grab information such as filename, line number, etc.

However, that said, tasks themselves have no need to understand what the canonical format is. This is because all that a task needs to do is to log enough information, so that the logger can format the message in the canonical format. A task must never output text to the console on its own. It must go through the logging mechanism.

For Visual Studio scenarios, regardless of which ""LogError..."" method you use in your task, the error should definitely show up in both the VS Task List as well as the VS Output Window. However, when additional information is provided (such as filename, line number, etc.), the user will be able to double-click on the task list entries as well as double-clicking on the error in the Output Window in order to automatically navigate to the correct file and line number.

For build.exe, there are unfortunately multiple versions floating around Microsoft. Some of these versions are more strict than others in terms of how the error messages must be formatted in order for it to recognize them as errors. Some of the logging methods in the ""TaskLoggingHelper"" class take enough information such that the loggers can format the error message in the canonical format that will be understood by all versions of build.exe. One such example is ""LogErrorFromText(message, errorcode, filename, line, offset)"". However, other more simple logging methods (such as ""LogError"", ""LogErrorFromException"", etc.), do not take enough information. So if you use these methods, you may have mixed results depending on which build.exe you're using.

We've provided a variety of overloads so that task authors can log as easily as possible. We didn't want to force people who didn't care about error codes and help keywords to have to log all the details all the time. Note: If you want to log the maximum possible amount of information, you can use the ""IBuildEngine.LogEvent() method"", which is available off the ""BuildEngine"" property on the base Task class.