Referencia de la línea de comandos de MSBuild

Artículo
06/13/2024

Si usa MSBuild.exe para compilar un archivo de proyecto o solución, puede incluir varios modificadores para especificar distintos aspectos del proceso.

Cada modificador está disponible en dos formas: -switch y /switch. En la documentación solo se muestra el formato -switch. Los modificadores no distinguen mayúsculas de minúsculas. Si ejecuta MSBuild desde un shell que no sea el símbolo del sistema de Windows, podría ser necesario usar comillas simples o dobles en las listas de argumentos para un modificador (separados por signos de punto y coma o comas) con el fin de garantizar que las listas se pasen a MSBuild en lugar de que las interprete el shell.

Los comandos de la CLI de .NET dotnet build, dotnet publish, dotnet msbuild y los comandos relacionados pasan estos modificadores a MSBuild, por lo que esta referencia es aplicable cuando se usan esos comandos; sin embargo dotnet run , no.

Sintaxis

MSBuild.exe [Switches] [ProjectFile]

Argumentos

Argument	Descripción
`ProjectFile`	Crea los destinos en el archivo de proyecto especificado. Si no se especifica un archivo de proyecto, MSBuild busca en el directorio de trabajo actual una extensión de nombre de archivo que termine en proj y usa ese archivo. También puede especificar un archivo de solución de Visual Studio para este argumento.

Modificadores

La primera columna de la tabla siguiente muestra una forma larga y corta de cada modificador. Ambas formas son equivalentes.

Los corchetes indican partes opcionales y llaves indican valores proporcionados [] {}por el usuario.

Switch	Descripción
`-detailedSummary[:{True or False}]` `-ds[:{True or False}]`	Si es `True`, muestra información detallada al final del registro de compilación sobre las configuraciones que se compilaron y cómo se programaron en los nodos.
`-getItem:{itemName,...}`	Escriba el valor del elemento o elementos después de la evaluación, sin ejecutar la compilación, o si se usa la opción `-targets` o la opción `-getTargetResult`, escriba los valores después de la compilación.
`-getProperty:{propertyName,...}`	Escriba el valor de la propiedad o propiedades después de la evaluación, sin ejecutar la compilación, o si se usa la opción `-targets` o la opción `-getTargetResult`, escriba los valores después de la compilación.
`-getTargetResult:{targetName,...}`	Escriba los valores de salida de los destinos especificados.
`-graphBuild[:{True or False}]` `-graph[:{True or False}]`	Hace que MSBuild construya y compile un gráfico de proyecto. La construcción de un gráfico implica la identificación de las referencias de proyecto para formar las dependencias. La compilación del gráfico implica el intento de compilar referencias de proyecto antes que los proyectos que hacen referencia a ellas, lo que supone una diferencia con respecto a la programación tradicional de MSBuild. Requiere MSBuild 16 o una versión posterior.
`-help` `/?` o `-h`	Muestra información de uso. El comando siguiente muestra un ejemplo: `msbuild.exe -?`
`-ignoreProjectExtensions: {extensions}` `-ignore: {extensions}`	Omite las extensiones especificadas al determinar qué archivo de proyecto se va a compilar. Use un punto y coma o una coma para separar varias extensiones, como se muestra en el ejemplo siguiente: `-ignoreprojectextensions:.vcproj,.sln`
`-inputResultsCaches[:{cacheFile; ...}]` `-irc[:{cacheFile; ...}]`	Lista de archivos de caché de entrada separados por punto y coma de los que MSBuild leerá los resultados de la compilación. Si `-isolateProjects` se establece en `False`, esto se establece en `True`.
`-interactive[:{True or False}]`	Indica que las acciones en la compilación pueden interactuar con el usuario. No use este argumento en un escenario automatizado donde no se espera interactividad. Especificar `-interactive` es lo mismo que especificar `-interactive:true`. Use el parámetro para invalidar un valor que proceda de un archivo de respuesta.
`-isolateProjects[:{True, MessageUponIsolationViolation, False}]` `-isolate[:{True, MessageUponIsolationViolation, False}]`	Hace que MSBuild compile cada proyecto de forma aislada. Cuando se establece en `MessageUponIsolationViolation` (o su forma abreviada `Message`), solo se serializan los resultados de los destinos de nivel superior si se proporciona el modificador `-outputResultsCache`. Esta opción consiste en mitigar las posibilidades de que un destino de infracción de aislamiento en un proyecto de dependencia use un estado incorrecto debido a su dependencia en un destino almacenado en caché cuyos efectos secundarios no se tendrán en cuenta. (Por ejemplo, la definición de una propiedad). Este modo es más restrictivo, ya que requiere que el gráfico del proyecto se pueda detectar estáticamente en el momento de la evaluación, pero puede mejorar la programación y reducir la sobrecarga de memoria al crear un gran conjunto de proyectos.
`-lowPriority[:{True or False}]` `-low[:{True or False}]`	Hace que MSBuild se ejecute con prioridad de proceso baja. Especificar `-lowPriority` es lo mismo que especificar `-lowPriority:True`.
`-maxCpuCount[:{number}]` `-m[:{number}]`	Especifica el número máximo de procesos simultáneos que se pueden usar al compilar. Si no incluye este modificador, el valor predeterminado es 1. Si incluye este modificador sin especificar un valor, MSBuild usa hasta el número de procesadores del equipo. Para obtener más información, vea Compilar varios proyectos en paralelo. En el ejemplo siguiente se indica a MSBuild que efectúe la compilación usando tres procesos de MSBuild, lo que permite compilar tres proyectos al mismo tiempo: `msbuild myproject.proj -maxcpucount:3`
`-noAutoResponse` `-noautorsp`	No incluya ningún archivo MSBuild.rsp ni Directory.Build.rsp automáticamente.
`-nodeReuse:{value}` `-nr:{value}`	Habilite o deshabilite la reutilización de nodos de MSBuild. Puede especificar los siguientes valores: - True. Los nodos permanecen al finalizar la compilación de modo que las compilaciones subsiguientes puedan usarlos (valor predeterminado). - False. Los nodos no se conservan después finalizar la compilación. Un nodo corresponde a un proyecto que se está ejecutando. Si incluye el `-maxcpucount` modificador, varios nodos se pueden ejecutar simultáneamente.
`-nologo`	No muestra la pancarta de inicio ni el mensaje de copyright.
`-preprocess[:{filepath}]` `-pp[:{filepath}]`	Crea un solo archivo de proyecto agregado alineando todos los archivos que se importarían durante una compilación, con sus límites marcados. Puede usar este modificador para determinar con mayor facilidad qué archivos se van a importar, desde dónde y cuáles contribuirán a la compilación. Si se usa este modificador, el proyecto no se compila. Si especifica el parámetro `filepath`, el archivo de proyecto agregado se genera en el archivo. En caso contrario, los resultados aparecen en la ventana de la consola. Para obtener información sobre cómo usar el elemento `Import` para insertar un archivo de proyecto en otro, vea Elemento Import (MSBuild) y Cómo: Usar el mismo destino en varios archivos de proyecto.
`-outputResultsCache[:{cacheFile}]` `-orc[:{cacheFile}]`	Archivo de caché de salida donde MSBuild escribe el contenido de sus memorias caché de resultados de compilación al final de la compilación. Si `-isolateProjects` se establece en `False`, esto se establece en `True`.
`profileEvaluation:{file}`	Genera un perfil de la evaluación de MSBuild y escribe el resultado en el archivo especificado. Si la extensión del archivo especificado es ".md", el resultado se generará con el formato Markdown. De lo contrario, se generará un archivo de valores separados por tabulaciones.
`-property:{name}={value}` `-p:{name}={value}`	Establece o invalida las propiedades en el nivel de proyecto especificadas, donde `name` es el nombre de la propiedad y `value` es el valor de propiedad. Especifique cada propiedad por separado, o use un punto y coma o una coma para separar varias propiedades, como se muestra en el ejemplo siguiente: `-property:WarningLevel=2;OutDir=bin\Debug` Consulte Propiedades comunes del proyecto de MSBuild para obtener una lista de las propiedades más usadas. El conjunto completo de propiedades disponibles depende del tipo de proyecto, el SDK y los archivos importados.
`-restore` `-r`	Ejecuta el destino `Restore` antes de compilar los destinos reales.
`-restoreProperty:{name}={value}` `-rp:{name}={value}`	Establezca o invalide estas propiedades de nivel de proyecto solo durante la restauración y no use las propiedades especificadas con el `-property` argumento . `name` es el nombre de la propiedad y `value` es el valor de la propiedad. Utilice un punto y coma para separar varias propiedades o especifique cada propiedad por separado.
`-target:{targets}` `-t:{targets}`	Compila los destinos especificados en el proyecto. Especifique cada destino por separado, o use un punto y coma o una coma para separar varios destinos, como se muestra en el ejemplo siguiente: `-target:PrepareResources;Compile` Si especifica destinos mediante este modificador, se ejecutan en lugar de destinos en el `DefaultTargets` atributo del archivo del proyecto. Para obtener más información, vea Orden de compilación de destinos y Cómo: Especificar qué destino usar primero al compilar. Un destino es un grupo de tareas. Para obtener más información, consulte Destinos.
`-targets[:{file}]` `-ts[:{file}]`	Escriba la lista de destinos disponibles en el archivo especificado (o el dispositivo de salida, si no se especifica ningún archivo), sin ejecutar realmente el proceso de compilación.
`-toolsVersion:{version}` `-tv:{version}`	Especifica un conjunto de herramientas personalizado. Un conjunto de herramientas consta de tareas, destinos y herramientas que se utilizan para compilar una aplicación. Vea Conjunto de herramientas (ToolsVersion) y Configuraciones de conjuntos de herramientas estándar y personalizados.
`-validate:[{schema}]` `-val[{schema}]`	Valida el archivo de proyecto y, si la validación es correcta, lo compila. Si no especifica `schema`, el proyecto se valida con el esquema predeterminado. Si especifica `schema`, el proyecto se valida con el esquema especificado. El valor siguiente muestra un ejemplo: `-validate:MyExtendedBuildSchema.xsd`
`-verbosity:{level}` `-v:{level}`	Especifica la cantidad de información que se va a mostrar en el registro de compilación. Cada registrador muestra eventos en función del nivel de detalle establecido para él. Puede especificar los niveles de detalle `q[uiet]`, `m[inimal]`, `n[ormal]` (predeterminado), `d[etailed]` y `diag[nostic]`. El valor siguiente muestra un ejemplo: `-verbosity:quiet`
`-version` `-ver`	Muestra solo la información de versión. El proyecto no se compila.
`@{file}`	Inserta los modificadores de línea de comando de un archivo de texto. Si tiene varios archivos, deberá especificarlos por separado. Para obtener más información, vea Archivos de respuesta.
`-warnAsError[:{code; ...}]` `-err[:{code; ...}]`	Enumera los códigos de advertencia para tratar como errores. Use un punto y coma o una coma para separar varios códigos de advertencia. Para tratar todas las advertencias como errores, use el modificador sin valores. Cuando se trata una advertencia como un error, el destino continúa ejecutándose como si fuera una advertencia, pero se produce un error en la compilación general. Ejemplo: `-err:MSB4130`
`-warnNotAsError[:{code; ...}]` `-noerr[:{code; ...}]`	MSBuild 17.0 y versiones posteriores. Lista de códigos de advertencia que no se deben promover a errores. En concreto, si el modificador warnAsError está establecido para promover todas las advertencias a errores, los códigos de error especificados con warnNotAsError no se promueven. Esto no tiene ningún efecto si warnAsError no está establecido para promover todas las advertencias a errores. Use un punto y coma o una coma para separar varios códigos de advertencia. Ejemplo: `-noerr:MSB4130`
`-warnAsMessage[:{code}; ...}]` `-noWarn[:{code; ...}]`	Enumera los códigos de advertencia para tratar como mensajes de importancia baja. Use un punto y coma o una coma para separar varios códigos de advertencia. Ejemplo: `-noWarn:MSB3026`

Modificadores para registradores

Switch	Descripción
`-binaryLogger[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]` `-bl[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]`	Serializa todos los eventos de compilación en un archivo binario comprimido. De manera predeterminada, el archivo está en el directorio actual y se denomina msbuild.binlog. El registro binario es una descripción detallada del proceso de compilación que puede usarse más tarde para reconstruir registros de texto y usarse con otras herramientas de análisis. Normalmente un registro binario es de 10 a 20 veces más pequeño que el registro de nivel de diagnóstico de texto más detallado, pero contiene más información. El registrador binario recopila de manera predeterminada el texto de origen de los archivos de proyecto, incluidos todos los proyectos importados y los archivos de destino que se han encontrado durante la compilación. El parámetro opcional `ProjectImports` controla este comportamiento: - ProjectImports=None. No recopila las importaciones de proyecto. - ProjectImports=Embed. Inserta las importaciones del proyecto en el archivo de registro de forma predeterminada. - ProjectImports=ZipFile. Guarde los archivos de proyecto en {output}.projectimports.zip donde <output> es el mismo nombre que el nombre del archivo de registro binario. La configuración predeterminada para ProjectImports es "Embed". Nota: el registrador no recopila archivos de código fuente que no son de MSBuild, como `.cs`, `.cpp`, etc. Un archivo .binlog puede "reproducirse" si se pasa a msbuild.exe como argumento en lugar de como proyecto o solución. Otros registradores reciben la información contenida en el archivo de registro como si se estuviera produciendo la compilación original. Puede leer más acerca del registro binario y sus usos en: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md Ejemplos: - `-bl` - `-bl:output.binlog` - `-bl:output.binlog;ProjectImports=None` - `-bl:output.binlog;ProjectImports=ZipFile` - `-bl:..\..\custom.binlog` - `-binaryLogger`
`-consoleLoggerParameters:{parameters}` `-clp:{parameters}`	Pasa los parámetros especificados al registrador de la consola, lo que muestra información de compilación en la ventana de la consola. Puede especificar los parámetros siguientes: - PerformanceSummary. Muestra el tiempo empleado en tareas, destinos y proyectos. - Summary. Muestra un resumen de errores y advertencias al final. - NoSummary. No muestra un resumen de errores y advertencias al final. - ErrorsOnly. Muestra solo errores. - WarningsOnly. Muestra solo advertencias. - NoItemAndPropertyList. No muestra la lista de elementos y propiedades que aparecerían al principio de cada compilación del proyecto si se estableciera el nivel de detalle en `diagnostic`. - ShowCommandLine. Muestra los mensajes de `TaskCommandLineEvent`. - ShowProjectFile. Muestra la ruta de acceso al archivo del proyecto en los mensajes de diagnóstico. Esta configuración está activada de manera predeterminada. - ShowTimestamp. Muestra la marca de tiempo como un prefijo en los mensajes. - ShowEventId. Muestra el identificador de evento para los eventos iniciados, los eventos finalizados y los mensajes. - ForceNoAlign. No alinea el texto al tamaño del búfer de la consola. - DisableConsoleColor. Usa los colores de consola predeterminados para todos los mensajes de registro. - DisableMPLogging. Deshabilita el estilo de registro de resultados de multiprocesador al ejecutarse en el modo de no multiprocesador. - EnableMPLogging. Habilita el estilo de registro de multiprocesador aunque se ejecute en el modo de no multiprocesador. Este estilo de registro está habilitado de forma predeterminada. - ForceConsoleColor. Use colores de la consola ANSI incluso si la consola no la admite. - Verbosity. Invalide la `-verbosity` configuración de este registrador. Use un punto y coma para separar varios parámetros, como se muestra en el ejemplo siguiente: `-consoleloggerparameters:PerformanceSummary;NoSummary -verbosity:minimal` El registrador de consola predeterminado utiliza un nivel de detalle normal e incluye un valor `Summary`.
`-distributedFileLogger` `-dfl`	Registra los resultados de la compilación de cada nodo de MSBuild en su propio archivo. La ubicación inicial de estos archivos es el directorio actual. De forma predeterminada, los archivos se denominan MSBuild{NodeId}.log. Puede usar el `-fileLoggerParameters` modificador para especificar la ubicación de los archivos y otros parámetros para fileLogger. Si asigna un nombre a un archivo de registro mediante el `-fileLoggerParameters` modificador , el registrador distribuido usa ese nombre como plantilla y anexa el identificador de nodo a ese nombre al crear un archivo de registro para cada nodo.
`-distributedLogger:{central logger},{forwarding logger}, ...` `-dl:{central logger},{forwarding logger, ...}`	Registra eventos de MSBuild, adjuntando una instancia del registrador diferente a cada nodo. Para especificar varios registradores, hágalo por separado. Use la sintaxis del registrador para especificar un registrador, salvo que proporcione y una clase adicional para el registrador de reenvío. Para obtener la sintaxis del registrador, consulte el `-logger` modificador. En los ejemplos siguientes se muestra cómo utilizar este modificador: `-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll`
`-fileLogger[{number}]` `-fl[{number}]`	Registra el resultado de la compilación en un archivo único en el directorio actual. Si no especifica `number`, el archivo de salida se denomina msbuild.log. Si especifica `number`, el archivo de salida se denomina msbuild<n>.log, donde <n> es `number`. `Number` puede ser un dígito comprendido entre 1 y 9. Puede usar el `-fileLoggerParameters` modificador para especificar la ubicación del archivo y otros parámetros para fileLogger.
`-fileLoggerParameters[{number}]:` `parameters` `-flp[{number}]: {parameters}`	Especifica parámetros adicionales del registrador de archivos y del registrador de archivos distribuido. La presencia de este conmutador implica que el modificador correspondiente `-filelogger[number]` está presente. `Number` puede ser un dígito comprendido entre 1 y 9. Puede usar todos los parámetros enumerados para `-consoleloggerparameters`. También puede utilizar uno o varios de los parámetros siguientes: - LogFile. La ruta de acceso del archivo de registro donde se escribe el registro de compilación. El registrador de archivos distribuido usa esta ruta de acceso como prefijo en los nombres de los archivos de registro. - Append. Determina si el registro de compilación se anexará al archivo de registro o lo sobrescribirá. Cuando se establece el modificador, el registro de compilación se anexa al archivo de registro. Cuando el modificador no está presente, se sobrescribe el contenido de un archivo de registro existente. Ejemplo: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append` Si incluye un valor explícito `true` o `false`, el registro se anexa con independencia de la configuración. Si no incluye el modificador append, se sobrescribe el registro. En este caso, el archivo se sobrescribe: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log` En este caso, el archivo se anexa: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true` En este caso, el archivo se anexa: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false` - Encoding. Especifica la codificación del archivo (por ejemplo, UTF-8, Unicode o ASCII). El ejemplo siguiente genera archivos de registro independientes para advertencias y errores: `-flp1:logfile=errors.txt;errorsonly -flp2:logfile=warnings.txt;warningsonly` En los ejemplos siguientes se muestran otras posibilidades: `-fileLoggerParameters:LogFile=MyLog.log;Append; Verbosity=diagnostic;Encoding=UTF-8` `-flp:Summary;Verbosity=minimal;LogFile=msbuild.sum` `-flp1:warningsonly;logfile=msbuild.wrn` `-flp2:errorsonly;logfile=msbuild.err`
`-logger:logger` `-l:logger`	Especifica el registrador que se debe utilizar para registrar los eventos de MSBuild. Para especificar varios registradores, hágalo por separado. Utilice la sintaxis siguiente para `logger`: `[LoggerClass,]LoggerAssembly[;LoggerParameters]` Utilice la sintaxis siguiente para `LoggerClass`: `[PartialOrFullNamespace.]LoggerClassName` No necesita especificar la clase de registrador si el ensamblado contiene exactamente un registrador. Utilice la sintaxis siguiente para `LoggerAssembly`: `AssemblyName[,StrongName] \\| AssemblyFile` Los parámetros del registrador son opcionales y se pasan al registrador tal como se han escrito. En los ejemplos siguientes se usa el `-logger` modificador . `-logger:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML`
`-noConsoleLogger` `-noconlog`	Deshabilita el registrador de la consola predeterminado y no registra eventos en la consola.
`-terminalLogger[:auto`,`on`,`off]` `-tl[:auto`,`on`,`off]`	Habilite o deshabilite el registrador de terminales. El registrador de terminal proporciona una salida de compilación mejorada en la consola en tiempo real, organizada lógicamente por proyecto y diseñada para resaltar información accionable. Especifique `auto` (o use la opción sin argumentos) para usar el registrador de terminal solo si no se redirige la salida estándar. No analice la salida o, de lo contrario, confíe en que permanece sin cambios en versiones futuras. Esta opción está disponible en MSBuild 17.8 y versiones posteriores.

Ejemplo 1

En el siguiente ejemplo se compila el destino rebuild del proyecto MyProject.proj.

MSBuild.exe MyProject.proj -t:rebuild

Ejemplo 2

Puede usar MSBuild.exe para realizar compilaciones más complejas. Por ejemplo, puede utilizarlo para compilar determinados destinos de proyectos específicos de una solución. En el ejemplo siguiente se recompila el proyecto NotInSolutionFolder y se limpia el proyecto InSolutionFolder, que está en la carpeta de soluciones NewFolder.

msbuild SlnFolders.sln -t:NotInSolutionfolder:Rebuild;NewFolder\InSolutionFolder:Clean

Compartir vía