Personalizar seu build

  • Artigo

Os projetos do MSBuild que usam o processo de build padrão (importando Microsoft.Common.props e Microsoft.Common.targets) têm vários ganchos de extensibilidade que você pode usar para personalizar o processo de build.

Muitas operações de build personalizáveis são controladas por propriedades. É importante entender como e onde definir o valor de uma propriedade para obter o efeito pretendido. Você pode definir propriedades na linha de comando (e em arquivos de resposta), em arquivos especiais como Directory.Build.props, em arquivos importados ou no arquivo de projeto. É importante entender quando utilizar, definir ou alterar uma propriedade, bem como a sequência dos arquivos importados, incluindo importações implícitas de SDKs, como o SDK do .NET.

Para ver uma lista de propriedades, consulte Propriedades comuns do MSBuild.

Explorar as opções de personalização

As opções de personalização a seguir são listadas para aumentar a complexidade e o escopo de influência. Recomendamos que você utilize a opção de personalização menos complexa que atenda à sua finalidade, começando pelo topo desta lista.

Opção de personalização Descrição
Adicionar argumentos à linha de comando do MSBuild Defina propriedades globais que afetam o main build de projeto e builds de todos os projetos dependentes.
Personalizar o build para apenas um projeto Adicione propriedades a arquivos .props ou .targets para personalizar as configurações de build.
Manipular arquivos gerados no processo de build Como garantir que os arquivos gerados sejam incluídos corretamente na saída do build.
Personalizar o build para um ou mais projetos Adicione propriedades a Directory.Build.props ou adicione propriedades e destinos a Directory.Build.targets para personalizar o build para todos os projetos em uma pasta. Essa técnica é útil para definir propriedades definidas ou usadas por um SDK, bem como para definir o escopo de personalizações para que elas afetem todos os projetos em uma pasta ou subpasta.
Personalizar o build local Faça alterações no build apenas no computador local, sem afetar os arquivos de origem compartilhados.
Personalizar todos os builds do .NET Personalize o build, com escopo definido para todo o sistema, para builds do .NET.
Personalizar builds do C++ Personalize o build do C++, com escopo para um projeto, uma solução, uma pasta ou todos os builds regidos por uma instalação do MSBuild em um sistema.

Adicionar argumentos para invocações de linha de comando do MSBuild para o seu projeto

Você pode definir propriedades globais na linha de comando. Propriedades globais afetam todos os builds do projeto, incluindo dependências. Lembre-se de que compilar um projeto dispara automaticamente um possível build de todas as dependências do projeto. O comportamento normal do MSBuild é compilar todos os projetos dependentes desatualizados. Esses builds de projeto dependentes são iniciados com as mesmas configurações de propriedade globais da linha de comando que o projeto original.

Um arquivo Directory.Build.rsp no diretório de origem ou acima dele é aplicado aos builds de linha de comando do projeto. Para obter detalhes, confira Arquivos de resposta do MSBuild.

Escolha entre adicionar propriedades a um arquivo .props ou .targets.

O MSBuild depende da ordem de importação, e a última definição de uma propriedade (ou uma UsingTask ou um destino) é a definição usada.

Ao usar importações explícitas, você pode importar de um arquivo .props ou .targets a qualquer momento. Veja a seguir a convenção mais amplamente usada:

  • Os arquivos .props são importados no início na ordem de importação.

  • Os arquivos .targets são importados no final na ordem de compilação.

Essa convenção é imposta pelas importações <Project Sdk="SdkName"> (isto é, a importação de Sdk.props vem primeiro, antes de todos os conteúdos do arquivo, e Sdk.targets vem por último, depois de todos os conteúdos do arquivo).

Ao decidir onde colocar as propriedades, use as seguintes diretrizes gerais:

  • Para muitas propriedades, não importa onde elas são definidas porque elas não são substituídas e são lidas somente no tempo de execução.

  • Para o comportamento que pode ser personalizado em um projeto individual, defina padrões em arquivos .props.

  • Evite definir propriedades dependentes em arquivos .props, lendo o valor de uma propriedade possivelmente personalizada, pois a personalização não acontecerá até que MSBuild leia o projeto do usuário.

  • Defina propriedades dependentes em arquivos .targets, pois elas selecionarão as personalizações em projetos individuais.

  • Se você precisar substituir as propriedades, faça isso em um arquivo .targets, depois que todas as personalizações de projeto do usuário tiverem tido uma chance de entrar em vigor. Tenha cuidado ao usar propriedades derivadas, pois elas também podem precisar ser substituídas.

  • Inclua itens em arquivos .props (condicionados em uma propriedade). Todas as propriedades são consideradas antes de qualquer item, portanto, as personalizações de propriedades do projeto do usuário são captadas, e ter arquivos importados em arquivos .props oferece ao projeto do usuário a oportunidade de Remove ou Update qualquer item inserido pela importação.

  • Defina os destinos nos arquivos .targets. No entanto, se o arquivo .targets for importado por um SDK, lembre-se de que esse cenário torna a substituição do destino mais difícil porque o projeto do usuário não tem um lugar para substituí-lo por padrão.

  • Se possível, prefira propriedades de personalização no tempo de avaliação às propriedades de alteração dentro de um destino. Essa diretriz torna mais fácil carregar um projeto e entender o que ele está fazendo.

Conteúdo relacionado