Paquete y restauración de NuGet como destinos de MSBuild

  • Artículo

NuGet 4.0 y versiones posteriores

Con el formato PackageReference, NuGet 4.0 y las versiones posteriores pueden almacenar los metadatos de todos los manifiestos directamente en un archivo de proyecto, en lugar de usar un archivo .nuspec independiente.

Con MSBuild 15.1 y versiones posteriores, NuGet es también un ciudadano de MSBuild de primera clase con los destinos pack y restore como se describe a continuación. Estos destinos permiten trabajar con NuGet como lo haría con cualquier otra tarea o destino de MSBuild. Para obtener instrucciones sobre cómo crear un paquete NuGet mediante MSBuild, consulte Creación de un paquete NuGet mediante MSBuild. (Para NuGet 3.x y versiones anteriores, los comandos pack y restore se usan a través de la CLI de NuGet en su lugar).

Orden de compilación de destinos

Dado que pack y restore son destinos de MSBuild, puede tener acceso a ellos para mejorar el flujo de trabajo. Por ejemplo, supongamos que quiere copiar el paquete en un recurso compartido de red después de empaquetarlo. Puede hacer esto si agrega lo siguiente al archivo de proyecto:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

De forma similar, puede escribir una tarea de MSBuild, su propio destino y usar propiedades de NuGet en la tarea de MSBuild.

Nota:

$(OutputPath) es relativo y espera que ejecute el comando desde la raíz del proyecto.

Destino de pack

En el caso de los proyectos de .NET que usan el formato PackageReference, el uso de msbuild -t:pack extrae entradas del archivo de proyecto para usarlas en la creación de un paquete NuGet.

En la tabla siguiente se describen las propiedades de MSBuild que se pueden agregar a un archivo de proyecto en el primer nodo <PropertyGroup>. Puede realizar estas modificaciones fácilmente en Visual Studio 2017 y después haciendo clic con el botón derecho en el proyecto y seleccionando Editar {nombre_proyecto} en el menú contextual. Para mayor comodidad, la tabla se organiza por la propiedad equivalente en un archivo .nuspec.

Nota:

Tenga en cuenta que las propiedades Owners y Summary de .nuspec no son compatibles con MSBuild.

Atributo/valor nuspec PropiedadMSBuild Valor predeterminado Notas
Id PackageId $(AssemblyName) $(AssemblyName) de MSBuild
Version PackageVersion Versión Esto es compatible con semver, por ejemplo 1.0.0, 1.0.0-beta o 1.0.0-beta-00345. Si no se establece, el valor predeterminado es Version.
VersionPrefix VersionPrefix empty La configuración PackageVersion sobrescribe VersionPrefix
VersionSuffix VersionSuffix empty La configuración PackageVersion sobrescribe VersionSuffix
Authors Authors Nombre del usuario actual Lista separada por puntos y comas de autores de paquetes que coinciden con los nombres de perfil de nuget.org. Se muestran en la Galería de NuGet en nuget.org y se usan para realizar referencias cruzadas a paquetes de los mismos autores.
Owners N/D No está presente en nuspec
Title Title $(PackageId) Un título fácil de usar del paquete, que se usa normalmente en las visualizaciones de la interfaz de usuario, como en nuget.org, y el Administrador de paquetes de Visual Studio.
Description Description "Descripción del paquete" Una descripción larga del ensamblado. Si PackageDescription no se especifica, esta propiedad también se utiliza como la descripción del paquete.
Copyright Copyright empty Detalles de copyright del paquete.
RequireLicenseAcceptance PackageRequireLicenseAcceptance false Un valor booleano que especifica si el cliente debe pedir al consumidor que acepte la licencia del paquete antes de instalarlo.
license PackageLicenseExpression empty Se corresponde con <license type="expression">. Consulte Empaquetado de una expresión de licencia o un archivo de licencia.
license PackageLicenseFile empty Ruta de acceso a un archivo de licencia dentro del paquete si usa una licencia personalizada o una licencia que no tiene asignado un identificador SPDX. Debe empaquetar explícitamente el archivo de licencia al que se hace referencia. Se corresponde con <license type="file">. Consulte Empaquetado de una expresión de licencia o un archivo de licencia.
LicenseUrl PackageLicenseUrl empty PackageLicenseUrl está en desuso. Use PackageLicenseExpression o PackageLicenseFile en su lugar.
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty Ruta de acceso a una imagen del paquete que se va a usar como icono del paquete. Debe empaquetar explícitamente el archivo de imagen de icono al que se hace referencia. Para obtener más información, consulte Empaquetado de un archivo de imagen de icono y Metadatos de icon.
IconUrl PackageIconUrl empty Se ha dejado de usar PackageIconUrl en favor de PackageIcon. Sin embargo, para obtener la mejor experiencia de nivel inferior, debe especificar PackageIconUrl, además de PackageIcon.
Readme PackageReadmeFile empty Debe empaquetar explícitamente el archivo Léame al que se hace referencia.
Tags PackageTags empty Una lista de etiquetas delimitada por punto y coma que designa el paquete.
ReleaseNotes PackageReleaseNotes empty Notas de la versión para el paquete.
Repository/Url RepositoryUrl empty Dirección URL del repositorio usada para clonar o recuperar código fuente. Ejemplo: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
Repository/Type RepositoryType empty Tipo de repositorio. Ejemplos: git (valor predeterminado), tfs.
Repository/Branch RepositoryBranch empty Información opcional de la rama del repositorio. RepositoryUrl también se debe especificar para que esta propiedad se incluya. Ejemplo: master (NuGet 4.7.0 y versiones posteriores).
Repository/Commit RepositoryCommit empty Confirmación o conjunto de cambios opcionales de repositorio para indicar en qué origen se ha compilado el paquete. RepositoryUrl también se debe especificar para que esta propiedad se incluya. Ejemplo: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0 y versiones posteriores).
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> Indica el uso previsto del paquete. Los tipos de paquete usan el mismo formato que los id. de paquete y se delimitan por ;. Los tipos de paquete se pueden versionar anexando una cadena , y Version. Consulte Establecimiento de un tipo de paquete NuGet (NuGet 3.5.0 y versiones posteriores).
Summary No compatible

Entradas de destino de pack

Propiedad Descripción
IsPackable Un valor booleano que especifica si se puede empaquetar el proyecto. El valor predeterminado es true.
SuppressDependenciesWhenPacking Establézcalo en true para suprimir las dependencias del paquete NuGet generado.
PackageVersion Especifica la versión que tendrá el paquete resultante. Acepta todos los formatos de la cadena de versión de NuGet. El valor predeterminado es $(Version), es decir, de la propiedad Version del proyecto.
PackageId Especifica el nombre para el paquete resultante. Si no se especifica, la operación pack usará de forma predeterminada el elemento AssemblyName o el nombre del directorio como el nombre del paquete.
PackageDescription Una descripción larga del paquete para su visualización en la interfaz de usuario.
Authors Lista separada por puntos y comas de autores de paquetes que coinciden con los nombres de perfil de nuget.org. Se muestran en la Galería de NuGet en nuget.org y se usan para realizar referencias cruzadas a paquetes de los mismos autores.
Description Una descripción larga del ensamblado. Si PackageDescription no se especifica, esta propiedad también se utiliza como la descripción del paquete.
Copyright Detalles de copyright del paquete.
PackageRequireLicenseAcceptance Un valor booleano que especifica si el cliente debe pedir al consumidor que acepte la licencia del paquete antes de instalarlo. El valor predeterminado es false.
DevelopmentDependency Valor booleano que especifica si el paquete se debe marcar como una dependencia de solo desarrollo, que impide que el paquete se incluya como una dependencia en otros paquetes. Con PackageReference (NuGet 4.8 y versiones posteriores), esta marca también significa que se excluirán los recursos en tiempo de compilación de la compilación. Para más información, consulte Compatibilidad de DevelopmentDependency para PackageReference.
PackageLicenseExpression Identificador de licencia SPDX o expresión, por ejemplo, Apache-2.0. Para obtener más información, consulte Empaquetado de una expresión de licencia o un archivo de licencia.
PackageLicenseFile Ruta de acceso a un archivo de licencia dentro del paquete si usa una licencia personalizada o una licencia que no tiene asignado un identificador SPDX.
PackageLicenseUrl PackageLicenseUrl está en desuso. Use PackageLicenseExpression o PackageLicenseFile en su lugar.
PackageProjectUrl
PackageIcon Especifica la ruta de acceso del icono del paquete, en relación con la raíz del paquete. Para obtener más información, consulte Empaquetado de un archivo de imagen del icono.
PackageReleaseNotes Notas de la versión para el paquete.
PackageReadmeFile Léame del paquete.
PackageTags Una lista de etiquetas delimitada por punto y coma que designa el paquete.
PackageOutputPath Determina la ruta de acceso de salida en la que se va a quitar el paquete empaquetado. El valor predeterminado es $(OutputPath).
IncludeSymbols Este valor booleano indica si el paquete debe crear un paquete de símbolos adicionales cuando se empaqueta el proyecto. El formato del paquete de símbolos se controla mediante la propiedad SymbolPackageFormat. Para obtener más información, vea IncludeSymbols.
IncludeSource Este valor booleano indica si el proceso de empaquetado debe crear un paquete de origen. El paquete de origen contiene el código fuente de la biblioteca, así como archivos PDB. Los archivos de origen se colocan en el directorio src/ProjectName, en el archivo de paquete resultante. Para obtener más información, vea IncludeSource.
PackageType
IsTool Especifica si se copian todos los archivos de salida en la carpeta tools en lugar de la carpeta lib. Para obtener más información, vea IsTool.
RepositoryUrl Dirección URL del repositorio usada para clonar o recuperar código fuente. Ejemplo: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
RepositoryType Tipo de repositorio. Ejemplos: git (valor predeterminado), tfs.
RepositoryBranch Información opcional de la rama del repositorio. RepositoryUrl también se debe especificar para que esta propiedad se incluya. Ejemplo: master (NuGet 4.7.0 y versiones posteriores).
RepositoryCommit Confirmación o conjunto de cambios opcionales de repositorio para indicar en qué origen se ha compilado el paquete. RepositoryUrl también se debe especificar para que esta propiedad se incluya. Ejemplo: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0 y versiones posteriores).
SymbolPackageFormat Especifica el formato del paquete de símbolos. Si es "symbols.nupkg", se crea un paquete de símbolos heredado con una extensión .symbols.nupkg que contiene archivos PDB, DLL y otros archivos de salida. Si es "snupkg", se crea un paquete de símbolos snupkg que contiene los archivos PDB portátiles. El valor predeterminado es "symbols.nupkg".
NoPackageAnalysis Especifica que pack no debe ejecutar el análisis de paquetes después de crear el paquete.
MinClientVersion Especifica la versión mínima del cliente de NuGet que puede instalar este paquete, aplicada por nuget.exe y el Administrador de paquetes de Visual Studio.
IncludeBuildOutput Este valor booleano especifica si se deben empaquetar los ensamblados de salida de la compilación en el archivo .nupkg o no.
IncludeContentInPack Este valor booleano especifica si los elementos del tipo Content se incluirán automáticamente en el paquete resultante. El valor predeterminado es true.
BuildOutputTargetFolder Especifica la carpeta en la que se colocarán los ensamblados de salida. Los ensamblados de salida (y otros archivos de salida) se copian en sus respectivas carpetas de marco. Para obtener más información, vea Ensamblados de salida.
ContentTargetFolders Especifica la ubicación predeterminada a la que deben ir todos los archivos de contenido si no se especifica PackagePath para ellos. El valor predeterminado es “content;contentFiles”. Para obtener más información, consulte Including content in a package (Incluir contenido en un paquete).
NuspecFile Ruta de acceso relativa o absoluta al archivo .nuspec que se usa para el empaquetado. Si se especifica, se usa exclusivamente para la información de empaquetado y no se usa ninguna de la información de los proyectos. Para obtener más información, vea Empaquetado con un archivo .nuspec.
NuspecBasePath Ruta de acceso base para el archivo .nuspec. Para obtener más información, vea Empaquetado con un archivo .nuspec.
NuspecProperties Lista separada por punto y coma de pares clave=valor. Para obtener más información, vea Empaquetado con un archivo .nuspec.

Escenarios de pack

Supresión de dependencias

Para suprimir las dependencias de paquetes del paquete NuGet generado, establezca SuppressDependenciesWhenPacking en true, que permitirá omitir todas las dependencias del archivo nupkg generado.

PackageIconUrl

PackageIconUrl está en desuso en favor de la propiedad PackageIcon. A partir de NuGet 5.3 y Visual Studio 2019 versión 16.3, pack genera la advertencia NU5048 si los metadatos del paquete solo especifican PackageIconUrl.

PackageIcon

Sugerencia

Para mantener la compatibilidad con versiones anteriores con clientes y orígenes que aún no admiten PackageIcon, especifique PackageIcon y PackageIconUrl. Visual Studio admite PackageIcon para paquetes procedentes de un origen basado en carpetas.

Empaquetado de un archivo de imagen del icono

Al empaquetar un archivo de imagen del icono, use la propiedad PackageIcon para especificar la ruta de acceso del archivo de icono relativa a la raíz del paquete. Además, debe asegurarse de que el archivo se incluya en el paquete. El tamaño del archivo de imagen está limitado a 1 MB. Entre los formatos de archivos admitidos se incluyen JPEG y PNG. Se recomienda una resolución de imagen de 128x128.

Por ejemplo:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Ejemplo de icono de paquete.

Para obtener el archivo nuspec equivalente, eche un vistazo a la referencia de nuspec del icono.

PackageReadmeFile

Compatible con la versión preliminar 2 de NuGet 5.10.0 / .NET SDK 5.0.300 y versiones posteriores

Al empaquetar un archivo Léame, debe usar la propiedad PackageReadmeFile para especificar la ruta de acceso del paquete relativa a la raíz del paquete. Además de esto, debe asegurarse de que el archivo se incluya en el paquete. Los formatos de archivo admitidos incluyen solo Markdown (.md).

Por ejemplo:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Para obtener el archivo nuspec equivalente, eche un vistazo a la referencia de nuspec del archivo Léame.

Ensamblados de salida

nuget pack copia los archivos de salida con las extensiones .exe, .dll, .xml, .winmd, .json y .pri. Los archivos de salida que se copian dependen de lo que proporciona MSBuild desde el destino BuiltOutputProjectGroup.

Hay dos propiedades de MSBuild que se pueden usar en el archivo de proyecto o la línea de comandos para controlar dónde van los ensamblados de salida:

  • IncludeBuildOutput: un valor booleano que determina si los ensamblados de salida de compilación deben incluirse en el paquete.
  • BuildOutputTargetFolder: especifica la carpeta en la que se deben colocar los ensamblados de salida. Los ensamblados de salida (y otros archivos de salida) se copian en sus respectivas carpetas de marco.

Referencias de paquete

Vea Referencias de paquete en archivos de proyecto.

Referencias entre proyectos

Las referencias entre proyectos se consideran de manera predeterminada como referencias de paquetes NuGet. Por ejemplo:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

También puede agregar los metadatos siguientes a la referencia de proyecto:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Inclusión de contenido en un paquete

Para incluir contenido, agregue metadatos adicionales al elemento <Content> existente. De forma predeterminada todos los elementos de tipo "Content" se incluyen en el paquete a menos que los reemplace con entradas como la siguiente:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

De forma predeterminada, todo el contenido se agrega a la raíz de la carpeta content y contentFiles\any\<target_framework> dentro de un paquete y se conserva la estructura de carpetas relativa, a menos que se especifique una ruta de acceso de paquete:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

Si quiere copiar todo el contenido a una carpeta raíz determinada (en lugar de content y contentFiles), puede usar la propiedad MSBuild de ContentTargetFolders, cuyo valor predeterminado es "content;contentFiles", pero que se puede establecer en cualquier otro nombre de carpeta. Tenga en cuenta que si solo especifica "contentFiles" en ContentTargetFolders, los archivos se colocan en contentFiles\any\<target_framework> o contentFiles\<language>\<target_framework> en función de buildAction.

PackagePath puede ser un conjunto de rutas de acceso de destino delimitadas por punto y coma. Especificar una ruta de acceso de paquete vacía agregaría el archivo a la raíz del paquete. Por ejemplo, en el ejemplo siguiente se agrega libuv.txt a content\myfiles, content\samples y la raíz del paquete:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

También hay una propiedad MSBuild de $(IncludeContentInPack), cuyo valor predeterminado es true. Si esto se establece en false en cualquier proyecto, el contenido de ese proyecto no se incluye en el paquete NuGet.

Otros metadatos específicos del paquete que se pueden establecer en cualquiera de los elementos anteriores incluyen <PackageCopyToOutput> y <PackageFlatten>, que establece los valores CopyToOutput y Flatten en la entrada contentFiles del archivo nuspec de salida.

Nota:

Además de los elementos Content, los metadatos <Pack> y <PackagePath> también se pueden establecer en archivos con una acción de compilación Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreatableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource o None.

Para que el comando pack anexe el nombre de archivo a la ruta de acceso del paquete cuando se usan patrones globales, la ruta de acceso del paquete debe terminar con el carácter separador de carpeta; en caso contrario, la ruta de acceso del paquete se trata como la ruta de acceso completa, incluido el nombre de archivo.

IncludeSymbols

Cuando se usa MSBuild -t:pack -p:IncludeSymbols=true, se copian los archivos .pdb correspondientes junto con otros archivos de salida (.dll, .exe, .winmd, .xml, .json, .pri). Tenga en cuenta que al establecer IncludeSymbols=true se crea un paquete estándar y un paquete de símbolos.

IncludeSource

Esto equivale a IncludeSymbols, salvo que también copia los archivos de código fuente junto con los archivos .pdb. Todos los archivos de tipo Compile se copian en src\<ProjectName>\ conservando la estructura de carpetas de ruta de acceso relativa en el paquete resultante. Lo mismo sucede para los archivos de código fuente de cualquier ProjectReference en la que TreatAsPackageReference se establece en false.

Si un archivo de tipo Compile está fuera de la carpeta de proyecto, simplemente se agrega a src\<ProjectName>\.

Empaquetado de una expresión de licencia o un archivo de licencia

Al usar una expresión de licencia, use la propiedad PackageLicenseExpression. Para obtener un ejemplo, consulte Ejemplo de expresión de licencia.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Para obtener más información sobre las expresiones de licencia y las licencias aceptadas por NuGet.org, consulte metadatos de licencia.

Al empaquetar un archivo de licencia, use la propiedad PackageLicenseFile para especificar la ruta de acceso del paquete relativa a la raíz del paquete. Además, debe asegurarse de que el archivo se incluya en el paquete. Por ejemplo:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

Para obtener un ejemplo, consulte Ejemplo de archivo de licencia.

Nota:

Solo se puede especificar uno de estos elementos cada vez: PackageLicenseExpression, PackageLicenseFile o PackageLicenseUrl.

Empaquetado de un archivo sin una extensión

En algunos escenarios, como al empaquetar un archivo de licencia, es posible que desee incluir un archivo sin una extensión. Por razones históricas, NuGet y MSBuild tratan las rutas de acceso sin extensión como directorios.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>

Archivo sin un ejemplo de extensión.

IsTool

Cuando se usa MSBuild -t:pack -p:IsTool=true, todos los archivos de salida, como se especifica en el escenario Ensamblados de salida, se copian en la carpeta tools en lugar de la carpeta lib. Tenga en cuenta que esto es diferente de DotNetCliTool, que se especifica estableciendo PackageType en el archivo .csproj.

Empaquetado mediante un archivo .nuspec

Aunque se recomienda incluir todas las propiedades que normalmente están en el archivo .nuspec del archivo del proyecto, en su lugar, puede optar por usar un archivo .nuspec para empaquetar el proyecto. Para un proyecto que no sea de estilo SDK que use PackageReference, debe importar NuGet.Build.Tasks.Pack.targets para que se pueda ejecutar la tarea de paquete. Todavía tiene que restaurar el proyecto antes de empaquetar un archivo nuspec. (Un proyecto de estilo SDK incluye los destinos del paquete de manera predeterminada).

La plataforma de destino del archivo de proyecto es irrelevante y no se usa al empaquetar un archivo nuspec. Las tres propiedades de MSBuild siguientes son relevantes para el empaquetado mediante un archivo .nuspec:

  1. NuspecFile: ruta de acceso relativa o absoluta al archivo .nuspec que se usa para el empaquetado.
  2. NuspecProperties: lista de pares clave=valor separados por punto y coma. Debido al funcionamiento del análisis de línea de comandos de MSBuild, se deben especificar varias propiedades como se indica a continuación: -p:NuspecProperties="key1=value1;key2=value2".
  3. NuspecBasePath: ruta de acceso base para el archivo .nuspec.

Si se usa dotnet.exe para empaquetar el proyecto, use un comando similar al siguiente:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

Si se usa MSBuild para empaquetar el proyecto, use un comando similar al siguiente:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

Tenga en cuenta que el empaquetado de un archivo nuspec mediante dotnet.exe o msbuild también conduce a la compilación del proyecto de manera predeterminada. Esto se puede evitar pasando la propiedad --no-build a dotnet.exe, que es el equivalente de establecer <NoBuild>true</NoBuild> en el archivo de proyecto, junto con la configuración <IncludeBuildOutput>false</IncludeBuildOutput> en el archivo del proyecto.

Un ejemplo de un archivo .csproj para empaquetar un archivo nuspec es:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Puntos de extensión avanzados para crear un paquete personalizado

El destino pack proporciona dos puntos de extensión que se ejecutan en la compilación específica de la plataforma de destino interna. Los puntos de extensión admiten el contenido específico de la plataforma de destino y los ensamblados en un paquete:

  • Destino TargetsForTfmSpecificBuildOutput: úselo para los archivos dentro de la carpeta lib o una carpeta especificada mediante BuildOutputTargetFolder.
  • Destino TargetsForTfmSpecificContentInPackage: úselo para los archivos fuera de BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Escriba un destino personalizado y especifíquelo como valor de la propiedad $(TargetsForTfmSpecificBuildOutput). Para los archivos que necesiten entrar en BuildOutputTargetFolder (lib de manera predeterminada), el destino debe escribir esos archivos en el ItemGroup BuildOutputInPackage y establecer los dos valores de metadatos siguientes:

  • FinalOutputPath: ruta de acceso absoluta del archivo; si no se proporciona, la identidad se usa para evaluar la ruta de acceso de origen.
  • TargetPath: (opcional) establezca esta opción cuando el archivo necesite ir a una subcarpeta dentro de lib\<TargetFramework>, como los ensamblados satélite que se encuentran en sus respectivas carpetas de referencia cultural. El valor predeterminado es el nombre del archivo.

Ejemplo:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Escriba un destino personalizado y especifíquelo como valor de la propiedad $(TargetsForTfmSpecificContentInPackage). Para que los archivos se incluyan en el paquete, el destino debe escribir esos archivos en el ItemGroup TfmSpecificPackageFile y establecer los metadatos opcionales siguientes:

  • PackagePath: ruta de acceso donde se debe generar el archivo en el paquete. NuGet emite una advertencia si se agrega más de un archivo a la misma ruta de acceso del paquete.
  • BuildAction: acción de compilación que se va a asignar al archivo; solo es necesaria si la ruta de acceso del paquete está en la carpeta contentFiles. El valor predeterminado es "None".

Un ejemplo:

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>

Destino de restore

MSBuild -t:restore (que nuget restore y dotnet restore usan con proyectos de .NET Core), restaura los paquetes a los que se hace referencia en el archivo de proyecto como se indica a continuación:

  1. Leer todas las referencias entre proyectos
  2. Leer las propiedades del proyecto para buscar las carpetas y plataformas de destino intermedias
  3. Traslado de los datos de MSBuild a NuGet.Build.Tasks.dll
  4. Ejecutar la restauración
  5. Descarga de paquetes
  6. Escribir el archivo de activos, destinos y propiedades

El destino restore funciona para proyectos con el formato PackageReference. MSBuild 16.5+ también tiene compatibilidad con la participación para el formato packages.config.

Nota:

El destino restoreno se debe ejecutar en combinación con el destino build.

Restaurar las propiedades

Otra configuración de restauración puede proceder de propiedades de MSBuild en el archivo de proyecto. También se pueden establecer valores desde la línea de comandos mediante el modificador -p: (vea los ejemplos siguientes).

Propiedad Descripción
RestoreSources Lista delimitada por punto y coma de orígenes de paquetes.
RestorePackagesPath Ruta de acceso de la carpeta de paquetes de usuario.
RestoreDisableParallel Limitar las descargas a una cada vez.
RestoreConfigFile Ruta de acceso a un archivo Nuget.Config que se va a aplicar.
RestoreNoHttpCache Si es true, evita el uso de paquetes almacenados en caché http. Consulte Administración de paquetes globales y carpetas de caché.
RestoreIgnoreFailedSources Si es true, ignora los orígenes de paquetes que producen errores o faltan.
RestoreFallbackFolders Carpetas de reserva, que se usan de la misma manera que se usa la carpeta de paquetes de usuario.
RestoreAdditionalProjectSources Orígenes adicionales que se usarán durante la restauración.
RestoreAdditionalProjectFallbackFolders Carpetas de reserva adicionales que se usarán durante la restauración.
RestoreAdditionalProjectFallbackFoldersExcludes Excluye las carpetas de reserva especificadas en RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFile Ruta de acceso a NuGet.Build.Tasks.dll.
RestoreGraphProjectInput Lista delimitada por punto y coma de proyectos para restaurar, que debe contener rutas de acceso absolutas.
RestoreUseSkipNonexistentTargets Cuando los proyectos se recopilan a través de MSBuild, determina si se recopilan mediante la optimización de SkipNonexistentTargets. Si no se establece, el valor predeterminado es true. La consecuencia es un comportamiento con respuesta rápida a errores cuando no se pueden importar los destinos de un proyecto.
MSBuildProjectExtensionsPath Carpeta de salida, que de manera predeterminada es BaseIntermediateOutputPath y la carpeta obj.
RestoreForce En los proyectos basados en PackageReference, fuerza la resolución de todas las dependencias, incluso si la última restauración se realizó correctamente. Especificar esta marca es similar a eliminar el archivo project.assets.json. Esto no omite la caché http.
RestorePackagesWithLockFile Opta por el uso de un archivo de bloqueo.
RestoreLockedMode Ejecute la restauración en modo de bloqueo. Esto significa que la restauración no volverá a evaluar las dependencias.
NuGetLockFilePath Una ubicación personalizada para el archivo de bloqueo. La ubicación predeterminada está junto al proyecto y se denomina packages.lock.json.
RestoreForceEvaluate Fuerza la restauración para volver a calcular las dependencias y actualizar el archivo de bloqueo sin ninguna advertencia.
RestorePackagesConfig Un modificador de participación que restaura proyectos con packages.config. Compatibilidad solo con MSBuild -t:restore.
RestoreRepositoryPath Solo packages.config. Especifica el directorio de paquetes al que se deben restaurar los paquetes. Si no se especifica, se usará SolutionDirectory.
RestoreUseStaticGraphEvaluation Un modificador de participación para usar la evaluación de MSBuild de grafos estáticos en lugar de la evaluación estándar. La evaluación de grafos estáticos es una característica experimental que es significativamente más rápida para grandes repositorios y soluciones.

La propiedad ExcludeRestorePackageImports es una propiedad interna utilizada por NuGet. No debe modificarse ni establecerse en ningún archivo MSBuild.

Ejemplos

Línea de comandos:

msbuild -t:restore -p:RestoreConfigFile=<path>

Archivo del proyecto:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Restaurar salidas

La restauración crea los archivos siguientes en la carpeta obj de compilación:

Archivo Descripción
project.assets.json Contiene el gráfico de dependencias de todas las referencias de paquetes.
{projectName}.projectFileExtension.nuget.g.props Referencias a propiedades de MSBuild incluidas en paquetes
{projectName}.projectFileExtension.nuget.g.targets Referencias a destinos de MSBuild incluidos en paquetes

Restauración y compilación con un comando de MSBuild

Debido al hecho de que NuGet puede restaurar paquetes que traen destinos y propiedades de MSBuild, las evaluaciones de restauración y compilación se ejecutan con diferentes propiedades globales. Esto significa que lo siguiente tendrá un comportamiento impredecible y a menudo incorrecto.

msbuild -t:restore,build

En su lugar, el enfoque recomendado es:

msbuild -t:build -restore

La misma lógica se aplica a otros destinos similares a build.

Restauración de los proyectos PackageReference y packages.config con MSBuild

Con MSBuild 16.5 y versiones posteriores, packages.config también se admite para msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Nota:

La restauración de packages.config solo está disponible con MSBuild 16.5+, y no con dotnet.exe.

Restauración con la evaluación de MSBuild de grafos estáticos

Nota:

Con MSBuild 16.6 y versiones posteriores, NuGet ha agregado una característica experimental para usar la evaluación de grafos estáticos desde la línea de comandos que mejora significativamente el tiempo de restauración de los repositorios grandes.

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Como alternativa, puede habilitarla especificando la propiedad en un archivo Directory.Build.Props.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

Nota:

A partir de Visual Studio 2019.x y NuGet 5.x, esta característica se considera experimental y de participación. Siga NuGet/Home#9803 para obtener más información sobre cuándo se habilitará esta característica de manera predeterminada.

La restauración de grafos estáticos cambia la parte de msbuild de la restauración, la lectura y evaluación del proyecto, pero no el algoritmo de restauración. El algoritmo de restauración es el mismo en todas las herramientas de NuGet (NuGet.exe, MSBuild.exe, dotnet.exe y Visual Studio).

En muy pocos escenarios, la restauración de grafos estáticos puede comportarse de forma diferente a la restauración actual y es posible que falten ciertas instancias de PackageReferences o ProjectReferences declaradas.

Para proporcionarle tranquilidad, como una comprobación única, al migrar a la restauración de grafos estáticos considere la posibilidad de ejecutar:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGetno debe notificar ningún cambio. Si ve una discrepancia, envíe un problema en NuGet/Home.

Reemplazo de una biblioteca desde un gráfico de restauración

Si una restauración agrega el ensamblado equivocado, se puede excluir la opción predeterminada de ese paquete y reemplazarla por una de su propia elección. En primer lugar, con una PackageReference de nivel superior, excluya todos los activos:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Después, agregue su propia referencia a la copia local correspondiente del archivo DLL:

<Reference Include="Newtonsoft.Json.dll" />