Referência de linha de comando do MSBuild

2025-08-08

When you use MSBuild.exe to build a project or solution file, you can include several switches to specify various aspects of the process.

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.

The .NET CLI commands dotnet build, dotnet publish, dotnet msbuild and related commands pass these switches to MSBuild, so this reference is applicable when you use those commands; however dotnet run does not.

Syntax

MSBuild.exe [Switches] [ProjectFile]

Arguments

Argument Description

ProjectFile Cria os destinos no arquivo de projeto que você especificar. If you don't specify a project file, MSBuild searches the current working directory for a file name extension that ends in proj and uses that file. Você também pode especificar um arquivo de solução do Visual Studio para esse argumento. No Visual Studio 17.12 e posterior, há suporte para o formato de arquivo da solução .slnx, bem como o formato .sln. Os arquivos .sln e .slnx para a mesma solução podem estar presentes no mesmo diretório; se ambos estiverem presentes, você deverá especificar explicitamente um deles para criar a solução.

Argument	Description
`ProjectFile`	Cria os destinos no arquivo de projeto que você especificar. If you don't specify a project file, MSBuild searches the current working directory for a file name extension that ends in proj and uses that file. Você também pode especificar um arquivo de solução do Visual Studio para esse argumento. No Visual Studio 17.12 e posterior, há suporte para o formato de arquivo da solução `.slnx`, bem como o formato `.sln`. Os arquivos `.sln` e `.slnx` para a mesma solução podem estar presentes no mesmo diretório; se ambos estiverem presentes, você deverá especificar explicitamente um deles para criar a solução.

Switches

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.

Switch	Description
`-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`	Don't include any MSBuild.rsp or Directory.Build.rsp files automatically.
`-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. For more information, see Targets.
`-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. See Toolset (ToolsVersion) and Standard and custom toolset configurations.
`-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. For more information, see Response files.
`-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

Switch	Description
`-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. By default the file is in the current directory and named msbuild.binlog. O parâmetro opcional `LogFile` aceita uma cadeia de caracteres do formulário `{filename}.binlog`, onde `{filename}` contém caracteres válidos do sistema de arquivos, mas também aceita um símbolo `{}`de espaço reservado. Se `{}` for fornecido, o MSBuild preencherá essa posição com um "carimbo exclusivo" do formulário `yyyyMMdd-HHmmss--<current process id>--<6-character random string>`. 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=Embed. Insira importações de projeto no arquivo de log (padrão). - ProjectImports=ZipFile. Save project files to {output}.projectimports.zip where <output> is the same name as the binary log file name. A configuração padrão para ProjectImports é Inserir. Note: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on. A .binlog file can be "played back" by passing it to msbuild.exe as an argument instead of a project/solution. 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 na visão geral do Log Binário do MSBuild. Examples: - `-bl` - `-bl:output.binlog` - `-bl:output.binlog;ProjectImports=None` - `-bl:output.binlog;ProjectImports=ZipFile` - `-bl:..\..\custom.binlog` - `-bl:publish-{}.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. - Summary. 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. - DisableMPLogging. 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. By default, the files are named 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. If you don't specify `number`, the output file is named 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. - Append. 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` - Encoding. 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]`	Enable or disable the terminal logger. 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.

Example

The following example builds the rebuild target of the MyProject.proj project.

MSBuild.exe MyProject.proj -t:rebuild

Comentários

Esta página foi útil?