/analyze (Análise de código)

Habilita opções de análise e controle de código.

Sintaxe

Opções de análise geral:

/analyze[-]
/analyze:only
/analyze:quiet
/analyze:max_paths number
/analyze:stacksize number
/analyze:WX-

Opções de plug-in de análise:

/analyze:plugin plugin_dll

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

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

Opções de log de análise:

/analyze:autolog[-]
/analyze:autolog:ext extension
/analyze:log log_path

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:projectdirectory project_directory
/analyze:rulesetdirectory ruleset_directories
/analyze:ruleset ruleset_files

Argumentos

Opções de análise geral

/analyze[-]
Ativa a análise de código. Use /analyze- para desativar explicitamente a análise. /analyze- é o comportamento padrão.

Por padrão, a saída da análise vai para o console ou para a janela Saída do Visual Studio como outras mensagens de erro. A análise de código também cria um arquivo de log chamado filename.nativecodeanalysis.xml, onde filename é o nome do arquivo de origem analisado.

/analyze:only
Por padrão, o compilador compila o código para gerar arquivos de objeto antes da execução da análise de código. A opção /analyze:only faz com que o compilador ignore a passagem de geração de código e faça a análise de código diretamente. Os erros do compilador ainda impedem que a análise de código seja executada. No entanto, o compilador não relatará outros avisos que ele pode encontrar durante a passagem de geração de código. Se o programa não estiver livre de avisos de geração de código, os resultados da análise podem não ser confiáveis. Recomendamos que você use essa opção somente se o código passar por verificações de sintaxe de geração de código sem erros ou avisos.

/analyze:quiet
Desativa a saída da análise para o console ou a janela Saída do Visual Studio.

/analyze:max_paths number
O parâmetro number especifica o número máximo de caminhos de código a serem analisados. A análise é padrão para 256 caminhos. Valores maiores causam uma verificação mais completa, mas a análise pode demorar mais.

/analyze:stacksize number
O parâmetro number especifica o tamanho em bytes do registro de ativação que gera o aviso C6262. O tamanho do registro de ativação padrão é de 16 KB.

/analyze:WX-
Informa ao compilador para não tratar avisos de análise de código como erros mesmo quando a opção /WX é usada. Para mais informações, consulte /WX(Nível de aviso).

Opções de plug-in de análise

/analyze:plugin plugin_dll
Habilita a DLL do plug-in de análise de código definida para análise de código.

O espaço entre /analyze:plugin e o caminho do arquivo plugin_dll será opcional se o caminho não exigir aspas duplas ("). Por exemplo, você pode gravar /analyze:plugin EspxEngine.dll. No entanto, se o caminho estiver entre aspas duplas, você não poderá ter um espaço entre /analyze:plugin e o caminho do arquivo. Aqui está um exemplo: /analyze:plugin"c:\path\to\EspxEngine.dll".

O mecanismo de análise de código usa plug-ins para ajudar a encontrar categorias específicas de defeitos. O mecanismo de análise de código vem com alguns plug-ins internos que detectam vários defeitos. Para usar outro plug-in com o mecanismo de análise de código, especifique-o usando a opção /analyze:plugin.

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 log de análise

/analyze:autolog[-]
Esse sinalizador costumava ser obrigatório para habilitar a criação do arquivo de log de análise, para cada um dos arquivos de origem que estão sendo analisados. Os arquivos de log agora são criados por padrão, portanto, esse sinalizador é redundante. Quando usado, ele altera a extensão de log padrão para *.pftlog em vez de .xml. Use /analyze:autolog- para desabilitar o registro em log para arquivos.

/analyze:autolog:ext extension
Substitui a extensão padrão dos arquivos de log de análise e usa extension em vez disso. Se você usar a extensão .sarif, o arquivo de log usará o formato SARIF em vez do formato XML padrão.

/analyze:log log_path
Especifica um caminho do arquivo de log log_path em vez do caminho do arquivo de log gerado automaticamente. Quando o caminho log_path tem uma barra invertida à direita e se refere a um diretório existente, a análise de código cria todos os arquivos de log no diretório especificado. Caso contrário, log_path especifica um caminho do arquivo. Um caminho do arquivo instrui o compilador a combinar logs para todos os arquivos de origem analisados no arquivo de log especificado. Se o caminho do arquivo tiver uma extensão .sarif, o arquivo de log usa o formato SARIF em vez do formato XML padrão. É possível substituir esse comportamento usando-se a opção /analyze:log:format:*.

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.

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 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.

Comentários

Para obter mais informações, consulte Visão geral da análise de código para C/C++ e Avisos da análise de código para C/C++.

Para definir esta opção do compilador no ambiente de desenvolvimento do Visual Studio

1. Abra a caixa de diálogo Páginas de Propriedades do projeto. Para obter detalhes, confira Definir as propriedades de build e do compilador do C++ no Visual Studio.

2. Selecione a página de propriedades Propriedades da Configuração>Análise de Código>Geral.

3. Modifique uma ou mais propriedades da Análise de Código.

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

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.

Para definir essa opção do compilador via programação

1. Consulte EnablePREfast.

Confira também

Opções do compilador MSVC
Sintaxe da linha de comando do compilador MSVC