Opções do Compilador do C# para relatar erros e avisos

Artigo
12/15/2024

As opções a seguir controlam a maneira como o compilador relata erros e avisos.

Sintaxe do MSBuild	sintaxe csc.exe	Descrição
`WarningLevel`	`-warn`	Defina o nível de aviso. Mais informações.
`AnalysisLevel`	/	Defina o nível de aviso opcional. Mais informações.
`TreatWarningsAsErrors`	`-warnaserror`	Trate todos os avisos como erros. Mais informações.
`WarningsAsErrors`	`-warnaserror`	Trate um ou mais avisos como erros. Mais informações.
`WarningsNotAsErrors`	`-warnnotaserror`	Trate um ou mais avisos não como erros. Mais informações.
`NoWarn`	`-nowarn`	Defina uma lista de avisos desativados. Mais informações.
`CodeAnalysisRuleSet`	`-ruleset`	Especifique um arquivo de conjunto de regras que desabilita diagnósticos específicos. Mais informações.
`ErrorLog`	`-errorlog`	Especifique um arquivo para registrar todos os diagnósticos do compilador e do analisador. Mais informações.
`ReportAnalyzer`	`-reportanalyzer`	Reporte informações adicionais do analisador, como o tempo de execução. Mais informações.

Observação

Consulte Opções do compilador para obter mais informações sobre como configurar essas opções para o seu projeto.

WarningLevel

A opção WarningLevel especifica o nível de aviso a ser exibido pelo compilador.

<WarningLevel>3</WarningLevel>

O valor do elemento é o nível de aviso que você deseja que seja exibido para a compilação: números mais baixos mostram apenas avisos de gravidade alta. Números mais altos mostram mais avisos. O valor deve ser zero ou um número inteiro positivo:

Nível de aviso	Significado
0	Desativa a emissão de todas as mensagens de aviso.
1	Exibe mensagens de aviso graves.
2	Exibe os avisos do nível 1 e mais alguns avisos menos graves, como avisos sobre membros de classe ocultos.
3	Exibe os avisos do nível 2 e mais alguns avisos menos graves, como avisos sobre expressões que sempre resultam em `true` ou `false`.
4 (padrão)	Exibe todos os avisos do nível 3 e também avisos informativos.

Aviso

A linha de comando do compilador aceita valores maiores que 4, para habilitar os avisos do ciclo de aviso. No entanto, o SDK do .NET define o WarningLevel para corresponder ao AnalysisLevel no arquivo de projeto.

Para obter informações sobre um erro ou aviso, você pode procurar o código de erro no Índice da Ajuda. Para outras maneiras de se obter informações sobre um erro ou aviso, consulte Erros do compilador do C#. Use TreatWarningsAsErrors para tratar todos os avisos como erros. Use DisabledWarnings para desabilitar determinados avisos.

Nível de análise

A opção AnalysisLevel especifica ondas de aviso adicionais e analisadores a serem habilitados. Avisos de onda de aviso são verificações adicionais que melhoram seu código ou garantem que ele será compatível com as próximas versões. Os analisadores fornecem funcionalidade semelhante a lint para melhorar seu código.

<AnalysisLevel>preview</AnalysisLevel>

Nível de análise	Significado
5	Exibe todos os avisos opcionais do ciclo de aviso 5.
6	Exibe todos os avisos opcionais do ciclo de aviso 6.
7	Exibe todos os avisos opcionais do ciclo de aviso 7.
mais recente (padrão)	Exibe todos os avisos informativos até e incluindo a versão atual.
preview	Exibe todos os avisos informativos até e incluindo a versão prévia mais recente.
nenhum	Desativa todos os avisos informativos.

Para obter mais informações sobre avisos opcionais, confira Ciclos de aviso.

TreatWarningsAsErrors

A opção TreatWarningsAsErrors trata todos os avisos como erros. Você também pode usar o WarningsAsErrors para definir apenas alguns avisos como erros. Se você ativar TreatWarningsAsErrors, pode usar WarningsNotAsErrors para listar os avisos que não devem ser tratados como erros.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Todas as mensagens de aviso são relatadas como erros. O processo de compilação é interrompido (nenhum arquivo de saída é criado). Por padrão, TreatWarningsAsErrors não foi implementado, o que significa que os avisos não impedem a geração de um arquivo de saída. Opcionalmente, se você deseja que apenas avisos específicos sejam tratados como erros, você pode especificar uma lista separada por vírgulas de números de aviso para serem tratados como erros. O conjunto de todos os avisos de nulidade pode ser especificado com a abreviação Anulável. Use WarningLevel para especificar o nível de avisos que você deseja que o compilador exiba. Use NoWarn para desabilitar determinados avisos.

Importante

Há duas diferenças sutis entre usar o elemento <TreatWarningsAsErrors> no arquivo csproj e usar a opção de linha de comando do MSBuild warnaserror. TreatWarningsAsErrors: afeta apenas o compilador do C#, e não outras tarefas do MSBuild no arquivo csproj. A opção de linha de comando warnaserror afeta todas as tarefas. Em segundo lugar, o compilador não produz a saída nos avisos quando o TreatWarningsAsErrors é usado. O compilador produz a saída quando a opção de linha de comando warnaserror é usada.

WarningsAsErrors e WarningsNotAsErrors

As opções WarningsAsErrors e WarningsNotAsErrors substituem a opção TreatWarningsAsErrors para obter uma lista de avisos. Essa opção pode ser usada com todos os avisos CS. O prefixo "CS" é opcional. Você pode usar o número ou "CS" seguido do erro ou número de aviso. Para outros elementos que afetam avisos, confira as Propriedades comuns do MSBuild. Além da lista de IDs de aviso, você também pode especificar a cadeia de caracteres nullable, que trata todos os avisos relacionados à nulidade como erros.

Habilite os avisos 0219, 0168 e todos os avisos anuláveis como erros:

<WarningsAsErrors>0219,CS0168,nullable</WarningsAsErrors>

Desabilite os mesmos avisos como erros:

<WarningsNotAsErrors>0219,CS0168,nullable</WarningsNotAsErrors>

Você usará o WarningsAsErrors para configurar um conjunto de avisos como erros. Use o WarningsNotAsErrors para configurar um conjunto de avisos que não devem ser erros, ao definir todos os avisos como erros.

NoWarn

A opção NoWarn permite suprimir o compilador de exibir um ou mais avisos, onde warningnumber1, warningnumber2 são números de aviso que você deseja que o compilador suprima. Separe vários números de aviso com uma vírgula. Você pode especificar nullable para desabilitar todos os avisos relacionados à nulidade.

<NoWarn>warningnumber1,warningnumber2</NoWarn>

Você somente precisa especificar a parte numérica do identificador de aviso. Por exemplo, se quiser suprimir CS0028, você pode especificar <NoWarn>28</NoWarn>. O compilador ignora silenciosamente números de aviso passados para NoWarn que eram válidos nas versões anteriores, mas que foram removidos. Por exemplo, CS0679 era válido no compilador no Visual Studio .NET 2002, mas foi removido posteriormente.

Os avisos a seguir não podem ser suprimidos pela opção NoWarn:

Aviso do compilador (nível 1) CS2002
Aviso do compilador (nível 1) CS2023
Aviso do compilador (nível 1) CS2029

Observe que os avisos devem ser uma indicação de um possível problema com seu código, portanto, você deve entender os riscos de desabilitar qualquer aviso específico. Use o NoWarn somente quando tiver certeza de que um aviso é um falso positivo e não pode ser um bug de runtime.

Talvez você queira usar uma abordagem mais direcionada para desabilitar avisos:

A maioria dos compiladores fornece maneiras de desabilitar avisos apenas para determinadas linhas de código, para que você ainda possa examinar os avisos se eles ocorrerem em outro lugar no mesmo projeto. Para suprimir um aviso somente em uma parte específica do código em C#, use #aviso pragma.
Se sua meta for ver uma saída mais concisa e focada no log de build, talvez você queira alterar o detalhamento do log de build. Para obter mais informações, consulte Como exibir, salvar e configurar arquivos de log de build.

Para adicionar números de aviso a qualquer valor definido anteriormente para NoWarn sem substituí-lo, consulte $(NoWarn) conforme mostrado no exemplo a seguir:

   <NoWarn>$(NoWarn);newwarningnumber3;newwarningnumber4</NoWarn>

CodeAnalysisRuleSet

Especifica um arquivo de conjunto de regras que configura diagnósticos específicos.

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

Onde MyConfiguration.ruleset é o caminho para o arquivo de conjunto de regras. Para obter mais informações sobre como usar conjuntos de regras, confira o artigo na documentação do Visual Studio sobre conjuntos de regras.

ErrorLog

Especifique um arquivo para registrar todos os diagnósticos do compilador e do analisador.

<ErrorLog>compiler-diagnostics.sarif</ErrorLog>

A opção ErrorLog faz com que o compilador gere um log SARIF (Static Analysis Results Interchange Format). Os logs SARIF normalmente são lidos por ferramentas que analisam os resultados do diagnóstico do compilador e do analisador.

Você pode especificar o formato SARIF usando o argumento version para o elemento ErrorLog:

<ErrorLog>logVersion21.json,version=2.1</ErrorLog>

O separador pode ser uma vírgula (,) ou um ponto e vírgula (;). Os valores válidos para versão são: "1", "2" e "2.1". O padrão é "1". "2" e "2.1" indicam SARIF versão 2.1.0.

ReportAnalyzer

Reporte informações adicionais do analisador, como o tempo de execução.

<ReportAnalyzer>true</ReportAnalyzer>

A opção ReportAnalyzer faz com que o compilador emita informações de log do MSBuild adicionais, que detalham as características de desempenho dos analisadores na compilação. Normalmente, é usada pelos autores do analisador como parte da validação do analisador.