dotnet build

Este artigo se aplica a: ✔️ SDK do .NET Core 3.1 e versões posteriores

Nome

dotnet build – Compila um projeto e todas as suas dependências.

Sinopse

dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
    [--disable-build-servers]
    [--force] [--interactive] [--no-dependencies] [--no-incremental]
    [--no-restore] [--nologo] [--no-self-contained] [--os <OS>]
    [-o|--output <OUTPUT_DIRECTORY>]
    [-p|--property:<PROPERTYNAME>=<VALUE>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--self-contained [true|false]] [--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

dotnet build -h|--help

Descrição

O comando dotnet build compila o projeto e suas dependências em um conjunto de binários. Os binários incluem o código do projeto em arquivos de linguagem intermediária (IL) com uma extensão .dll. A depender do tipo de projeto e das configurações, outros arquivos podem ser incluídos, tais como:

• Um executável que pode ser usado para executar o aplicativo, se o tipo de projeto for um executável direcionado para o .NET Core 3.0 ou posterior.
• Arquivos de símbolo usados para depuração com uma extensão .pdb.
• Um arquivo .deps.jsno, que lista as dependências do aplicativo ou da biblioteca.
• Um arquivo .runtimeconfig.jsno, que especifica o tempo de execução compartilhado e sua versão em um aplicativo.
• Outras bibliotecas das quais o projeto depende (por meio de referências de projeto ou referências de pacote do NuGet).

Para projetos executáveis direcionados a versões anteriores ao .NET Core 3.0, as dependências de biblioteca do NuGet normalmente NÃO são copiadas para a pasta de saída. Eles são resolvidos da pasta de pacotes globais do NuGet em tempo de execução. Com isso em mente, o produto de dotnet build não está pronto para ser transferido para outro computador para execução. Para criar uma versão do aplicativo que pode ser implantada, você precisa publicá-lo (por exemplo, com o comando dotnet publish). Para obter mais informações, consulte Implantação de aplicativos .NET.

Para projetos executáveis direcionados ao .NET Core 3.0 e posteriores, as dependências da biblioteca são copiadas para a pasta de saída. Isso significa que, se não houver nenhuma outra lógica específica de publicação (como projetos Web), a saída de compilação deverá ser implantável.

Restauração implícita

A compilação exige o arquivo project.assets.json, que lista as dependências do seu aplicativo. O arquivo é criado quando dotnet restore é executado. Sem o arquivo de ativos em vigor, as ferramentas não conseguem resolver os assemblies de referência, o que resulta em erros.

Não é necessário executar dotnet restore, pois ele é executado implicitamente por todos os comandos que exigem uma restauração, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish e dotnet pack. Para desabilitar a restauração implícita, use a opção --no-restore.

O comando dotnet restore ainda é útil em determinados cenários em que realizar uma restauração explícita faz sentido, como compilações de integração contínua no Azure DevOps Services ou em sistemas de compilação que precisam controlar explicitamente quando a restauração ocorrerá.

Para obter informações sobre como gerenciar feeds do NuGet, consulte a documentação de dotnet restore.

Este comando é compatível com as opções dotnet restore quando passado no formato longo (por exemplo, --source). Opções de formato curto, como -s, não são compatíveis.

Saída executável ou de biblioteca

O fato de o projeto ser executável ou não é determinado pela propriedade <OutputType> do arquivo de projeto. O seguinte exemplo mostra um projeto que produz um código executável:

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

Para produzir uma biblioteca, omita a propriedade <OutputType> ou altere seu valor para Library. A DLL IL de uma biblioteca não contém pontos de entrada e não pode ser executada.

MSBuild

O dotnet build usa o MSBuild para compilar o projeto e, portanto, dá suporte a builds paralelos e incrementais. Para obter mais informações, consulte Compilações incrementais.

Além das próprias opções, o comando dotnet build também aceita opções do MSBuild, como -p para configurar propriedades ou -l para definir um agente. Para obter mais informações sobre essas opções, confira a Referência de linha de comando do MSBuild. Ou você também pode usar o comando dotnet msbuild.

Observação

Quando dotnet build é executado automaticamente por dotnet run, argumentos como -property:property=value não são respeitados.

Executar dotnet build é equivalente a executar dotnet msbuild -restore; no entanto, a o padrão de saída é diferente.

Downloads de manifesto de carga de trabalho

Quando você executa esse comando, ele inicia um download assíncrono em segundo plano de manifestos de publicidade para cargas de trabalho. Se o download ainda estiver em execução quando esse comando for concluído, o download será interrompido. Para saber mais, confira Manifestos de publicidade.

Argumentos

PROJECT | SOLUTION

O arquivo de projeto ou solução a ser compilado. Se um arquivo de solução ou projeto não for especificado, o MSBuild pesquisará o diretório de trabalho atual em busca de um arquivo que tenha uma extensão terminada em proj ou sln e usará esse arquivo.

Opções

• -a|--arch <ARCHITECTURE>

  Especifica a arquitetura de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador win-x64, a especificação de --arch x86 define o RID como win-x86. Se você usar essa opção, não use a opção -r|--runtime. Disponível desde a versão prévia 7 do .NET 6.

• --artifacts-path <ARTIFACTS_DIR>

  Todos os arquivos de saída de compilação do comando executado irão para subpastas no caminho especificado, separados por projeto. Para obter mais informações, consulte Layout de saída de artefatos. Disponível desde o SDK do .NET 8.

• -c|--configuration <CONFIGURATION>

  Define a configuração da compilação. O padrão para a maioria dos projetos é Debug, mas você pode substituir as configurações de compilação em seu projeto.

• --disable-build-servers

  Força o comando a ignorar qualquer servidor de compilação persistente. Essa opção fornece uma maneira consistente de desativar todo o uso do cache de compilação, o que força uma compilação do zero. Uma compilação que não depende de caches é útil quando os caches podem estar corrompidos ou incorretos por algum motivo. Disponível desde o SDK do .NET 7.

• -f|--framework <FRAMEWORK>

  Compila para uma estrutura específica. A estrutura precisa ser definida no arquivo de projeto. Exemplos: net7.0, net462.

• --force

  Forçará todas as dependências a serem resolvidas mesmo se última restauração tiver sido bem-sucedida. A especificação desse sinalizador é o mesmo que a exclusão do arquivo project.assets.json.

• -?|-h|--help

  Imprime uma descrição de como usar o comando.

• --interactive

  Permite que o comando pare e aguarde entrada ou ação do usuário. Por exemplo, para concluir a autenticação. Disponível desde o SDK do .NET Core 3.0.

• --no-dependencies

  Ignora as referências P2P (projeto a projeto) e compila apenas o projeto raiz especificado.

• --no-incremental

  Marca o build como não segura para build incremental. Esse sinalizador desativa a compilação incremental e força uma nova recompilação do grafo de dependência do projeto.

• --no-restore

  Não executa uma restauração implícita durante o build.

• --nologo

  Não exibe a faixa de inicialização nem a mensagem de direitos autorais.

• --no-self-contained

  Publica o aplicativo como um aplicativo dependente de estrutura. Um runtime do .NET compatível deve ser instalado no computador de destino para executar o aplicativo. Disponível desde o SDK do .NET 6.

• -o|--output <OUTPUT_DIRECTORY>

  Diretório no qual os binários compilados são colocados. Se não for especificado, o caminho padrão será ./bin/<configuration>/<framework>/. Para projetos com várias estruturas de destino (por meio da propriedade TargetFrameworks), você também precisa definir --framework quando especifica essa opção.

  • SDK do .NET 7.0.200 e posterior

    Se você especificar a opção --output ao executar esse comando em uma solução, a CLI emitirá um aviso (um erro em 7.0.200) devido à semântica pouco clara do caminho de saída. A opção --output não é permitida, porque todas as saídas de todos os projetos criados serão copiadas para o diretório especificado, o que não é compatível com projetos multiplataforma, bem como projetos que têm diferentes versões de dependências diretas e transitivas. Para obter mais informações, confira A opção --output no nível da solução não é mais válida para comandos relacionados à compilação.

• --os <OS>

  Especifica o sistema operacional (SO) de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador win-x64, a especificação de --os linux define o RID como linux-x64. Se você usar essa opção, não use a opção -r|--runtime. Disponível desde o .NET 6.

• -p|--property:<PROPERTYNAME>=<VALUE>

  Define uma ou mais propriedades MSBuild. Especifique várias propriedades delimitadas por ponto-e-vírgula ou repetindo a opção:

  --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
  --property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
  

• -r|--runtime <RUNTIME_IDENTIFIER>

  Especifica o runtime de destino. Para obter uma lista de RIDs (Identificadores de Runtime), veja o Catálogo de RIDs. Se você usar essa opção com o SDK do .NET 6, use --self-contained ou --no-self-contained também. Se não for especificado, o padrão será compilar para o sistema operacional e a arquitetura atuais.

• --self-contained [true|false]

  Publica o runtime do .NET com o aplicativo para que não seja necessário instalar o runtime no computador de destino. O padrão é true se um identificador de runtime for especificado. Disponível desde o .NET 6.

• --source <SOURCE>

  A URI da origem do pacote NuGet a ser usada durante a operação de restauração.

• --tl:[auto|on|off]

  Especifica se o agente de terminal deve ser usado para a saída de build. O padrão é auto, que primeiro verifica o ambiente antes de habilitar o registro em log do terminal. A verificação de ambiente confirma se o terminal é capaz de usar recursos de saída modernos e não está usando uma saída padrão redirecionada antes de habilitar o novo agente. on ignora a verificação de ambiente e habilita o registro em log do terminal. off ignora a verificação de ambiente e usa o agente de console padrão.

  O agente de terminal mostra a fase de restauração seguida pela fase de build. Durante cada fase, os projetos de construção atuais aparecem na parte inferior do terminal. Cada projeto que está sendo criado gera tanto o destino do MSBuild em construção no momento quanto o tempo gasto nesse destino. Você pode pesquisar essas informações para saber mais sobre o build. Quando a build de um projeto é concluída, é gravada uma única seção "build concluída" que captura:

  • O nome do projeto criado.
  • A estrutura de destino (se houver vários destinos).
  • O status dessa build.
  • A saída primária dessa build (que contém um hiperlink).
  • Qualquer diagnóstico gerado para esse projeto.

  Esta opção está disponível desde o .NET 8.

• -v|--verbosity <LEVEL>

  Define o nível de detalhes do comando. Os valores permitidos são q[uiet], m[inimal], n[ormal], d[etailed] e diag[nostic]. O padrão é minimal. Por padrão, o MSBuild exibe avisos e erros em todos os níveis de detalhamento. Para excluir avisos, use /property:WarningLevel=0. Para obter mais informações, confira LoggerVerbosity e WarningLevel.

• --use-current-runtime, --ucr [true|false]

  Define RuntimeIdentifier como uma plataforma portátil RuntimeIdentifier com base em um de seus computadores. Isso acontece implicitamente com propriedades que exigem RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFile e PublishReadyToRun. Se a propriedade for definida como false, essa resolução implícita não ocorrerá mais.

• --version-suffix <VERSION_SUFFIX>

  Define o valor da propriedade $(VersionSuffix) a ser usada ao compilar o projeto. Isso funcionará apenas se a propriedade $(Version) não estiver definida. Em seguida, $(Version) é definido como o $(VersionPrefix) combinado com o $(VersionSuffix), separado por um traço.

Exemplos

• Compile um projeto e suas dependências:

  dotnet build
  

• Compile um projeto e suas dependências usando a configuração da Versão:

  dotnet build --configuration Release
  

• Crie um projeto e suas dependências para um runtime específico (neste exemplo, Linux):

  dotnet build --runtime linux-x64
  

• Compile o projeto e use a fonte do pacote NuGet especificada durante a operação de restauração:

  dotnet build --source c:\packages\mypackages
  

• Compile o projeto e defina a versão 1.2.3.4 como um parâmetro de build usando a -p opção MSBuild:

  dotnet build -p:Version=1.2.3.4