Referência de linha de comando do MSBuild

Artigo
11/01/2024

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`, `.cpp`e 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 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

Compartilhar via