Partilhar via

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 switch está disponível em duas formas: -switch e /switch. A documentação mostra apenas a forma -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.

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

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

A primeira coluna na tabela a seguir mostra uma forma longa e curta de cada opção. Ambas as formas são equivalentes.

Os colchetes [] indicam peças opcionais e as chaves {}indicam os valores fornecidos pelo usuário.

Switch Descrição
-detailedSummary[:{True or False}]

-ds[:{True or 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 or False}]

-graph[:{True or 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; ...}]

-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 é 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 serão serializados se a opção -outputResultsCache for fornecida. Essa opção é para mitigar as chances de um destino que viola o isolamento em um projeto de dependência usar o 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 grafo do projeto seja detectável estaticamente 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 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 o -maxcpucount switch, 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 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}		 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

Consulte Propriedades comuns do projeto 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 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 propriedades especificadas com o -property argumento. 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; ...}]

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

Switch 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 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. O parâmetro opcional ProjectImports 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 os arquivos de projeto em {output}.projectimports.zip em que <output> tem o mesmo nome que o nome do arquivo de log binário.

A configuração padrão para ProjectImports é Embed.
Observação: o agente não coleta arquivos de origem não MSBuild, como .cs, .cppe assim por diante.
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 dê suporte a ele.
- Verbosity. Substitua a -verbosity configuração desse 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 -fileLoggerParameters opção para especificar o local dos arquivos e outros parâmetros para o fileLogger.

Se você nomear um arquivo de log usando a -fileLoggerParameters opção, o agente 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 logger},{forwarding 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ê usa a sintaxe do agente para especificar um agente, exceto que você fornece uma classe adicional para o agente de encaminhamento. Para obter a sintaxe do agente, consulte a -logger opção.

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 -fileLoggerParameters opção para especificar o local do arquivo e outros parâmetros para o 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 chave implica que a chave correspondente -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] \| 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 o -logger switch.

-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]		 Ative ou desative o registrador de terminal. 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 nela inalterada em versões futuras. Essa opção está disponível no MSBuild 17.8 e posterior.

Exemplo

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

MSBuild.exe MyProject.proj -t:rebuild

Confira também