Personalizar seu build

Este artigo fornece uma visão geral das opções de personalização de build e diretrizes sobre quando usar cada abordagem. As opções são apresentadas em ordem de complexidade, desde argumentos de linha de comando até personalizações em todo o sistema.

Pré-requisitos

• Familiaridade com a estrutura de arquivos de projeto do MSBuild (.csproj.vbprojou similar)
• Noções básicas sobre as propriedades e os alvos do MSBuild

Visão geral

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 seu processo de build.

Muitas operações de build personalizáveis são controladas por propriedades. É importante saber como e onde definir um valor de propriedade para ter o efeito desejado. 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 saber onde uma propriedade é usada, definida ou alterada e a ordem dos arquivos importados, incluindo importações implícitas de SDKs como o SDK do .NET.

Para obter uma lista de propriedades, consulte as propriedades comuns do MSBuild.

Explorar 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. É recomendável usar a opção de personalização menos complexa que atenda à sua finalidade, começando na parte superior desta lista.

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

Você pode definir propriedades globais na linha de comando. As propriedades globais afetam todas as compilações de projetos, incluindo dependências. Lembre-se de que a compilação de um projeto dispara automaticamente uma possível compilação para todas as dependências do projeto. O comportamento normal do MSBuild é criar projetos dependentes desatualizados. As compilações de projetos dependentes são executadas com as mesmas configurações de propriedades globais da linha de comando, assim como o projeto original.

Um arquivo Directory.Build.rsp dentro ou acima do diretório de origem é aplicado a compilações de linha de comando do seu projeto. Para obter detalhes, consulte os arquivos de resposta do MSBuild.

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

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

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

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

• .targets os arquivos são importados tardiamente na ordem de build.

Essa convenção é imposta por <Project Sdk="SdkName"> importações (ou seja, a importação de Sdk.props vem primeiro, antes de todo o conteúdo do arquivo, em seguida, Sdk.targets vem por último, depois de todo o conteúdo do arquivo).

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

• Para muitas propriedades, não importa onde elas são definidas, pois elas não são substituídas e são lidas apenas no momento da execução.

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

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

• Defina as propriedades dependentes nos arquivos .targets, pois elas absorvem personalizações de projetos individuais.

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

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

• Definir destinos em arquivos .targets. No entanto, se o .targets arquivo for importado por um SDK, lembre-se de que esse cenário dificulta a substituição do alvo porque o projeto do usuário não possui um local padrão para a substituição.

• Se possível, prefira personalizar propriedades no momento da avaliação, em vez de alterar as propriedades em um alvo. Essa diretriz facilita o carregamento de um projeto e a compreensão do que ele está fazendo.

Conteúdo relacionado

• Visão geral do processo de build
• Propriedades comuns do projeto MSBuild
• Arquivos de resposta do MSBuild
• Referência do MSBuild