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

Artigo
11/30/2023

As opções a seguir controlam como o compilador relata erros e avisos. A nova sintaxe do MSBuild é mostrada em negrito. A sintaxe csc.exe mais antiga é mostrada em code style.

WarningLevel / -warn: Defina o nível de aviso.
AnalysisLevel: Defina o nível de aviso opcional.
TreatWarningsAsErrors / -warnaserror: Trate todos os avisos como erros
AvisosAsErros / -warnaserror: Trate um ou mais avisos como erros
WarningsNotAsErrors / -warnnotaserror: Trate um ou mais avisos não como erros
NoWarn / -nowarn: defina uma lista de avisos desativados.
CodeAnalysisRuleSet / -ruleset: especifique um arquivo de conjunto de regras que desabilite diagnósticos específicos.
ErrorLog / -errorlog: especifique um arquivo para registrar todos os diagnósticos do compilador e do analisador.
ReportAnalyzer / -reportanalyzer: Relate informações adicionais do analisador, como tempo de execução.

Nível de Alerta

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 exibir para a compilação: números mais baixos mostram apenas avisos de alta gravidade. Números mais altos mostram mais alertas. O valor deve ser zero ou um número inteiro positivo:

Nível de alerta	Significado
0	Desativa a emissão de todas as mensagens de aviso.
1	Exibe mensagens de aviso severas.
2	Exibe avisos de nível 1, além de certos avisos menos severos, como avisos sobre como ocultar membros da classe.
3	Exibe avisos de nível 2 mais certos avisos menos severos, como avisos sobre expressões que sempre avaliam para `true` ou `false`.
4 (padrão)	Exibe todos os avisos de nível 3, além de avisos informativos.

Aviso

A linha de comando do compilador aceita valores maiores que 4 para habilitar avisos de onda 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, pode procurar o código de erro no Índice da Ajuda. Para obter outras maneiras de obter informações sobre um erro ou aviso, consulte Erros do compilador C#. Use TreatWarningsAsErrors para tratar todos os avisos como erros. Use DisabledWarnings para desativar determinados avisos.

Nível de análise

A opção AnalysisLevel especifica ondas de aviso adicionais e analisadores para habilitar. Os avisos de onda de aviso são verificações adicionais que melhoram seu código ou garantem que ele será compatível com versões futuras. Os analisadores fornecem recursos semelhantes a fiapos para melhorar seu código.

<AnalysisLevel>preview</AnalysisLevel>

Nível de análise	Significado
5	Exibe todos os avisos opcionais da onda de aviso 5.
6	Exibe todos os avisos opcionais da onda de aviso 6.
7	Exibe todos os avisos opcionais da onda de aviso 7.
mais recente (padrão)	Exibe todos os avisos informativos até a versão atual, inclusive.
preview	Exibe todos os avisos informativos até a versão de visualização mais recente, inclusive.
nenhum	Desativa todos os avisos informativos.

Para obter mais informações sobre avisos opcionais, consulte Ondas de aviso.

TratarAvisosAsErros

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, poderá usar WarningsNotAsErrors para listar avisos que não devem ser tratados como erros.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Todas as mensagens de aviso são, em vez disso, relatadas como erros. O processo de compilação para (nenhum arquivo de saída é construído). Por padrão, TreatWarningsAsErrors não está em vigor, o que significa que os avisos não impedem a geração de um arquivo de saída. Opcionalmente, se desejar que apenas alguns avisos específicos sejam tratados como erros, você pode especificar uma lista separada por vírgulas de números de aviso para tratar como erros. O conjunto de todos os avisos de anulabilidade pode ser especificado com a abreviatura Nulo . Use WarningLevel para especificar o nível de avisos que você deseja que o compilador exiba. Use NoWarn para desativar determinados avisos.

Importante

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

AvisosAsErros e AvisosNotAsErrors

As opções WarningsAsErrors e WarningsNotAsErrors substituem a opção TreatWarningsAsErrors para obter uma lista de avisos. Esta opção pode ser usada com todos os avisos CS . O prefixo "CS" é opcional. Você pode usar o número, ou "CS" seguido pelo número de erro ou aviso. Para outros elementos que afetam os avisos, consulte 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 à anulabilidade como erros.

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

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

Desative os mesmos avisos que os erros:

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

Use WarningsAsErrors para configurar um conjunto de avisos como erros. Use WarningsNotAsErrors para configurar um conjunto de avisos que não devem ser erros quando você tiver definido todos os avisos como erros.

NãoAvisar

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

<NoWarn>warningnumber1,warningnumber2</NoWarn>

Você precisa especificar apenas a parte numérica do identificador de aviso. Por exemplo, se você quiser suprimir CS0028, você pode especificar <NoWarn>28</NoWarn>. O compilador ignora silenciosamente os números de aviso passados para NoWarn que eram válidos em 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 seguintes avisos não podem ser suprimidos pela opção NoAvisar :

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 destinam-se a ser uma indicação de um problema potencial com seu código, portanto, você deve entender os riscos de desabilitar qualquer aviso específico. Use NoWarn somente quando tiver certeza de que um aviso é um falso positivo e não pode ser um bug de tempo de execução.

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 revisar 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 #pragma aviso.
Se o seu objetivo é ver uma saída mais concisa e focada em seu log de compilação, você pode querer alterar a verbosidade do log de compilação. Para obter mais informações, consulte Como exibir, salvar e configurar arquivos de log de compilação.

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

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

CodeAnalysisRuleSet

Especifique um arquivo de conjunto de regras que configure diagnósticos específicos.

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

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

Registo de Erros

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 produza um log SARIF (Static Analysis Results Interchange Format). Os logs SARIF são normalmente lidos por ferramentas que analisam os resultados do diagnóstico do compilador e do analisador.

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

<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 a versão são: "1", "2" e "2.1". O padrão é "1". "2" e "2.1" significam SARIF versão 2.1.0.

Analisador de relatórios

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

<ReportAnalyzer>true</ReportAnalyzer>

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