Personaliza a tua build

Este artigo oferece uma visão geral das opções de personalização de builds e orientações sobre quando usar cada abordagem. As opções são apresentadas por ordem de complexidade, desde argumentos na linha de comandos até personalizações a nível de sistema.

Pré-requisitos

• Familiaridade com a estrutura de ficheiros do projeto MSBuild (.csproj, .vbproj, ou similar)
• Compreensão básica das propriedades e alvos do MSBuild

Visão geral

Os projetos MSBuild que utilizam o processo de compilação padrão (importação de Microsoft.Common.props e Microsoft.Common.targets) têm vários ganchos de extensibilidade que podes usar para personalizar o teu processo de compilação.

Muitas operações de construção personalizáveis são controladas por propriedades. É importante saber como e onde definir o valor de uma propriedade para obter o efeito desejado. Podes definir propriedades na linha de comandos (e nos ficheiros de resposta), em ficheiros especiais como Directory.Build.props, em ficheiros importados ou no ficheiro do projeto. É importante saber onde uma propriedade é usada, definida ou alterada e a ordem dos ficheiros importados, incluindo importações implícitas de SDKs como o SDK .NET.

Para uma lista de propriedades, veja Propriedades comuns do MSBuild.

Explore opções de personalização

As seguintes opções de personalização estão listadas por ordem de complexidade crescente e âmbito de influência. Recomendamos usar a opção de personalização menos complexa que sirva o seu propósito, começando pelo topo desta lista.

Adicione argumentos às invocações do MSBuild em linha de comandos para o seu projeto

Podes definir propriedades globais na linha de comandos. As propriedades globais afetam todas as construções de projetos, incluindo dependências. Lembre-se que compilar um projeto desencadeia automaticamente uma possível compilação das dependências do projeto. O comportamento normal do MSBuild é construir quaisquer projetos dependentes que estejam desatualizados. As builds dependentes do projeto são lançadas com as mesmas definições de propriedades globais na linha de comando que o projeto original.

Um ficheiro Directory.Build.rsp dentro ou acima do seu diretório de origem é aplicado às compilações de linha de comandos do seu projeto. Para mais detalhes, consulte ficheiros de resposta do MSBuild.

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

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

Ao usar importações explícitas, pode importar de um ficheiro .props ou de um ficheiro .targets em qualquer momento. Aqui está a convenção amplamente utilizada:

• .props os ficheiros são importados cedo na ordem de importação.

• .targets Os ficheiros são importados tarde na ordem de construção.

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

Ao decidir onde colocar as propriedades, utilize as seguintes orientações gerais:

• Para muitas propriedades, não importa onde estão definidas, porque não são sobrescrevidas e são lidas apenas no momento da execução.

• Para comportamentos que possam ser personalizados num projeto individual, defina os valores predefinidos nos .props ficheiros.

• Evite definir propriedades dependentes nos .props ficheiros lendo o valor de uma propriedade possivelmente personalizada, porque a personalização só acontece quando o MSBuild lê o projeto do utilizador.

• Defina propriedades dependentes nos .targets ficheiros, porque absorvem personalizações de projetos individuais.

• Se precisares de sobrescrever propriedades, faz-no num .targets ficheiro, depois de todas as personalizações do projeto de utilizador tiverem tido efeito. Tenha cautela ao utilizar propriedades derivadas; as propriedades derivadas podem também precisar de ser substituídas.

• Inclua itens em .props ficheiros (condicionados a uma propriedade). Todas as propriedades são consideradas antes de qualquer item, por isso as personalizações de propriedades do projeto do utilizador são reconhecidas, e ter ficheiros importados em .props dá ao projeto do utilizador a oportunidade de Remove ou Update para qualquer item trazido pela importação.

• Define alvos nos .targets ficheiros. No entanto, se o ficheiro .targets for importado por um SDK, lembre-se de que este cenário torna mais difícil substituir o alvo, dado que o projeto do utilizador não possui, por padrão, um local para efetuá-lo.

• Se possível, prefira personalizar propriedades na altura da avaliação em vez de mudar propriedades dentro de um alvo. Esta orientação facilita o carregamento de um projeto e a compreensão do que ele está a fazer.

Conteúdo relacionado

• Visão geral do processo de construção
• Propriedades comuns do projeto MSBuild
• Ficheiros de resposta MSBuild
• Referência do MSBuild