/analyze (Análisis de código)

Permite utilizar análisis de código y opciones de control.

Sintaxis

Opciones generales de análisis:

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

Opciones del complemento de análisis:

/analyze:plugin plugin_dll

Opciones de análisis de archivos externos:

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

Opciones de registro de análisis:

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

Opciones de formato de archivo de registro:

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

Opciones de contenido de archivo de registro:

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

Opciones del conjunto de reglas:

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

Argumentos

Opciones generales de análisis

/analyze[-]
Activa el análisis de código. Use /analyze- para desactivar explícitamente el análisis. /analyze- es el comportamiento predeterminado.

De manera predeterminada, la salida del análisis va a la consola o a la ventana Salida de Visual Studio, como otros mensajes de error. El análisis de código también crea un archivo de registro llamado filename.nativecodeanalysis.xml, donde filename es el nombre del archivo de código fuente analizado.

/analyze:only
De manera predeterminada, el compilador compila el código para generar archivos de objeto antes de ejecutar el análisis de código. La opción /analyze:only hace que el compilador omita el paso de generación de código y realice el análisis de código directamente. Los errores del compilador siguen evitando que se ejecute el análisis de código. Sin embargo, el compilador no notificará otras advertencias que podrían encontrarse durante el paso de generación de código. Si el programa tiene advertencias de generación de código, es posible que los resultados del análisis no sean confiables. Se recomienda usar esta opción solo si el código pasa las comprobaciones de sintaxis de generación de código sin errores ni advertencias.

/analyze:quiet
Desactiva la salida del análisis en la consola o en la ventana Salida de Visual Studio.

/analyze:max_paths number
El parámetro number especifica el número máximo de rutas de acceso al código que se van a analizar. El valor predeterminado del análisis es de 256 rutas de acceso. Si se utilizan valores más elevados, se realizará una comprobación más completa, pero el análisis podría llevar más tiempo.

/analyze:stacksize number
El parámetro number especifica el tamaño en bytes del marco de pila que genera la advertencia C6262. El tamaño predeterminado del marco de pila es de 16 KB.

/analyze:WX-
Indica al compilador que no trate las advertencias del análisis de código como errores incluso cuando se usa la opción /WX. Para obtener más información, consulte /WX (nivel de advertencia).

Opciones del complemento de análisis

/analyze:plugin plugin_dll
Habilita el archivo DLL del complemento de análisis de código especificado para el análisis de código.

El espacio entre /analyze:plugin y la ruta de acceso del archivo plugin_dll es opcional si la ruta de acceso no requiere comillas dobles ("). Por ejemplo, puede escribir /analyze:plugin EspxEngine.dll. Sin embargo, si la ruta de acceso está entre comillas dobles, no puede tener un espacio entre /analyze:plugin y la ruta de acceso del archivo. Por ejemplo: /analyze:plugin"c:\path\to\EspxEngine.dll".

El motor del análisis de código usa complementos para ayudar a encontrar categorías específicas de defectos. El motor del análisis de código incluye algunos complementos integrados que detectan varios defectos. Para usar otro complemento con el motor de análisis de código, especifíquelo mediante la opción /analyze:plugin.

Algunos complementos, como EspXEngine.dll, que se incluye con Visual Studio, emplean extensiones que pueden realizar análisis adicionales. Visual Studio incluye estas extensiones para EspXEngine: ConcurrencyCheck.dll, CppCoreCheck.dll, EnumIndex.dll, HResultCheck.dll y VariantClear.dll. Comprueban si hay defectos sobre problemas de simultaneidad, infracciones de CppCoreGuidelines, usos inadecuados de valores enum como índices, valores HRESULT o valores VARIANT, respectivamente.

Al compilar en la línea de comandos, puede usar la variable de entorno Esp.Extensions para especificar las extensiones de EspXEngine. Por ejemplo:

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

Use un punto y coma (;) para delimitar las extensiones, como se muestra en el ejemplo. No es necesario un punto y coma final. Puede usar una ruta de acceso de archivo absoluta para una extensión o especificar una ruta de acceso relativa desde el directorio que contiene EspXEngine.dll.

El complemento EspXEngine.dll usa ConcurrencyCheck.dll para implementar las comprobaciones de análisis de código relacionadas con la simultaneidad. Estas comprobaciones generan advertencias en el intervalo C261XX, desde C26100 hasta C26167.

Si va a compilar en una ventana del símbolo del sistema para desarrolladores, establezca primero la variable de entorno Esp.Extensions para especificar la extensión ConcurrencyCheck.dll:

set Esp.Extensions=ConcurrencyCheck.dll

A continuación, use la opción /analyze:plugin EspXEngine.dll del compilador para usar el complemento EspXEngine.

Opciones de análisis de archivos externos

A partir de la versión 16.10 de Visual Studio 2019, puede especificar reglas de análisis y un comportamiento diferentes para los encabezados externos. Use las opciones /external:I, /external:env o /external:anglebrackets para especificar directorios como directorios "externos". Los archivos que se incluyen mediante #include desde un directorio externo o sus subdirectorios se consideran encabezados externos. Para obtener más información, consulte /external (diagnóstico de encabezados externos).

El análisis de código proporciona estas opciones para controlar el análisis de archivos externos:

/analyze:external-
Omite el análisis de archivos de encabezado externos. De manera predeterminada, el análisis de código analiza los archivos de encabezado externos igual que otros archivos. Cuando se establece la opción /analyze:external-, el análisis de código omite los archivos especificados como externos, excepto las plantillas de los archivos externos. Las plantillas definidas en encabezados externos se tratan como no externas mediante la opción /external:templates-. La opción /external:Wn no afecta al análisis de código. Por ejemplo, el análisis de código analiza los archivos externos e informa de los defectos incluso cuando se especifica /external:W0.

/analyze:external:ruleset ruleset_files
El parámetro ruleset_files especifica uno o varios archivos de conjunto de reglas delimitados por punto y coma que se usarán para el análisis de los archivos externos. Para obtener información sobre los conjuntos de reglas, consulte la sección "Opciones para conjuntos de reglas".

Hay una variable de entorno (CAExcludePath) que proporciona una funcionalidad similar pero más sencilla para omitir el análisis de archivos en los directorios especificados en la variable de entorno. Si se especifica un directorio tanto la opción /external:* como en la variable de entorno CAExcludePath, se considera excluido y las opciones /analyze:external* no se aplicarán a ese directorio.

Opciones de registro de análisis

/analyze:autolog[-]
Esta marca solía ser necesaria para habilitar la creación de un archivo de registro de análisis para cada uno de los archivos de código fuente que se analizan. Ahora, los archivos de registro se crean de manera predeterminada, por lo que esta marca es principalmente redundante. Cuando se usa, cambia la extensión de registro predeterminada a *.pftlog en lugar de .xml. Use /analyze:autolog- para deshabilitar el registro en archivos.

/analyze:autolog:ext extension
Invalida la extensión predeterminada de los archivos de registro de análisis y usa extension en su lugar. Si usa la extensión .sarif, el archivo de registro usa el formato SARIF en lugar del formato XML predeterminado.

/analyze:log log_path
Especifica una ruta de acceso log_path del archivo de registro en lugar de la ruta de acceso del archivo de registro generada automáticamente. Cuando la ruta de acceso log_path tiene una barra diagonal inversa final y hace referencia a un directorio existente, el análisis de código crea todos los archivos de registro en el directorio especificado. De lo contrario, log_path especifica una ruta de acceso de archivo. Una ruta de acceso de archivo indica al compilador que combine los registros de todos los archivos de código fuente analizados en el archivo de registro especificado. Si la ruta de acceso de archivo tiene la extensión .sarif, el archivo de registro usa el formato SARIF en lugar del formato XML predeterminado. Se puede reemplazar este comportamiento mediante la opción /analyze:log:format:*.

Opciones de formato de archivo de registro

A partir de la versión 16.9 de Visual Studio 2019, puede especificar diferentes opciones de formato de registro para el análisis de código.

/analyze:log:format:xml
Fuerza el uso del formato de registro XML independientemente de la extensión de archivo usada.

/analyze:log:format:sarif
Fuerza el uso del formato de registro SARIF independientemente de la extensión de archivo usada.

Opciones de contenido de archivo de registro

A partir de la versión 16.9 de Visual Studio 2019, puede especificar diferentes opciones de contenido de registro para el análisis de código.

/analyze:sarif:analyzedfiles[-]
Agrega entradas de artefactos de archivo al archivo de registro SARIF para los archivos analizados que no emiten advertencias. Esta opción está deshabilitada de manera predeterminada. Siempre se incluyen los artefactos para el archivo de código fuente y para los archivos que emiten resultados.

/analyze:sarif:configuration[-]
Agrega entradas de configuración de reglas para determinar cómo ha invalidado el usuario la configuración de reglas predeterminada (deshabilitado de manera predeterminada).

/analyze:log:compilerwarnings
Agrega todos los defectos que encuentra el motor de análisis y todas las advertencias del compilador al archivo de registro de análisis. De manera predeterminada, las advertencias del compilador no se incluyen en el archivo de registro de análisis. Para obtener más información sobre las advertencias del compilador durante el análisis de código, consulte la opción /analyze:only.

/analyze:log:includesuppressed
Agrega las advertencias suprimidas y las advertencias sin suprimir al archivo de registro de análisis. De manera predeterminada, las advertencias suprimidas no se incluyen en el archivo de registro de análisis. Si se especifican archivos de conjunto de reglas para el análisis, las advertencias deshabilitadas por los archivos de conjunto de reglas no se incluyen en el registro incluso cuando se especifica /analyze:log:includesuppressed.

Opciones del conjunto de reglas

/analyze:projectdirectory project_directory
Especifica el directorio del proyecto actual. Si el conjunto de reglas (o un elemento que incluya) es un nombre de archivo, el compilador busca primero el archivo en el directorio project_directory especificado. Si no lo encuentra, a continuación busca en el directorio ruleset_directories especificado por /analyze:rulesetdirectory, si existe. Si el conjunto de reglas (o un elemento que incluya) es una ruta de acceso relativa, el compilador primero busca el archivo en el directorio del proyecto. Si no se encuentra el conjunto de reglas, se busca en el directorio de trabajo actual. Esta opción está disponible a partir de la versión 16.9 de Visual Studio 2019.

/analyze:rulesetdirectory ruleset_directories
Especifica una lista separada por punto y coma de rutas de acceso de búsqueda del conjunto de reglas. Si el conjunto de reglas (o un elemento que incluya) es un nombre de archivo, el compilador busca primero el archivo en el directorio project_directory especificado por /analyze:projectdirectory, si lo hay, seguido del directorio especificado por ruleset_directories. Esta opción está disponible a partir de la versión 16.9 de Visual Studio 2019.

/analyze:ruleset ruleset_files
Especifica uno o varios archivos de conjunto de reglas que se van a usar para el análisis. Esta opción puede hacer que el análisis sea más eficaz; el motor de análisis intenta excluir los comprobadores que no tienen reglas activas especificadas en los archivos de conjunto de reglas antes de ejecutarse. De lo contrario, el motor ejecuta todos los comprobadores habilitados.

Los archivos de conjunto de reglas que se incluyen con Visual Studio se encuentran en %VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets.

En el siguiente conjunto de reglas personalizado de ejemplo, se indica al motor de análisis que compruebe C6001 y C26494, y los notifique como advertencias.

Puede colocar este archivo en cualquier lugar siempre que especifique la ruta de acceso completa en el argumento o en los directorios especificados en las opciones /analyze:projectdirectory o /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>

De manera predeterminada, la extensión de archivo de los archivos de conjunto de reglas es *.ruleset. Visual Studio usa la extensión predeterminada al examinar los archivos de conjunto de reglas. Sin embargo, puede usar cualquier extensión.

Para obtener más información sobre los conjuntos de reglas, consulte Usar conjuntos de reglas para especificar las reglas C++ que se van a ejecutar.

Comentarios

Para obtener más información, consulte Introducción al análisis de código para C/C++ y Advertencias del análisis de código para C/C++.

Para establecer esta opción del compilador en el entorno de desarrollo de Visual Studio

1. Abra el cuadro de diálogo Páginas de propiedades del proyecto. Para más información, vea Establecimiento del compilador de C++ y de propiedades de compilación en Visual Studio.

2. Seleccione la página de propiedades Propiedades de configuración>Code Analysis>General.

3. Modifique una o varias de las propiedades de Code Analysis.

4. Haga clic en Aceptar o en Aplicar para guardar los cambios.

Para establecer opciones de análisis de archivos externos en la versión 16.10 y posteriores de Visual Studio 2019:

1. Abra el cuadro de diálogo Páginas de propiedades del proyecto.

2. Seleccione la página de propiedades Propiedades de configuración>C/C++>Archivos incluidos como externos.

3. Establezca las propiedades:

   • Deshabilitar el análisis de código para encabezados externos establece la opción /analyze:external-.

   • Conjunto de reglas de análisis para encabezados externos establece la opción /analyze:external:ruleset path.

4. Haga clic en Aceptar o en Aplicar para guardar los cambios.

Para establecer esta opción del compilador mediante programación

1. Vea EnablePREfast.

Consulte también

Opciones del compilador de MSVC
Sintaxis de línea de comandos del compilador de MSVC