Referência de linha de comando do MSBuild

Artigo
01/27/2025

Ao usar MSBuild.exe para criar um projeto ou arquivo de solução, você pode incluir várias opções para especificar vários aspectos do processo.

Cada comutador está disponível em duas formas: -switch e /switch. A documentação mostra apenas o formulário -switch. As opções não diferenciam maiúsculas de minúsculas. Se você executar o MSBuild de um shell diferente do prompt de comando do Windows, listas de argumentos para um comutador (separados por ponto-e-vírgula ou vírgulas) podem precisar de aspas simples ou duplas para garantir que as listas sejam passadas para o MSBuild em vez de interpretadas pelo shell.

Os comandos da CLI do .NET dotnet build, dotnet publish, dotnet msbuild e comandos relacionados passam essas opções para o MSBuild, portanto, essa referência é aplicável quando você usa esses comandos; no entanto, dotnet run não.

Sintaxe

MSBuild.exe [Switches] [ProjectFile]

Argumentos

Argumento	Descrição
`ProjectFile`	Cria os destinos no arquivo de projeto que você especificar. Se você não especificar um arquivo de projeto, o MSBuild pesquisará no diretório de trabalho atual uma extensão de nome de arquivo que termina em proj e usa esse arquivo. Você também pode especificar um arquivo de solução do Visual Studio para esse argumento.

Interruptores

A primeira coluna da tabela a seguir mostra uma forma longa e curta de cada comutador. Ambos os formulários são equivalentes.

Colchetes [] indicam partes opcionais e chaves {}indicam valores fornecidos pelo usuário.

Interruptor	Descrição
`-detailedSummary[:{True or False}]` `-ds[:{True or False}]`	Se `True`, mostre informações detalhadas no final do log de build sobre as configurações que foram criadas e como elas foram agendadas para nós.
`-getItem:{itemName,...}`	Anote o valor do item ou dos itens após a avaliação, sem executar o build ou se a opção `-targets` ou a opção `-getTargetResult` for usada, anote os valores após o build.
`-getProperty:{propertyName,...}`	Anote o valor da propriedade ou das propriedades após a avaliação, sem executar o build ou se a opção `-targets` ou a opção `-getTargetResult` for usada, escreva os valores após o build.
`-getTargetResult:{targetName,...}`	Anote os valores de saída dos destinos especificados.
`-graphBuild[:{True or False}]` `-graph[:{True or False}]`	Faz com que o MSBuild construa e crie um grafo de projeto. A construção de um grafo envolve a identificação de referências de projeto para formar dependências. A criação desse grafo envolve a tentativa de criar referências de projeto antes dos projetos que fazem referência a eles, diferentemente do agendamento tradicional do MSBuild. Requer o MSBuild 16 ou posterior.
`-help` `/?` ou `-h`	Exibir informações de uso. O seguinte comando é um exemplo: `msbuild.exe -?`
`-ignoreProjectExtensions: {extensions}` `-ignore: {extensions}`	Ignore as extensões especificadas ao determinar qual arquivo de projeto será compilado. Use um ponto-e-vírgula ou uma vírgula para separar várias extensões, como mostra o exemplo a seguir: `-ignoreprojectextensions:.vcproj,.sln`
`-inputResultsCaches[:{cacheFile; ...}]` `-irc[:{cacheFile; ...}]`	Lista separada de ponto-e-vírgula de arquivos de cache de entrada dos quais o MSBuild lerá os resultados do build. Se `-isolateProjects` estiver definido como `False`, isso o definirá como `True`.
`-interactive[:{True or False}]`	Indica que as ações no build têm permissão para interagir com o usuário. Não use esse argumento em um cenário automatizado em que a interatividade não seja esperada. Especificar `-interactive` é o mesmo que especificar `-interactive:true`. Use o parâmetro para substituir um valor proveniente de um arquivo de resposta.
`-isolateProjects[:{True, MessageUponIsolationViolation, False}]` `-isolate[:{True, MessageUponIsolationViolation, False}]`	Faz com que o MSBuild crie cada projeto isoladamente. Quando definido como `MessageUponIsolationViolation` (ou sua forma curta `Message`), somente os resultados de destinos de nível superior são serializados se a opção `-outputResultsCache` for fornecida. Essa opção é reduzir as chances de um destino que viola o isolamento em um projeto de dependência usando o estado incorreto devido à sua dependência em um destino armazenado em cache cujos efeitos colaterais não seriam levados em conta. (Por exemplo, a definição de uma propriedade.) Esse modo é mais restritivo, pois exige que o grafo do projeto seja estaticamente detectável no momento da avaliação, mas pode melhorar o agendamento e reduzir a sobrecarga de memória ao criar um grande conjunto de projetos.
`-lowPriority[:{True or False}]` `-low[:{True or False}]`	Faz com que o MSBuild seja executado com baixa prioridade de processo. Especificar `-lowPriority` é o mesmo que especificar `-lowPriority:True`.
`-maxCpuCount[:{number}]` `-m[:{number}]`	Especifica o número máximo de processos simultâneos a serem usados ao compilar. Se você não incluir essa opção, o valor padrão será 1. Se você incluir essa opção sem especificar um valor, o MSBuild usará até o número de processadores no computador. Para obter mais informações, consulte Criando vários projetos em paralelo. O exemplo a seguir instrui o MSBuild a criar usando três processos do MSBuild, o que permite que três projetos sejam compilados ao mesmo tempo: `msbuild myproject.proj -maxcpucount:3`
`-noAutoResponse` `-noautorsp`	Não inclua arquivos MSBuild.rsp ou Directory.Build.rsp automaticamente.
`-nodeReuse:{value}` `-nr:{value}`	Habilite ou desabilite a reutilização de nós do MSBuild. Você pode especificar os seguintes valores: - True. Os nós permanecem após a conclusão do build para que os builds subsequentes possam usá-los (padrão). - false. Os nós não permanecem após a conclusão do build. Um nó corresponde a um projeto em execução. Se você incluir a opção `-maxcpucount`, vários nós poderão ser executados simultaneamente.
`-nologo`	Não exiba a faixa de inicialização ou a mensagem de direitos autorais.
`-preprocess[:{filepath}]` `-pp[:{filepath}]`	Crie um único arquivo de projeto agregado, sublinhando todos os arquivos que seriam importados durante um build, com seus limites marcados. Você pode usar essa opção para determinar com mais facilidade quais arquivos estão sendo importados, de onde os arquivos estão sendo importados e quais arquivos contribuem para o build. Quando você usa essa opção, o projeto não é criado. Se você especificar um `filepath`, o arquivo de projeto agregado será enviado para o arquivo. Caso contrário, a saída será exibida na janela do console. Para obter informações sobre como usar o elemento `Import` para inserir um arquivo de projeto em outro arquivo de projeto, consulte do elemento de importação (MSBuild) e Como usar o mesmo destino em vários arquivos de projeto.
`-outputResultsCache[:{cacheFile}]` `-orc[:{cacheFile}]`	Arquivo de cache de saída em que o MSBuild grava o conteúdo de seus caches de resultados de build no final do build. Se `-isolateProjects` estiver definido como `False`, isso o definirá como `True`.
`profileEvaluation:{file}`	Cria perfis de avaliação do MSBuild e grava o resultado no arquivo especificado. Se a extensão do arquivo especificado for '.md', o resultado será gerado no formato Markdown. Caso contrário, um arquivo separado por tabulação será produzido.
`-property:{name}={value}` `-p:{name}={value}`	Defina ou substitua as propriedades de nível de projeto especificadas, em que `name` é o nome da propriedade e `value` é o valor da propriedade. Especifique cada propriedade separadamente ou use um ponto-e-vírgula ou vírgula para separar várias propriedades, como mostra o exemplo a seguir: `-property:WarningLevel=2;OutDir=bin\Debug` Consulte propriedades comuns de projeto do MSBuild para obter uma lista de propriedades comumente usadas. O conjunto completo de propriedades disponíveis depende do tipo de projeto, do SDK e dos arquivos importados.
`-restore` `-r`	Executa o destino `Restore` antes de criar os destinos reais.
`-restoreProperty:{name}={value}` `-rp:{name}={value}`	Defina ou substitua essas propriedades no nível do projeto somente durante a restauração e não use as propriedades especificadas com o argumento `-property`. `name` é o nome da propriedade e `value` é o valor da propriedade. Use um ponto-e-vírgula ou uma vírgula para separar várias propriedades ou especificar cada propriedade separadamente.
`-target:{targets}` `-t:{targets}`	Crie os destinos especificados no projeto. Especifique cada destino separadamente ou use um ponto-e-vírgula ou vírgula para separar vários destinos, como mostra o exemplo a seguir: `-target:PrepareResources;Compile` Se você especificar quaisquer destinos usando esse comutador, eles são executados em vez de quaisquer destinos no atributo `DefaultTargets` no arquivo de projeto. Para obter mais informações, consulte de ordem de build de destino e Como especificar qual destino criar primeiro. Um destino é um grupo de tarefas. Para obter mais informações, consulte destinos de.
`-targets[:{file}]` `-ts[:{file}]`	Escreva a lista de destinos disponíveis no arquivo especificado (ou no dispositivo de saída, se nenhum arquivo for especificado), sem realmente executar o processo de build.
`-toolsVersion:{version}` `-tv:{version}`	Especifica um conjunto de ferramentas personalizado. Um conjunto de ferramentas consiste em tarefas, destinos e ferramentas usadas para criar um aplicativo. Consulte do conjunto de ferramentas (ToolsVersion) e configurações de conjunto de ferramentas padrão e personalizado.
`-validate:[{schema}]` `-val[{schema}]`	Valide o arquivo de projeto e, se a validação for bem-sucedida, compile o projeto. Se você não especificar `schema`, o projeto será validado em relação ao esquema padrão. Se você especificar `schema`, o projeto será validado no esquema especificado. A seguinte configuração é um exemplo: `-validate:MyExtendedBuildSchema.xsd`
`-verbosity:{level}` `-v:{level}`	Especifica a quantidade de informações a serem exibidas no log de build. Cada agente exibe eventos com base no nível de verbosidade definido para esse agente. Você pode especificar os seguintes níveis de verbosidade: `q[uiet]`, `m[inimal]`, `n[ormal]` (padrão), `d[etailed]`e `diag[nostic]`. A seguinte configuração é um exemplo: `-verbosity:quiet`
`-version` `-ver`	Exibir somente informações de versão. O projeto não foi criado.
`@{file}`	Insira comutadores de linha de comando de um arquivo de texto. Se você tiver vários arquivos, especifique-os separadamente. Para obter mais informações, consulte arquivos de resposta.
`-warnAsError[:{code; ...}]` `-err[:{code; ...}]`	Lista de códigos de aviso a serem tratados como erros. Use um ponto-e-vírgula ou uma vírgula para separar vários códigos de aviso. Para tratar todos os avisos como erros, use a opção sem valores. Quando um aviso é tratado como um erro, o destino continua a ser executado como se fosse um aviso, mas o build geral falha. Exemplo: `-err:MSB4130`
`-warnNotAsError[:{code; ...}]` `-noerr[:{code; ...}]`	MSBuild 17.0 e posterior. Lista de códigos de aviso que não devem ser promovidos a erros. Especificamente, se a opção warnAsError estiver definida para promover todos os avisos a erros, os códigos de erro especificados com warnNotAsError não serão promovidos. Isso não terá efeito se warnAsError não estiver definido para promover todos os avisos a erros. Use um ponto-e-vírgula ou uma vírgula para separar vários códigos de aviso. Exemplo: `-noerr:MSB4130`
`-warnAsMessage[:{code}; ...}]` `-noWarn[:{code; ...}]`	Lista de códigos de aviso para tratar como mensagens de baixa importância. Use um ponto-e-vírgula ou uma vírgula para separar vários códigos de aviso. Exemplo: `-noWarn:MSB3026`

Opções para agentes

Interruptor	Descrição
`-binaryLogger[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]` `-bl[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]`	Serializa todos os eventos de build para um arquivo binário compactado. Por padrão, o arquivo está no diretório atual e nomeado msbuild.binlog. O log binário é uma descrição detalhada do processo de build que pode ser usado posteriormente para reconstruir logs de texto e usado por outras ferramentas de análise. Um log binário geralmente é 10-20x menor que o log de nível de diagnóstico de texto mais detalhado, mas contém mais informações. O agente binário, por padrão, coleta o texto de origem dos arquivos de projeto, incluindo todos os projetos importados e arquivos de destino encontrados durante o build. O parâmetro `ProjectImports` opcional controla esse comportamento: - ProjectImports=None. Não colete as importações do projeto. - ProjectImports=Insira. Insira importações de projeto no arquivo de log (padrão). - ProjectImports=ZipFile. Salve arquivos de projeto para {output}.projectimports.zip em que <> de saída é o mesmo nome do arquivo de log binário. A configuração padrão para ProjectImports é Inserir. Observação: o agente não coleta arquivos de origem não MSBuild, como `.cs`, `.cpp`e assim por diante. Um arquivo de .binlog pode ser "reproduzido" passando-o para msbuild.exe como um argumento em vez de um projeto/solução. Outros agentes recebem as informações contidas no arquivo de log como se o build original estivesse acontecendo. Você pode ler mais sobre o log binário e seus usos em: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md exemplos: - `-bl` - `-bl:output.binlog` - `-bl:output.binlog;ProjectImports=None` - `-bl:output.binlog;ProjectImports=ZipFile` - `-bl:..\..\custom.binlog` - `-binaryLogger`
`-consoleLoggerParameters:{parameters}` `-clp:{parameters}`	Passe os parâmetros especificados para o agente do console, que exibe informações de build na janela do console. Você pode especificar os seguintes parâmetros: - PerformanceSummary. Mostre o tempo gasto em tarefas, destinos e projetos. - Resumo. Mostrar o erro e o resumo do aviso no final. - NoSummary . Não mostre o erro e o resumo do aviso no final. - ErrorsOnly. Mostrar somente erros. - WarningsOnly. Mostrar somente avisos. - NoItemAndPropertyList. Não mostre a lista de itens e propriedades que apareceriam no início de cada build de projeto se o nível de verbosidade estiver definido como `diagnostic`. - ShowCommandLine. Mostrar `TaskCommandLineEvent` mensagens. - ShowProjectFile. Mostrar o caminho para o arquivo de projeto em mensagens de diagnóstico. Essa configuração está ativada por padrão. - ShowTimestamp. Mostrar o carimbo de data/hora como um prefixo para qualquer mensagem. - ShowEventId. Mostrar a ID do evento para cada evento iniciado, evento concluído e mensagem. - ForceNoAlign. Não alinhe o texto ao tamanho do buffer do console. - DisableConsoleColor . Use as cores padrão do console para todas as mensagens de registro em log. - Desabilitarde Log deMP . Desabilite o estilo de log de vários processadores de saída ao executar no modo não multiprocessador. - EnableMPLogging. Habilite o estilo de log de vários processadores mesmo quando estiver em execução no modo não multiprocessador. Esse estilo de registro em log está ativado por padrão. - ForceConsoleColor. Use cores de console ANSI mesmo que o console não dê suporte a ele. - Verbosity. Substitua a configuração de `-verbosity` para esse agente. Use um ponto-e-vírgula para separar vários parâmetros, como mostra o exemplo a seguir: `-consoleLoggerParameters:PerformanceSummary;NoSummary -verbosity:minimal` O agente de console padrão está em uma verbosidade normal e inclui um `Summary`.
`-distributedFileLogger` `-dfl`	Registre a saída de build de cada nó do MSBuild em seu próprio arquivo. O local inicial desses arquivos é o diretório atual. Por padrão, os arquivos são nomeados MSBuild{NodeId}.log. Você pode usar a opção `-fileLoggerParameters` para especificar o local dos arquivos e outros parâmetros para o fileLogger. Se você nomear um arquivo de log usando a opção `-fileLoggerParameters`, o agente distribuído usará esse nome como modelo e anexará a ID do nó a esse nome ao criar um arquivo de log para cada nó.
`-distributedLogger:{central logger},{forwarding logger}, ...` `-dl:{central logger},{forwarding logger, ...}`	Registrar eventos do MSBuild, anexando uma instância de agente diferente a cada nó. Para especificar vários agentes, especifique cada agente separadamente. Use a sintaxe do agente para especificar um agente, exceto que você fornece e classe adicional para o agente de encaminhamento. Para a sintaxe do agente, consulte a opção `-logger`. Os exemplos a seguir mostram como usar esta opção: `-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll`
`-fileLogger[{number}]` `-fl[{number}]`	Registre a saída de build em um único arquivo no diretório atual. Se você não especificar `number`, o arquivo de saída será nomeado msbuild.log. Se você especificar `number`, o arquivo de saída será nomeado msbuild<n>.log, em que <n> é `number`. `Number` pode ser um dígito de 1 a 9. Você pode usar a opção `-fileLoggerParameters` para especificar o local do arquivo e outros parâmetros para o fileLogger.
`-fileLoggerParameters[{number}]:` `parameters` `-flp[{number}]: {parameters}`	Especifica quaisquer parâmetros extras para o agente de arquivos e o agente de arquivo distribuído. A presença desse comutador implica que o comutador de `-filelogger[number]` correspondente está presente. `Number` pode ser um dígito de 1 a 9. Você pode usar todos os parâmetros listados para `-consoleloggerparameters`. Você também pode usar um ou mais dos seguintes parâmetros: - LogFile. O caminho para o arquivo de log no qual o log de build é gravado. O agente de arquivo distribuído prefixa esse caminho para os nomes de seus arquivos de log. - Acrescentar. Determina se o log de build é acrescentado ao arquivo de log ou o substitui. Quando você define a opção, o log de build é acrescentado ao arquivo de log. Quando a opção não está presente, o conteúdo de um arquivo de log existente é substituído. Exemplo: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append` Se você incluir uma configuração `true` ou `false` explícita, o log será acrescentado independentemente da configuração. Se você não incluir o comutador de acréscimo, o log será substituído. Nesse caso, o arquivo é substituído: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log` Nesse caso, o arquivo é acrescentado: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true` Nesse caso, o arquivo é acrescentado: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false` - codificação. Especifica a codificação do arquivo (por exemplo, UTF-8, Unicode ou ASCII). O exemplo a seguir gera arquivos de log separados para avisos e erros: `-flp1:logfile=errors.txt;errorsonly -flp2:logfile=warnings.txt;warningsonly` Os exemplos a seguir mostram outras possibilidades: `-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 o agente a ser usado para registrar eventos do MSBuild. Para especificar vários agentes, especifique cada agente separadamente. Use a seguinte sintaxe para `logger`: `[LoggerClass,]LoggerAssembly[;LoggerParameters]` Use a seguinte sintaxe para `LoggerClass`: `[PartialOrFullNamespace.]LoggerClassName` Você não precisará especificar a classe de agente se o assembly contiver exatamente um agente. Use a seguinte sintaxe para `LoggerAssembly`: `AssemblyName[,StrongName] \\| AssemblyFile` Os parâmetros do agente são opcionais e são passados para o agente exatamente quando você os insere. Os exemplos a seguir usam a opção `-logger`. `-logger:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML`
`-noConsoleLogger` `-noconlog`	Desabilite o agente de console padrão e não registre eventos no console.
`-terminalLogger[:auto`,`on`,`off]` `-tl[:auto`,`on`,`off]`	Habilitar ou desabilitar o agente do terminal . O agente de terminal fornece saída de build aprimorada no console em tempo real, organizada logicamente por projeto e projetada para realçar informações acionáveis. Especifique `auto` (ou use a opção sem argumentos) para usar o agente de terminal somente se a saída padrão não for redirecionada. Não analise a saída ou confie nela permanecendo inalterada em versões futuras. Essa opção está disponível no MSBuild 17.8 e posterior.

Exemplo

O exemplo a seguir cria o destino rebuild do projeto MyProject.proj.

MSBuild.exe MyProject.proj -t:rebuild

Consulte também

de referência do MSBuild
propriedades comuns do projeto MSBuild

Compartilhar via