Referência de linha de comando do MSBuild

  • Artigo

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

Cada opção está disponível em dois formulários: -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 (separado 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.

Sintaxe

MSBuild.exe [Switches] [ProjectFile]

Argumentos

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

Comutadores

Comutador Formato curto Descrição
-detailedSummary[:True ou False] -ds[:True ou False] Se for True, mostrará informações detalhadas ao final do log de build sobre as configurações que foram criadas e como elas foram agendadas para os nós.
-getItem:itemName,... Escreve o valor do item ou dos itens após a avaliação, sem executar a compilação, ou se a opção -targets ou a opção -getTargetResult for usada, escreve os valores após a compilação.
-getProperty:propertyName,... Escreve o valor da propriedade ou das propriedades após a avaliação, sem executar a compilação, ou se a opção -targets ou a opção -getTargetResult for usada, escreve os valores após a compilação.
-getTargetResult:targetName,... Escreve os valores de saída dos destinos especificados.
-graphBuild[:True ou False] -graph[:True ou False] Faz com que o MSBuild construa e compile um grafo de projeto. Construir um grafo envolve identificar referências de projeto para formar dependências. A compilação desse grafo envolve a tentativa de compilar referências de projeto antes dos projetos que fazem referência a eles, diferentemente do agendamento tradicional do MSBuild. Exige o MSBuild 16 ou posterior.
-help /? ou -h Exibir informações de uso. O seguinte comando é um exemplo:

msbuild.exe -?
-ignoreProjectExtensions: extensions -ignore: extensions Ignora as extensões especificadas ao determinar qual arquivo de projeto deve ser criado. Use um ponto e vírgula ou uma vírgula para separar várias extensões, como mostra o exemplo abaixo:

-ignoreprojectextensions:.vcproj,.sln
-inputResultsCaches[:cacheFile[;cacheFile2] -irc[:cacheFile[;cacheFile2] 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 ou 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 é 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 ou MessageUponIsolationViolation ou False] -isolate[:True ou MessageUponIsolationViolation ou 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 serão serializados se a opção -outputResultsCache for fornecida. Essa opção é para reduzir as chances de um destino de violação de isolamento em um projeto de dependência usando estado incorreto devido à sua dependência de um destino armazenado em cache cujos efeitos colaterais não seriam levados em consideração. (Por exemplo, a definição de uma propriedade.) Esse modo é mais restritivo, pois requer que o gráfico do projeto seja estatisticamente 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 ou False] -low[:True ou 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 durante a compilação. Quando você não inclui essa opção, o valor padrão é 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, confira Compilando vários projetos em paralelo.

O exemplo abaixo instrui o MSBuild a compilar usando três processos MSBuild, o que permite que os 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. É possível especificar os seguintes valores:

- True. Os nós permanecem após a conclusão da compilação para que as compilações subsequentes possam usá-los (padrão).
- False. Os nós não permanecerão após o término da compilação.

Um nó corresponde a um projeto que está em execução. Se você incluir a opção -maxcpucount, vários nós poderão ser executados simultaneamente.
-nologo Não exibe a faixa de inicialização ou a mensagem de direitos autorais.
-preprocess[:filepath] -pp[:filepath] Cria um arquivo de projeto único, agregado pelo alinhamento de todos os arquivos que seriam importados durante a compilação, com seus limites marcados. Você pode usar essa opção para determinar facilmente quais arquivos estão sendo importados, de onde os arquivos estão sendo importados e quais arquivos contribuem para a compilação. Quando você usar essa opção, o projeto não é criado.

Se você especificar um filepath, o arquivo de projeto agregado será a saída para o arquivo. Caso contrário, a saída é 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, confira Elemento Import (MSBuild) e Como usar o mesmo destino em vários arquivos de projeto.
-outputResultsCache[:cacheFile] -orc[:cacheFile] Arquivo de cache de saída onde o MSBuild grava o conteúdo de seus caches de resultados de compilação no final da compilação. 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 Define ou substitui 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 uma vírgula para separar várias propriedades, como mostra o exemplo abaixo:

-property:WarningLevel=2;OutDir=bin\Debug
-restore -r Executa o destino do 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 Cria destinos especificados no projeto. Especifique cada destino separadamente ou use um ponto e vírgula ou uma vírgula para separar vários destinos, como mostra o exemplo abaixo:

-target:PrepareResources;Compile

Se você especificar quaisquer destinos usando essa opção, eles serão executados em vez de quaisquer destinos no DefaultTargets atributo no arquivo de projeto. Para obter mais informações, confira Ordem de build de destino e Como especificar o destino a ser criado primeiro.

Um destino é um grupo de tarefas. Para obter mais informações, consulte Destinos.
-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 que são usados para compilar um aplicativo. Para saber mais, confira Conjunto de ferramentas (ToolsVersion) e Configurações padrão e personalizadas do conjunto de ferramentas.
-validate:[schema] -val[schema] Valida o arquivo de projeto e, se a validação for bem-sucedida, compila 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 em relação ao esquema que você especificar.

A configuração abaixo é um exemplo: -validate:MyExtendedBuildSchema.xsd
-verbosity:level -v:level Especifica a quantidade de informações a serem exibidas no log de compilação. Cada agente exibe eventos de acordo com o nível de detalhamento que você definiu para esse agente.

Você pode especificar os seguintes níveis de detalhamento: q[uiet], m[inimal], n[ormal] (padrão), d[etailed] e diag[nostic].

A configuração abaixo é um exemplo: -verbosity:quiet
-version -ver Exibe somente informações de versão. O projeto não é criado.
@file Insere configurações de linha de comando de um arquivo de texto. Se você tiver vários arquivos, especifique-os separadamente. Para obter mais informações, confira Arquivos de resposta.
-warnAsError[:code[;code2] -err[:code[;code2] 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 a compilação geral falha.

Exemplo: -err:MSB4130
-warnNotAsError[:code[;code2] -noerr[:code[;code2] 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 de 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[;code2] -noWarn[:code[;code2] Lista de códigos de aviso a serem tratados 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

Comutador Formato curto Descrição
-binaryLogger[:[LogFile=]output.binlog
[;ProjectImports=[None,Embed,ZipFile]]]		 -bl Serializa todos os eventos de build para um arquivo binário comprimido. 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 posteriormente pode ser usado para reconstruir os logs de texto e ser usado por outras ferramentas de análise. Um log binário é geralmente 10 a 20x menor do que o log de nível de diagnóstico de texto mais detalhado, mas ele contém mais informações.

O agente binário coleta por padrão o texto de origem dos arquivos de projeto, incluindo todos os projetos importados e arquivos de destino encontrados durante o build. A opção ProjectImports opcional controla esse comportamento:

- ProjectImports=None. Não coletar as importações do projeto.
- ProjectImports=Embed. Inserir importações do projeto no arquivo de log (padrão).
- ProjectImports=ZipFile. Salve arquivos de projeto em <output>.projectimports.zip, em que <output> tem o mesmo nome do arquivo de log binário.

A configuração padrão para ProjectImports é Embed.
Nota: o registrador não coleta arquivos de origem não-MSBuild, como .cs, .cpp etc.
Um arquivo .binlog pode ser "reproduzido" passando-o para msbuild.exe como um argumento, em vez de um projeto/uma solução. Outros registradores recebem as informações contidas no arquivo de log como se a compilação 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 Passa os parâmetros que você especificar para o agente de console, que exibe informações de compilação na janela do console. É possível especificar os seguintes parâmetros:

- PerformanceSummary. Mostra o tempo gasto em tarefas, destinos e projetos.
- Summary. Mostra o resumo de aviso e erro no final.
- NoSummary. Não mostra o resumo de aviso e erro no final.
- ErrorsOnly. Mostra somente os erros.
- WarningsOnly. Mostra somente os avisos.
- NoItemAndPropertyList. Não mostra a lista de itens e propriedades que aparecem no início de cada compilação de projeto se o nível de detalhamento é definido como diagnostic.
- ShowCommandLine. Mostrar TaskCommandLineEvent mensagens.
- ShowProjectFile. Mostrar o caminho para o arquivo de projeto em mensagens de diagnóstico. Esta configuração está ativada por padrão.
- ShowTimestamp. Mostra o carimbo de data/hora como um prefixo em todas as mensagens.
- ShowEventId. Mostra a ID de evento para cada evento iniciado e concluído e a mensagem.
- ForceNoAlign. Não alinha o texto com o tamanho do buffer de console.
- DisableConsoleColor. Usa as cores de console padrão em todas as mensagens de log.
- DisableMPLogging. Desabilita o estilo de registro em log do multiprocessador da saída quando executado no modo não multiprocessador.
- EnableMPLogging. Habilita o estilo de registro em log do multiprocessador quando executado no modo não multiprocessador. Esse estilo de registro em log fica ativado por padrão.
- ForceConsoleColor. Use as cores do console ANSI mesmo que o console não ofereça suporte a ele.
- Verbosity. Substitui a configuração -verbosity para esse agente.

Use um ponto e vírgula ou uma vírgula para separar vários parâmetros, conforme o seguinte exemplo:

-consoleloggerparameters:PerformanceSummary;NoSummary -verbosity:minimal

O agente de console padrão está em um detalhamento normal e inclui um Summary.
-distributedFileLogger -dfl A saída da compilação de cada nó do MSBuild para seu próprio arquivo. A localização 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 do fileLogger.

Se você nomear um arquivo de log usando a opção -fileLoggerParameters , o registrador distribuído usará esse nome como um modelo e acrescentará a ID do nó a esse nome ao criar um arquivo de log para cada nó.
-distributedLogger:

central logger

forwarding logger		 -dl:central loggerforwarding logger Registra eventos do MSBuild, anexando uma instância do agente diferente a cada nó. Para especificar vários agentes, especifique cada um separadamente.

Você pode usar a sintaxe do agente para especificar um agente. Para a sintaxe do registrador, consulte a opção -logger .

Os exemplos abaixo mostram como usar o essa opção:

-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral

-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll
-fileLogger

[number]		 -fl[number] Registra a saída da compilação para um único arquivo no diretório atual. Se você não especificar number, o arquivo de saída será denominado 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 do fileLogger.
-fileLoggerParameters[number]:

parameters		 -flp[ number]: parameters Especifica parâmetros extras para o agente do arquivo e o agente do arquivo distribuído. A presença dessa opção indica que a opção -filelogger[number] 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 compilação será gravado. O agente de arquivos distribuído prefixa esse caminho aos nomes dos seus arquivos de log.
- Append. Determina se o log de compilação é acrescentado ao arquivo de log ou se o substitui. Quando você definir a opção, o log de compilação será anexado 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 a opção 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 é anexado: msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true
Nesse caso, o arquivo é anexado: 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 abaixo gera arquivos de log separados para avisos e erros:

-flp1:logfile=errors.txt;errorsonly -flp2:logfile=warnings.txt;warningsonly

Os exemplos abaixo 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 um separadamente.

Use a seguinte sintaxe para logger: [``LoggerClass``,]``LoggerAssembly``[;``LoggerParameters``]

Use a seguinte sintaxe para LoggerClass: [``PartialOrFullNamespace``.]``LoggerClassName

Você não precisa especificar a classe do agente se o assembly contiver exatamente um agente.

Use a seguinte sintaxe para LoggerAssembly: {``AssemblyName``[,``StrongName``] &#124;AssemblyFile``}

Os parâmetros de agente são opcionais e são passados ao agente exatamente como são inseridos.

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 Desabilita o agente de console padrão e não registra eventos no console.
-terminalLogger[:auto,on,off] -tl[:auto,on,off] Habilite ou desabilite o registrador de terminais. O registrador de terminal fornece saída de compilação aprimorada no console em tempo real, organizada logicamente por projeto e projetada para destacar informações acionáveis. Especifique auto (ou use a opção sem argumentos) para usar o registrador de terminal somente se a saída padrão não for redirecionada. Não analise a saída ou confie que ela permaneça inalterada em versões futuras. Essa opção está disponível no MSBuild 17.8 e posterior.

Exemplo 1

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

MSBuild.exe MyProject.proj -t:rebuild

Exemplo 2

Use o MSBuild.exe para executar builds mais complexos. Por exemplo, você pode usá-lo para compilar destinos específicos de projetos específicos em uma solução. O exemplo a seguir recompila o projeto NotInSolutionFolder e limpa o projeto InSolutionFolder, que está na pasta de solução NewFolder.

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

Confira também