NuGet empaquetar y restaurar como MSBuild destinos

4.0+

Con el formato PackageReference, 4.0+ puede almacenar todos los metadatos del manifiesto directamente dentro de un archivo de proyecto en lugar de usar un archivo .nuspec independiente.

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

Orden de compilación de destinos

Como pack y restore son MSBuild destinos, puede acceder 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 MSBuild tarea, escribir su propio destino y consumir NuGet propiedades en la MSBuild tarea.

Destino de pack

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

En la tabla siguiente se describen MSBuild las propiedades que se pueden agregar a un archivo de proyecto dentro del primer <PropertyGroup> nodo. 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 mediante la propiedad equivalente en " data-linktype="relative-path">.nuspec file .

Entradas de destino de pack

Escenarios de pack

Supresión de dependencias

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

PackageIconUrl

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

PackageIcon

Empaquetado de un archivo de imagen de icono

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

Por ejemplo:

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

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

NuGet /Samples/tree/main/PackageIconExample" data-linktype="external">package icon sample .

Para el equivalente, echa un vistazo a la referencia nuspec nuspecnuspec "#icon" data-linktype="relative-path" >nuspec del icono .

PackageReadmeFile

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

Al empaquetar un archivo Léame, debe usar la propiedad para especificar la ruta de acceso del paquete, en relación con la PackageReadmeFile raíz del paquete. Además de esto, debe asegurarse de que el archivo está incluido 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 el equivalente, echa un vistazo a la referencia nuspec nuspecnuspec "#readme" data-linktype="relative-path" >nuspec para 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 MSBuild que proporciona el BuiltOutputProjectGroup destino.

Hay dos propiedades que puede usar en el archivo del proyecto o en la línea de comandos MSBuild 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

Project a las referencias de proyecto se consideran de forma predeterminada como NuGet referencias de paquete. 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 desea copiar todo el contenido solo en una carpeta raíz específica (en lugar de y en ambas), puede usar la propiedad , que tiene como valor predeterminado contentcontentFilesMSBuild "content;contentFiles", pero se puede establecer en cualquier otro nombre de ContentTargetFolders 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 MSBuild propiedad , cuyo valor predeterminado es $(IncludeContentInPack)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 puede establecer en cualquiera de los elementos anteriores incluyen y qué conjuntos y valores <PackageCopyToOutput> en la entrada de la salida <PackageFlatten>CopyToOutputFlattencontentFiles nuspec .

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 IncludeSymbols=true 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

Cuando use una expresión de licencia, use la PackageLicenseExpression propiedad . Para obtener un ejemplo, vea NuGet /Samples/tree/main/PackageLicenseExpressionExample" data-linktype="external">License expression sample .

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

Para obtener más información sobre las expresiones de licencia y las licencias aceptadas por NuGet .org, vea NuGetnuspec "#license" data-linktype="relative-path">license metadata .

Al empaquetar un archivo de licencia, use la propiedad para especificar la ruta de acceso del paquete, en relación con PackageLicenseFile la raíz del paquete. Además, asegúrese de que el archivo está incluido 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, vea NuGet /Samples/tree/main/PackageLicenseFileExample" data-linktype="external">License file sample .

Empaquetado de un archivo sin una extensión

En algunos escenarios, como al empaquetar un archivo de licencia, es posible que quiera incluir un archivo sin una extensión. Por motivos históricos, NuGet&MSBuild trate las rutas de acceso sin una extensión como directorios.

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

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

NuGet /Samples/blob/main/PackageLicenseFileExtensionlessExample/" data-linktype="external">File 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 MSBuild -t:pack -p:IsTool=true, 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.

-nuspec-file">Empaquetado mediante un .nuspec archivo

Aunque se recomienda incluir todas las propiedades que normalmente están en el archivo en el archivo de proyecto en su lugar, puede optar por usar un archivo para .nuspec empaquetar el proyecto. En el caso de un proyecto que no sea de estilo SDK que use , debe importar para que se pueda ejecutar la tarea de PackageReferenceNuGet.Build.Tasks.Pack.targets empaquetado. Debe restaurar el proyecto para poder empaquetar un nuspec archivo. (Un proyecto de estilo SDK incluye los destinos del paquete de forma predeterminada).

La plataforma de destino del archivo de proyecto es irrelevante y no se usa al empaquetar nuspec un . Las tres propiedades MSBuild siguientes son relevantes para empaquetar mediante .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 la línea de comandos, se deben especificar varias propiedades de MSBuild la siguiente manera: -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 dotnet.exe o msbuild también conduce a nuspec la creación del proyecto de forma predeterminada. Esto se puede evitar pasando la propiedad a dotnet.exe, que es el equivalente de establecer en el archivo de proyecto, junto con la configuración --no-build en el archivo de <NoBuild>true</NoBuild> <IncludeBuildOutput>false</IncludeBuildOutput> proyecto.

Un ejemplo de un archivo .csproj para empaquetar un archivo 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 pack destino proporciona dos puntos de extensión que se ejecutan en la compilación interna específica del marco de destino. Los puntos de extensión admiten la inclusión de ensamblados y contenido específicos de la plataforma de destino en un paquete:

• TargetsForTfmSpecificBuildOutput target: se usa para los archivos dentro de lib la carpeta o una carpeta especificada mediante BuildOutputTargetFolder .
• TargetsForTfmSpecificContentInPackage target: se usa para archivos fuera de BuildOutputTargetFolder .

TargetsForTfmSpecificBuildOutput

Escribir un destino personalizado y especificarlo como el valor de la $(TargetsForTfmSpecificBuildOutput) propiedad . En el caso de los archivos que necesiten entrar en (lib de forma predeterminada), el destino debe escribir esos archivos en ItemGroup y establecer los dos valores de metadatos BuildOutputTargetFolderBuildOutputInPackage 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) Se establece cuando el archivo debe ir a una subcarpeta dentro de , como los ensamblados satélite que van bajo lib\<TargetFramework> 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

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

• 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 contentFiles carpeta . El valor predeterminado es "None".

Por 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. Pasar MSBuild datos a NuGet .Build.Tasks.dll
4. Ejecutar la restauración
5. Descarga de paquetes
6. Escribir el archivo de activos, destinos y propiedades

El restore destino funciona para proyectos que usan el formato PackageReference. MSBuild 16.5+ también tiene MSBuild 16.5+ en el packages.config formato.

Restaurar las propiedades

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

Ejemplos

Línea de comandos:

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

Archivo del proyecto:

<PropertyGroup>
    <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

Restaurar salidas

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

Restauración y creación con un MSBuild comando

Debido al hecho de que puede restaurar paquetes que bajan destinos y propiedades, las evaluaciones de restauración y compilación se ejecutan NuGetMSBuild con diferentes propiedades globales. Esto significa que lo siguiente tendrá un comportamiento imprevisible 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 .

Restaurar PackageReference y packages.config proyectos con MSBuild

Con MSBuild la versión 16.5+, packages.config también se admiten para msbuild -t:restore .

msbuild -t:restore -p:RestorePackagesConfig=true

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

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

También puede habilitarla estableciendo la propiedad en Directory.Build.Props.

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

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 NuGetNuGet (.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 falte ciertas packageReferences o ProjectReferences declaradas.

Para facilitar la mente, 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

NuGet no NuGet ningún cambio. Si ve una discrepancia, envíe un problema a 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" />