.props y .targets de MSBuild en un paquete

Artículo
12/22/2023

Además de los ensamblados más tradicionales, a veces los paquetes NuGet pueden agregar propiedades o destinos de compilación personalizados a proyectos que consumen ese paquete. Esto se puede lograr agregando un archivo de MSBuild válido, en el formulario <package_id>.targets o <package_id>.props (como Contoso.Utility.UsefulStuff.targets) dentro de las carpetas de compilación del proyecto.

Carpetas de compilación

A medida que NuGet ha ido evolucionando, se han agregado varias carpetas diferentes para compilación .props y .targets.

Carpeta	Versión de NuGet	Usar
build	2.5+	Lógica de compilación para cada marco de un proyecto.
buildMultiTargeting	4.0+	Cree lógica para `outer build` para los proyectos que tienen como destino varias plataformas. Únicamente PackageReference.
buildTransitive	5.0+	Cree lógica para los recursos que fluyen de manera transitiva a cualquier proyecto de consumo. Vea la página de la característica. Únicamente PackageReference.

Carpeta de compilación específica del marco

Las tres carpetas de compilación siguen el mismo patrón para determinar el archivo más adecuado en función de la plataforma de destino del proyecto.

Los archivos de la carpeta de compilación raíz, build/<package_id>.targets y build/<package_id>.props se consideran adecuados para todos los marcos de destino.

Para proporcionar archivos específicos de la plataforma, colóquelos primero en las subcarpetas adecuadas, como las siguientes:

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

Opte por usar carpetas de compilación específicas del marco siempre que sea pertinente para evitar instalaciones con carácter falso positivo en proyectos que no sean compatibles con el paquete.

Tenga en cuenta que si un paquete no tiene ningún archivo en las carpetas lib o ref y solo archivos en una carpeta de compilación específica del marco, ese paquete se considerará compatible con todos los proyectos. Las versiones actualizadas de las herramientas de paquete generan la advertencia NU5127 cuando se crean estos paquetes.

Proyectos que consumen paquetes con archivos de compilación

Proyectos de PackageReference

.props y .targets no se agregan al archivo del proyecto pero en su lugar se ponen a disposición a través de {projectName}.nuget.g.targets y {projectName}.nuget.g.props. Estos archivos se generan automáticamente al ejecutar la restauración.

Cuando un proyecto tiene como destino más de un marco, las importaciones a estos archivos están condicionadas respecto al nombre de la plataforma de destino.

Los archivos .props y .targets de MSBuild de los destinos multiplataforma pueden colocarse en la carpeta \buildMultiTargeting. Cuando se generan las importaciones, se establece una condición en la que está vacía la propiedad $(TargetFramework) de MSBuild.

Proyectos de packages.config

Cuando NuGet instala un paquete con archivos \build, agrega elementos <Import> de MSBuild al archivo de proyecto que apunta a los archivos .targets y .props. (.props se agrega en la parte superior del archivo del proyecto; .targets se agrega en la parte inferior). Se agrega un elemento <Import> de MSBuild condicional independiente para cada plataforma de destino.

Creación de paquetes con propiedades y destinos de MSBuild

Puede usar cualquiera de las siguientes herramientas para incluir MSBuild .props y .targets en el paquete.

Guía para el contenido de las propiedades y destinos de MSBuild

NuGet no limita la forma en que cree .props y .targets, ya que variarán en función de las necesidades del autor del paquete y de los propios proyectos de destino.

Hay algunas cosas que conviene evitar en .props y .targets de los paquetes, tales como no especificar propiedades y elementos que afectan a la restauración, ya que se excluirán automáticamente.

Estos son algunos ejemplos de propiedades que no se deben agregar ni actualizar: TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker, AssetTargetFallback, etc.
Estos son algunos ejemplos de elementos que no se deben agregar ni actualizar: PackageReference, PackageVersion, PackageDownload, etc.