construção dotnet

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

Nome

dotnet build - Constrói 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

Description

O dotnet build comando constrói 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 . Dependendo do tipo de projeto e configurações, outros arquivos podem ser incluídos, como:

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

Para projetos executáveis destinados 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 a partir da pasta de pacotes globais do NuGet em tempo de execução. Com isso em mente, o produto de não está pronto para ser transferido dotnet build para outra máquina para funcionar. Para criar uma versão do aplicativo que pode ser implantada, você precisa publicá-la (por exemplo, com o comando dotnet publishing ). Para obter mais informações, consulte Implantação de aplicativos .NET.

Para projetos executáveis destinados ao .NET Core 3.0 e posterior, 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 da Web), a saída da compilação deve ser implantável.

Restauração implícita

A criação requer 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 no lugar, as ferramentas não podem resolver assemblies de referência, o que resulta em erros.

Você não precisa executar dotnet restore porque ele é executado implicitamente por todos os comandos que exigem uma restauração para ocorrer, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publishe dotnet pack. Para desativar a restauração implícita, use a --no-restore opção.

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

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

Este comando suporta as dotnet restore opções quando passado na forma longa (por exemplo, --source). Opções de formulário curto, como -s, não são suportadas.

Saída executável ou de biblioteca

Se o projeto é executável ou não é determinado pela <OutputType> propriedade no arquivo de projeto. O exemplo a seguir mostra um projeto que produz código executável:

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

Para produzir uma biblioteca, omita a <OutputType> propriedade ou altere seu valor para Library. A DLL IL para 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, portanto, ele suporta compilações paralelas e incrementais. Para obter mais informações, consulte Compilações incrementais.

Além de suas opções, o comando aceita opções do dotnet build MSBuild, como -p para definir propriedades ou -l para definir um registrador. Para obter mais informações sobre essas opções, consulte a referência de linha de comando do MSBuild. Ou você também pode usar o comando dotnet msbuild .

Nota

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 verbosidade padrão da 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 este comando terminar, o download será interrompido. Para obter mais informações, consulte Manifestos de publicidade.

Argumentos

PROJECT | SOLUTION

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

Opções

• -a|--arch <ARCHITECTURE>

  Especifica a arquitetura de destino. Esta é uma sintaxe abreviada para definir o Runtime Identifier (RID), onde o valor fornecido é combinado com o RID padrão. Por exemplo, em uma win-x64 máquina, especificar --arch x86 define o RID como win-x86. Se você usar essa opção, não use a -r|--runtime opção. Disponível desde o .NET 6 Preview 7.

• --artifacts-path <ARTIFACTS_DIR>

  Todos os arquivos de saída de compilação do comando executado irão em subpastas sob o 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 de compilação. O padrão para a maioria dos projetos é Debug, mas você pode substituir as definições de configuração de compilação em seu projeto.

• --disable-build-servers

  Força o comando a ignorar quaisquer servidores de compilação persistentes. Essa opção fornece uma maneira consistente de desabilitar 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 .NET 7 SDK.

• -f|--framework <FRAMEWORK>

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

• --force

  Força todas as dependências a serem resolvidas, mesmo que a última restauração tenha sido bem-sucedida. Especificar esse sinalizador é o mesmo que excluir o arquivo project.assets.json .

• -?|-h|--help

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

• --interactive

  Permite que o comando pare e aguarde a 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 referências de projeto a projeto (P2P) e cria apenas o projeto raiz especificado.

• --no-incremental

  Marca a compilação como insegura para compilação incremental. Esse sinalizador desativa a compilação incremental e força uma reconstrução limpa do gráfico de dependência do projeto.

• --no-restore

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

• --nologo

  Não exibe o banner de inicialização ou a mensagem de direitos autorais.

• --no-self-contained

  Publica o aplicativo como um aplicativo dependente da estrutura. Um tempo de execução .NET compatível deve ser instalado na máquina de destino para executar o aplicativo. Disponível desde o SDK do .NET 6.

• -o|--output <OUTPUT_DIRECTORY>

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

  • SDK do .NET 7.0.200 e posterior

    Se você especificar a --output opção 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 --output opção não é permitida porque todas as saídas de todos os projetos construídos seriam copiadas para o diretório especificado, que não é compatível com projetos com vários destinos, bem como projetos que têm diferentes versões de dependências diretas e transitivas. Para obter mais informações, consulte A opção de nível --output de solução não é mais válida para comandos relacionados à compilação.

• --os <OS>

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

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

  Define uma ou mais propriedades do 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 tempo de execução de destino. Para obter uma lista de identificadores de tempo de execução (RIDs), consulte o catálogo RID. 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 é compilar para o sistema operacional e a arquitetura atuais.

• --self-contained [true|false]

  Publica o tempo de execução do .NET com o aplicativo para que o tempo de execução não precise ser instalado na máquina de destino. O padrão é true se um identificador de tempo de execução for especificado. Disponível desde .NET 6.

• --source <SOURCE>

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

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

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

  O registrador de terminal mostra a fase de restauração seguida pela fase de compilação. Durante cada fase, os projetos atualmente em construção aparecem na parte inferior do terminal. Cada projeto que está construindo produz tanto a meta do MSBuild que está sendo criada quanto a quantidade de tempo gasto nessa meta. Você pode pesquisar essas informações para saber mais sobre a compilação. Quando um projeto termina de construir, uma única seção "construção concluída" é escrita que captura:

  • O nome do projeto construído.
  • A estrutura de destino (se multidirecionada).
  • O status dessa compilação.
  • A saída primária dessa compilação (que é hiperligada).
  • Qualquer diagnóstico gerado para esse projeto.

  Esta opção está disponível a partir do .NET 8.

• -v|--verbosity <LEVEL>

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

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

  Define o RuntimeIdentifier para uma plataforma portátil RuntimeIdentifier com base na da sua máquina. Isso acontece implicitamente com propriedades que exigem um RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFilee PublishReadyToRun. Se a propriedade estiver definida como false, essa resolução implícita não ocorrerá mais.

• --version-suffix <VERSION_SUFFIX>

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

Exemplos

• Crie um projeto e suas dependências:

  dotnet build
  

• Crie um projeto e suas dependências usando a configuração de versão:

  dotnet build --configuration Release
  

• Crie um projeto e suas dependências para um tempo de execução específico (neste exemplo, Linux):

  dotnet build --runtime linux-x64
  

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

  dotnet build --source c:\packages\mypackages
  

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

  dotnet build -p:Version=1.2.3.4