Objetivos e destinos do MSBuild em um pacote

Artigo
12/22/2023

Além dos assemblies mais tradicionais, os pacotes NuGet às vezes podem adicionar destinos de compilação personalizados ou propriedades a projetos que consomem esse pacote. Isso pode ser obtido adicionando-se um arquivo MSBuild válido, no formato <package_id>.targets ou <package_id>.props (como Contoso.Utility.UsefulStuff.targets) dentro das pastas de compilação do projeto.

Pastas de compilação

À medida que o NuGet evoluiu, várias pastas diferentes para compilação .props e .targets foram adicionadas.

Pasta	Versão do NuGet	Usar
compilar	2.5+	Compile lógica para cada estrutura de um projeto.
buildMultiTargeting	4.0+	Compile lógica para o `outer build` para projetos que visam várias estruturas. Somente PackageReference.
buildTransitive	5.0+	Crie lógica para ativos que fluem transitivamente para qualquer projeto consumidor. Confira a página de recursos. Somente PackageReference.

Pasta de compilação específica da estrutura

Todas as 3 pastas de compilação seguem o mesmo padrão para decidir o arquivo mais adequado com base na estrutura de destino do projeto.

Arquivos na pasta de compilação raiz, build/<package_id>.targets e build/<package_id>.props são considerados adequados para todas as estruturas de destino.

Para fornecer arquivos específicos de estrutura, primeiro coloque-os em subpastas apropriadas, como os seguintes:

    \build
        \netstandard1.4
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets
        \net462
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets

Prefira usar pastas de compilação específicas da estrutura sempre que apropriado para evitar instalações de falsos positivos em projetos que podem não ser compatíveis com seu pacote.

Observe que se um pacote não tiver nenhum arquivo nas pastas lib ou ref e arquivos somente em uma pasta de compilação específica da estrutura, esse pacote será considerado compatível com todos os projetos. Versões atualizadas das ferramentas do pacote acionam o aviso NU5127 quando esses pacotes são criados.

Projetos consumindo pacotes com arquivos de compilação

Projetos PackageReference

.props e .targets não são adicionados ao projeto, mas são disponibilizados por meio de {projectName}.nuget.g.targets e {projectName}.nuget.g.props. Esses arquivos são gerados automaticamente quando a restauração é executada.

Quando um projeto tem como alvo mais de uma estrutura, as importações para esses arquivos são condicionadas ao nome da estrutura de destino.

Os arquivos .props e .targets do MSBuild podem ser colocados na pasta \buildMultiTargeting para direcionamento entre estruturas. Quando as importações são geradas, uma condição de que a propriedade $(TargetFramework) do MSBuild esteja vazia é definida.

Projetos packages.config

Quando o NuGet instala um pacote com arquivos \build, ele adiciona elementos <Import> do MSBuild ao arquivo de projeto que aponta para os arquivos .targets e .props. (.props é adicionado na parte superior do arquivo de projeto; .targets é adicionado na parte inferior.) Um elemento <Import> do MSBuild condicional separado é adicionado para cada estrutura de destino.

Criando pacotes com objetos e destinos do MSBuild

Você pode usar qualquer uma das seguintes ferramentas para incluir .props e .targets do MSBuild em seu pacote.

Orientação para o conteúdo de objetos e destinos do MSBuild

O NuGet não limita como você cria .props e .targets, pois eles irão variar de acordo com a necessidade do autor do pacote e dos projetos de destino em si.

Há algumas coisas que não devem ser feitas em .props e .targets de pacotes, como não especificar propriedades e itens que afetam a restauração, pois esses serão automaticamente excluídos.

Alguns exemplos de propriedades que não devem ser adicionadas ou atualizadas: TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker, AssetTargetFallback etc.
Alguns exemplos de itens que não devem ser adicionados ou atualizados: PackageReference, PackageVersion, PackageDownload, etc.