Formato do MSBuild e do Visual Studio para mensagens de diagnóstico

  • Artigo

Quando uma ferramenta que gera algum texto é executada, o MSBuild examina o texto em busca de erros e avisos. Muitas ferramentas usam um formato conhecido para relatar essas mensagens. Por padrão, o MSBuild examina o texto e relata erros e/ou avisos com base na saída. Esse comportamento pode ser aumentado ou desabilitado usando estes parâmetros na tarefa: Exec: IgnoreStandardErrorWarningFormat, CustomErrorRegularExpression e CustomWarningRegularExpression.

Observação

Se você decidir usar sua própria expressão regular para detectar erros e avisos, saiba que o MSBuild examinará o resultado uma linha por vez. Mesmo que o regex personalizado corresponda a algo em várias linhas, ele não se comportará dessa maneira devido à forma como o MSBuild processa esse texto.

Dê uma olhada nas quatro mensagens a seguir. Todas estão formatadas corretamente e serão reconhecidas pelo MSBuild e pelo Microsoft Visual Studio:

Main.cs(17,20): warning CS0168: The variable 'x' is declared but never used
C:\dir1\strings.resx(2) : error BC30188: Declaration expected.
cl : Command line warning D4024 : unrecognized source file type 'file1.cs', object . . .
error CS0006: Metadata file 'System.dll' could not be found.

Essas mensagens estão em conformidade com o formato especial de cinco partes mostrado aqui. A ordem dessas partes é importante e não deve ser alterada.

Origin : Subcategory Category Code : Text

Por exemplo,

c1 : Command line warning D4024 : unrecognized source file type 'test.xyz'

Origin: c1
Subcategory: Command line
Category: warning
Code: D4024
Text: unrecognized source file type 'test.zyz'

Cada um dos componentes desse formato é descrito da seguinte maneira:

  • Origem (Obrigatório) A origem pode estar em branco. Se estiver presente, a origem geralmente será um nome de ferramenta, como cl em um dos exemplos. Mas também poderá ser um nome de arquivo, como "Main.cs", mostrado em outro exemplo. Se for um nome de arquivo, deverá ser um nome de arquivo absoluto ou relativo, seguido por uma informação opcional de linha/coluna entre parênteses em uma das seguintes formas:

    (line) or (line-line) or (line-col) or (line,col-col) or (line,col,line,col)

    Linhas e colunas começam em 1 em um arquivo; ou seja, o início de um arquivo é 1 e a coluna mais à esquerda é 1. Se a Origem for um nome de ferramenta, ele não deverá ser alterado com base na localidade; ou seja, ele precisa ser neutro em localidade.

  • Subcategoria (opcional) A subcategoria é usada para classificar ainda mais a própria categoria; ela não deve ser localizada.

  • Categoria (Obrigatório) A categoria deve ser "erro" ou "aviso". A diferenciação entre maiúsculas e minúsculas não importa. Assim como acontece com a origem, a categoria não deve ser localizada.

  • Código (Opcional) O código identifica um código de erro/código de aviso específico do aplicativo. O código não deve ser localizado e não deve conter espaços.

  • Texto Texto amigável que explica o erro e deve ser localizado se você atender a várias localidades.

Quando o MSBuild chama ferramentas de linha de comando (por exemplo, csc.exe ou vbc.exe), ele examina os fluxos de erro padrão e saída padrão emitidos pela ferramenta. As linhas que correspondem ao formato de erro que acabei de descrever serão tratadas de modo especial; ou seja, as linhas reconhecidas como erros ou avisos serão transformadas em erros de build e avisos, respectivamente. Para ver o benefício real disso, você precisa estar compilando de dentro de uma ferramenta de desenvolvimento como o Visual Studio ou o VS Code. Como o MSBuild trata essas mensagens de maneira especial, elas são registradas como avisos e erros de primeira classe na lista de tarefas do Visual Studio. Se a Origem especificar informações de linha/coluna, clicar duas vezes na mensagem levará você até a origem do erro no arquivo em questão.

Conteúdo relacionado