build dotnet

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

Nome

dotnet build - Cria um projeto, uma solução ou um aplicativo baseado em arquivo e todas as suas dependências.

Sinopse

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

dotnet build -h|--help

Descrição

O dotnet build comando cria o projeto, a solução ou o aplicativo baseado em arquivo 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.
• 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 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

dotnet build usa o MSBuild para criar o projeto, a solução ou o aplicativo baseado em arquivo. Ele 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.

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

O projeto, a solução ou o arquivo C# (aplicativo baseado em arquivo) no qual operar. Se um arquivo não for especificado, o MSBuild pesquisa o diretório atual em busca de um projeto ou solução.

• PROJECT é o caminho e o nome do arquivo de um arquivo de projeto C#, F#ou Visual Basic ou o caminho para um diretório que contém um arquivo de projeto C#, F#ou Visual Basic.

• SOLUTION é o caminho e o nome do arquivo de um arquivo de solução (.sln ou extensão .slnx) ou o caminho para um diretório que contém um arquivo de solução.

• FILE é um argumento adicionado ao .NET 10. O caminho e o nome do arquivo de um aplicativo baseado em arquivo. Os aplicativos baseados em arquivo estão contidos em um único arquivo que é criado e executado sem um arquivo de projeto (.csproj) correspondente. Para obter mais informações, consulte Criar aplicativos C# baseados em 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.

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

  Equivalente a --self-contained false.

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

• --sc|--self-contained

  Publique o runtime do .NET com seu aplicativo para que o runtime não precise ser instalado no computador de destino. O padrão é true.

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

• --ucr|--use-current-runtime

  Use o runtime atual como o runtime de destino.

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

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

• -?|-h|--help

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

Exemplos

• Compile um projeto e suas dependências:

  dotnet build
  

• Crie um aplicativo baseado em arquivo:

  dotnet build MyProject.cs
  

  O suporte a aplicativos baseados em arquivo foi adicionado ao SDK do .NET 10.0.100.

• 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 -popção MSBuild:

  dotnet build -p:Version=1.2.3.4