/analyze (Análise de código)

Opções de análise de arquivo externo:

/analyze:external-
/analyze:external:ruleset ruleset_files

Opções de formato de arquivo de log:

/analyze:log:format:sarif
/analyze:log:format:xml

Opções de conteúdo de arquivo de log:

/analyze:sarif:analyzedfiles[-]
/analyze:sarif:configuration[-]
/analyze:log:compilerwarnings
/analyze:log:includesuppressed

Opções do conjunto de regras:

/analyze:rulesetruleset_file

Opções do conjunto de regras:

/analyze:projectdirectory project_directory
/analyze:rulesetdirectory ruleset_directories
/analyze:ruleset ruleset_files

O plug-in LocalEspC.dll implementa as verificações de análise relacionadas à simultaneidade. Essas verificações geram avisos no intervalo C261XX, como C26100 até C26167.

Para carregar LocalEspC.dll, use a opção /analyze:plugin LocalEspC.dll do compilador.

Alguns plug-ins, como EspXEngine.dll, que são fornecidos com o Visual Studio, empregam extensões que podem fazer análises adicionais. O Visual Studio inclui essas extensões para EspXEngine:ConcurrencyCheck.dll, CppCoreCheck.dll, EnumIndex.dll, HResultCheck.dll e VariantClear.dll. Elas verificam se há defeitos para problemas de simultaneidade, violações de CppCoreGuidelines, uso inadequado de valores enum como índices, valores HRESULT ou valores VARIANT, respectivamente.

Ao compilar na linha de comando, é possível usar a variável de ambiente Esp.Extensions para especificar extensões EspXEngine. Por exemplo:

set Esp.Extensions=ConcurrencyCheck.dll;CppCoreCheck.dll;

Use um ponto e vírgula (;) para delimitar as extensões, conforme mostrado no exemplo. Um ponto e vírgula à direita não é necessário. Use um caminho de arquivo absoluto para uma extensão ou especifique um caminho relativo do diretório que contém EspXEngine.dll.

O plug-in EspXEngine.dll usa ConcurrencyCheck.dll para implementar verificações de análise de código relacionadas à simultaneidade. Essas verificações geram avisos no intervalo C261XX, como C26100 até C26167.

Se estiver compilando em uma janela do prompt de comando do desenvolvedor, primeiro defina a variável de ambiente Esp.Extensions para especificar a extensão ConcurrencyCheck.dll:

set Esp.Extensions=ConcurrencyCheck.dll

Em seguida, use a opção do compilador /analyze:plugin EspXEngine.dll para usar o plug-in de EspXEngine.

Opções de análise de arquivo externas

A partir do Visual Studio 2019 versão 16.10, é possível especificar regras de análise e comportamento diferentes para cabeçalhos externos. Use as opções /external:I, /external:env ou /external:anglebrackets para especificar diretórios como diretórios "externos". Todos os arquivos incluídos usando #include de um diretório externo ou de seus subdiretórios são considerados cabeçalhos externos. Para obter mais informações, consulte /external (Diagnóstico de cabeçalhos externos).

A análise de código fornece estas opções para controlar a análise de arquivos externos:

/analyze:external-
Ignora a análise de arquivos de cabeçalho externos. Por padrão, a análise de código analisa arquivos de cabeçalho externos, assim como outros arquivos. Quando a opção /analyze:external- é definida, a análise de código ignora todos os arquivos especificados como externos, exceto modelos de arquivos externos. Os modelos definidos em cabeçalhos externos são tratados como não externos usando a opção /external:templates-. A opção /external:Wn não afeta a análise de código. Por exemplo, a análise de código analisa arquivos externos e relata defeitos mesmo quando /external:W0 for especificado.

/analyze:external:ruleset ruleset_files
O parâmetro ruleset_files especifica um ou mais arquivos de conjunto de regras delimitados por ponto e vírgula a serem usados na análise de arquivos externos. Para obter informações sobre conjuntos de regras, consulte a seção "Opções para conjuntos de regras".

Há uma variável de ambiente (CAExcludePath) que fornece uma funcionalidade semelhante porém mais simples para ignorar a análise de arquivos nos diretórios especificados na variável de ambiente. Se um diretório for especificado na opção /external:* e na variável de ambiente CAExcludePath, ele será considerado como excluído e as opções /analyze:external* não se aplicarão a esse diretório.

Opções de formato de arquivo de log

A partir do Visual Studio 2019 versão 16.9, você pode especificar diferentes opções de formato de log para análise de código.

/analyze:log:format:xml
Força o uso do formato de log XML independentemente da extensão de arquivo usada.

/analyze:log:format:sarif
Força o uso do formato de log SARIF independentemente da extensão de arquivo usada.

Opções de conteúdo de arquivo de log

A partir do Visual Studio 2019 versão 16.9, você pode especificar diferentes opções de conteúdo de log para análise de código.

/analyze:sarif:analyzedfiles[-]
Adiciona entradas de artefatos de arquivo ao arquivo de log SARIF para arquivos analisados que não emitem avisos. Essa opção está desabilitada por padrão. Artefatos para o arquivo de origem e para arquivos que emitiram resultados são sempre incluídos.

/analyze:sarif:configuration[-]
Adiciona entradas de configuração de regra para determinar como o usuário substituiu a configuração de regra padrão (desabilitada por padrão).

/analyze:log:compilerwarnings
Adiciona todos os defeitos encontrados pelo mecanismo de análise e todos os avisos do compilador ao arquivo de log de análise. Por padrão, os avisos do compilador não são incluídos no arquivo de log de análise. Para obter mais informações sobre avisos do compilador durante a análise de código, consulte a opção /analyze:only.

/analyze:log:includesuppressed
Adiciona avisos compactados e avisos não compactados ao arquivo de log de análise. Por padrão, os avisos suprimidos não são incluídos no arquivo de log de análise. Se os arquivos de conjunto de regras forem especificados para análise, os avisos desabilitados pelos arquivos do conjunto de regras não serão incluídos no log mesmo quando /analyze:log:includesuppressed for especificado.

Opções do conjunto de regras

/analyze:projectdirectory project_directory
Especifica o diretório atual do projeto. Se o conjunto de regras (ou um item que ele inclui) for um nome de arquivo, o compilador primeiro procurará o arquivo no project_directory especificado. Se não for encontrado, ele pesquisará o ruleset_directories especificado por /analyze:rulesetdirectory, se houver. Se o conjunto de regras (ou um item que ele inclui) for um caminho relativo, o compilador primeiro procurará o arquivo no diretório do projeto. Se o conjunto de regras não for encontrado, ele será pesquisado no diretório de trabalho atual. A opção está disponível a partir do Visual Studio 2019 versão 16.9.

/analyze:rulesetdirectory ruleset_directories
Especifica uma lista separada por ponto-e-vírgula dos caminhos de pesquisa do conjunto de regras. Se o conjunto de regras (ou um item que ele inclui) for um nome de arquivo, então o compilador primeiro procurará o arquivo no project_directory especificado por /analyze:projectdirectory, se houver, seguido pelo ruleset_directories especificado. A opção está disponível a partir do Visual Studio 2019 versão 16.9.

/analyze:ruleset ruleset_files
Especifica um ou mais arquivos de conjunto de regras a serem usados para análise. Essa opção pode tornar a análise mais eficiente. O mecanismo de análise tenta excluir os verificadores que não têm regras ativas especificadas nos arquivos do conjunto de regras antes de serem executados. Caso contrário, o mecanismo executa todos os verificadores habilitados.

/analyze:ruleset ruleset_file
Especifica um arquivo de conjunto de regras a ser usado para análise. Essa opção pode tornar a análise mais eficiente. O mecanismo de análise tenta excluir os verificadores que não têm regras ativas especificadas no arquivo do conjunto de regras antes de serem executados. Caso contrário, o mecanismo executa todos os verificadores habilitados.

Os arquivos de conjunto de regras que são enviados com o Visual Studio são encontrados em %VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets.

O conjunto de regras personalizado de exemplo a seguir informa ao mecanismo de análise para verificar C6001 e C26494, e denunciá-los como avisos.

É possível colocar esse arquivo em qualquer lugar, desde que especifique o caminho completo no argumento.

É possível colocar esse arquivo em qualquer lugar, desde que especifique o caminho completo no argumento ou nos diretórios especificados nas opções /analyze:projectdirectory ou /analyze:rulesetdirectory.

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description="New rules to apply." ToolsVersion="15.0">
  <Rules AnalyzerId="Microsoft.Analyzers.NativeCodeAnalysis" RuleNamespace="Microsoft.Rules.Native">
    <Rule Id="C6001" Action="Warning" />
    <Rule Id="C26494" Action="Warning" />
  </Rules>
</RuleSet>

Por padrão, a extensão de arquivo para os arquivos de conjunto de regras é *.ruleset. O Visual Studio usa a extensão padrão para procurar arquivos de conjunto de regras. No entanto, você pode usar qualquer extensão.

Para obter mais informações sobre conjuntos de regras, consulte Usar conjuntos de regras para especificar as regras C++ a serem executadas.

Para configurar opções de análise de arquivos externos no Visual Studio 2019 versão 16.10 e posterior:

1. Abra a caixa de diálogo Páginas de Propriedades do projeto.

2. Selecione a página de propriedades Propriedades da Configuração>C/C++>Inclui Externo.

3. Defina as propriedades:

   • Desabilitar a Análise de Código para Cabeçalhos Externos define a opção /analyze:external-.

   • O Conjunto de Regras de Análise para Cabeçalhos Externos define a opção /analyze:external:ruleset path.

4. Escolha OK ou Aplicar para salvar as alterações.