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>]
    [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
    [--force] [--interactive] [--no-dependencies] [--no-incremental]
    [--no-restore] [--nologo] [--no-self-contained] [--os <OS>]
    [-o|--output <OUTPUT_DIRECTORY>] [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--self-contained [true|false]] [--source <SOURCE>] [--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, confira 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, consulte 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.

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

  • -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 especificar essa opçã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.

  • -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 SDK do .NET 6.

  • --source <SOURCE>

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

  • -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. Para obter mais informações, consulte LoggerVerbosity.

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

    Define o RuntimeIdentifier como uma plataforma portátil RuntimeIdentifier com base em um de seu computador. Isso acontece implicitamente com propriedades que exigem um RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFilee 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
    
  • Compile um projeto e suas dependências para um runtime específico (no exemplo, Ubuntu 18.04):

    dotnet build --runtime ubuntu.18.04-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 compilação usando a -popção MSBuild:

    dotnet build -p:Version=1.2.3.4