pack y restore de NuGet como destinos de MSBuildNuGet pack and restore as MSBuild targets

NuGet 4.0 y versiones posterioresNuGet 4.0+

Con el formato PackageReference , NuGet 4.0 + puede almacenar todos los metadatos del manifiesto directamente dentro de un archivo de proyecto en lugar de usar un .nuspec archivo independiente.With the PackageReference format, NuGet 4.0+ can store all manifest metadata directly within a project file rather than using a separate .nuspec file.

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.With MSBuild 15.1+, NuGet is also a first-class MSBuild citizen with the pack and restore targets as described below. Estos destinos permiten trabajar con NuGet como lo haría con cualquier otra tarea o destino de MSBuild.These targets allow you to work with NuGet as you would with any other MSBuild task or target. Para obtener instrucciones sobre cómo crear un paquete NuGet con MSBuild, consulte crear un paquete Nuget con MSBuild.For instructions creating a NuGet package using MSBuild, see Create a NuGet package using 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).(For NuGet 3.x and earlier, you use the pack and restore commands through the NuGet CLI instead.)

Orden de compilación de destinosTarget build order

Dado que pack y restore son destinos de MSBuild, puede tener acceso a ellos para mejorar el flujo de trabajo.Because pack and restore are MSBuild targets, you can access them to enhance your workflow. Por ejemplo, supongamos que quiere copiar el paquete en un recurso compartido de red después de empaquetarlo.For example, let’s say you want to copy your package to a network share after packing it. Puede hacer esto si agrega lo siguiente al archivo de proyecto:You can do that by adding the following in your project file:

<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.Similarly, you can write an MSBuild task, write your own target and consume NuGet properties in the MSBuild task.

Nota

$(OutputPath) es relativo y espera que se ejecute el comando desde la raíz del proyecto.$(OutputPath) is relative and expects that you are running the command from the project root.

Destino de packpack target

En el caso de los proyectos de .NET Standard con el formato PackageReference, el uso de msbuild -t:pack dibuja entradas del archivo de proyecto para usarlas en la creación de un paquete NuGet.For .NET Standard projects using the PackageReference format, using msbuild -t:pack draws inputs from the project file to use in creating a NuGet package.

En la tabla siguiente se describen las propiedades de MSBuild que se pueden agregar a un archivo de proyecto en el primer nodo <PropertyGroup>.The table below describes the MSBuild properties that can be added to a project file within the first <PropertyGroup> node. 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.You can make these edits easily in Visual Studio 2017 and later by right-clicking the project and selecting Edit {project_name} on the context menu. Para mayor comodidad, la tabla está organizada por la propiedad equivalente en un .nuspec archivo.For convenience the table is organized by the equivalent property in a .nuspec file.

Tenga en cuenta que las propiedades Owners y Summary de .nuspec no son compatibles con MSBuild.Note that the Owners and Summary properties from .nuspec are not supported with MSBuild.

Valor de atributo/NuSpecAttribute/NuSpec Value Propiedad de MSBuildMSBuild Property Valor predeterminadoDefault NotasNotes
IdentificadorId PackageIdPackageId AssemblyNameAssemblyName $(NombreDeEnsamblado) de MSBuild$(AssemblyName) from MSBuild
VersiónVersion PackageVersionPackageVersion VersiónVersion Esto es compatible con semver, por ejemplo, "1.0.0", "1.0.0-beta" o "1.0.0-beta-00345"This is semver compatible, for example “1.0.0”, “1.0.0-beta”, or “1.0.0-beta-00345”
VersionPrefixVersionPrefix PackageVersionPrefixPackageVersionPrefix emptyempty Al establecer PackageVersion se sobrescribe PackageVersionPrefix.Setting PackageVersion overwrites PackageVersionPrefix
VersionSuffixVersionSuffix PackageVersionSuffixPackageVersionSuffix emptyempty $(VersionSuffix) de MSBuild.$(VersionSuffix) from MSBuild. Al establecer PackageVersion se sobrescribe PackageVersionSuffix.Setting PackageVersion overwrites PackageVersionSuffix
AuthorsAuthors AuthorsAuthors Nombre del usuario actualUsername of the current user
PropietariosOwners N/DN/A No está presente en el archivo NuSpecNot present in NuSpec
TitleTitle TitleTitle El identificador de paqueteThe PackageId
DescripciónDescription DescripciónDescription "Descripción del paquete""Package Description"
CopyrightCopyright CopyrightCopyright emptyempty
RequireLicenseAcceptanceRequireLicenseAcceptance PackageRequireLicenseAcceptancePackageRequireLicenseAcceptance falsefalse
licenselicense PackageLicenseExpressionPackageLicenseExpression emptyempty Se corresponde con <license type="expression">Corresponds to <license type="expression">
licenselicense PackageLicenseFilePackageLicenseFile emptyempty Se corresponde con <license type="file">.Corresponds to <license type="file">. Debe empaquetar explícitamente el archivo de licencia al que se hace referencia.You need to explicitly pack the referenced license file.
LicenseUrlLicenseUrl PackageLicenseUrlPackageLicenseUrl emptyempty PackageLicenseUrl está en desuso, use la propiedad PackageLicenseExpression o PackageLicenseFilePackageLicenseUrl is deprecated, use the PackageLicenseExpression or PackageLicenseFile property
ProjectUrlProjectUrl PackageProjectUrlPackageProjectUrl emptyempty
IconoIcon PackageIconPackageIcon emptyempty Debe empaquetar explícitamente el archivo de imagen de icono al que se hace referencia.You need to explicitly pack the referenced icon image file.
IconUrlIconUrl PackageIconUrlPackageIconUrl emptyempty Para la mejor experiencia de nivel inferior, PackageIconUrl debe especificarse además de PackageIcon .For the best downlevel experience, PackageIconUrl should be specified in addition to PackageIcon. A largo plazo, estará en PackageIconUrl desuso.Longer term, PackageIconUrl will be deprecated.
EtiquetasTags PackageTagsPackageTags emptyempty Las etiquetas están delimitadas mediante punto y coma.Tags are semi-colon delimited.
ReleaseNotesReleaseNotes PackageReleaseNotesPackageReleaseNotes emptyempty
Repositorio/dirección URLRepository/Url RepositoryUrlRepositoryUrl emptyempty Dirección URL del repositorio usada para clonar o recuperar el código fuente.Repository URL used to clone or retrieve source code. Ejemplo https://github.com/NuGet/NuGet.Client.gitExample: https://github.com/NuGet/NuGet.Client.git
Repositorio/tipoRepository/Type RepositoryTypeRepositoryType emptyempty Tipo de repositorio.Repository type. Ejemplos: git, TFS.Examples: git, tfs.
Repositorio/ramaRepository/Branch RepositoryBranchRepositoryBranch emptyempty Información opcional de la rama del repositorio.Optional repository branch information. También se debe especificar RepositoryUrl para que se incluya esta propiedad.RepositoryUrl must also be specified for this property to be included. Ejemplo: maestra (NuGet 4.7.0 +)Example: master (NuGet 4.7.0+)
Repositorio/confirmarRepository/Commit RepositoryCommitRepositoryCommit emptyempty Confirmación o conjunto de cambios opcionales de repositorio para indicar en qué origen se ha compilado el paquete.Optional repository commit or changeset to indicate which source the package was built against. También se debe especificar RepositoryUrl para que se incluya esta propiedad.RepositoryUrl must also be specified for this property to be included. Ejemplo: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0 +)Example: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+)
PackageTypePackageType <PackageType>DotNetCliTool, 1.0.0.0;Dependency, 2.0.0.0</PackageType>
ResumenSummary No compatibleNot supported

Entradas de destino de packpack target inputs

  • IsPackableIsPackable
  • SuppressDependenciesWhenPackingSuppressDependenciesWhenPacking
  • PackageVersionPackageVersion
  • PackageIdPackageId
  • AuthorsAuthors
  • DescripciónDescription
  • CopyrightCopyright
  • PackageRequireLicenseAcceptancePackageRequireLicenseAcceptance
  • DevelopmentDependencyDevelopmentDependency
  • PackageLicenseExpressionPackageLicenseExpression
  • PackageLicenseFilePackageLicenseFile
  • PackageLicenseUrlPackageLicenseUrl
  • PackageProjectUrlPackageProjectUrl
  • PackageIconUrlPackageIconUrl
  • PackageReleaseNotesPackageReleaseNotes
  • PackageTagsPackageTags
  • PackageOutputPathPackageOutputPath
  • IncludeSymbolsIncludeSymbols
  • IncludeSourceIncludeSource
  • PackageTypesPackageTypes
  • IsToolIsTool
  • RepositoryUrlRepositoryUrl
  • RepositoryTypeRepositoryType
  • RepositoryBranchRepositoryBranch
  • RepositoryCommitRepositoryCommit
  • NoPackageAnalysisNoPackageAnalysis
  • MinClientVersionMinClientVersion
  • IncludeBuildOutputIncludeBuildOutput
  • IncludeContentInPackIncludeContentInPack
  • BuildOutputTargetFolderBuildOutputTargetFolder
  • ContentTargetFoldersContentTargetFolders
  • NuspecFileNuspecFile
  • NuspecBasePathNuspecBasePath
  • NuspecPropertiesNuspecProperties

Escenarios de packpack scenarios

Suprimir dependenciasSuppress dependencies

Para suprimir las dependencias de paquete del paquete NuGet generado, establezca SuppressDependenciesWhenPacking en, true lo que permitirá omitir todas las dependencias del archivo nupkg generado.To suppress package dependencies from generated NuGet package, set SuppressDependenciesWhenPacking to true which will allow skipping all the dependencies from generated nupkg file.

PackageIconUrlPackageIconUrl

PackageIconUrl quedará en desuso en favor de la nueva PackageIcon propiedad.PackageIconUrl will be deprecated in favor of the new PackageIcon property.

A partir de NuGet 5,3 & Visual Studio 2019 versión 16,3, pack se generará una advertencia NU5048 si los metadatos del paquete solo especifican PackageIconUrl .Starting with NuGet 5.3 & Visual Studio 2019 version 16.3, pack will raise NU5048 warning if the package metadata only specifies PackageIconUrl.

PackageIconPackageIcon

Sugerencia

Debe especificar PackageIcon y PackageIconUrl para mantener la compatibilidad con versiones anteriores de clientes y orígenes que aún no admiten PackageIcon .You should specify both PackageIcon and PackageIconUrl to maintain backward compatibility with clients and sources that do not yet support PackageIcon. Visual Studio será compatible con los PackageIcon paquetes procedentes de un origen basado en carpetas en una versión futura.Visual Studio will support PackageIcon for packages coming from a folder-based source in a future release.

Empaquetar un archivo de imagen de iconoPacking an icon image file

Al empaquetar un archivo de imagen de icono, debe usar PackageIcon la propiedad para especificar la ruta de acceso del paquete, relativa a la raíz del paquete.When packing an icon image file, you need to use PackageIcon property to specify the package path, relative to the root of the package. Además, debe asegurarse de que el archivo está incluido en el paquete.In addition, you need to make sure that the file is included in the package. El tamaño del archivo de imagen está limitado a 1 MB.Image file size is limited to 1 MB. Entre los formatos de archivo admitidos se incluyen JPEG y PNG.Supported file formats include JPEG and PNG. Se recomienda una resolución de imagen de 128x128.We recommend an image resolution of 128x128.

Por ejemplo:For example:

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

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

Ejemplo de icono de paquete.Package Icon sample.

En el caso del equivalente de nuspec, eche un vistazo a la referencia de nuspec para el icono.For the nuspec equivalent, take a look at nuspec reference for icon.

Ensamblados de salidaOutput assemblies

nuget pack copia los archivos de salida con las extensiones .exe, .dll, .xml, .winmd, .json y .pri.nuget pack copies output files with extensions .exe, .dll, .xml, .winmd, .json, and .pri. Los archivos de salida que se copian dependen de lo que proporciona MSBuild desde el destino BuiltOutputProjectGroup.The output files that are copied depend on what MSBuild provides from the BuiltOutputProjectGroup target.

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:There are two MSBuild properties that you can use in your project file or command line to control where output assemblies go:

  • IncludeBuildOutput: un valor booleano que determina si los ensamblados de salida de compilación deben incluirse en el paquete.IncludeBuildOutput: A boolean that determines whether the build output assemblies should be included in the package.
  • BuildOutputTargetFolder: especifica la carpeta en la que se deben colocar los ensamblados de salida.BuildOutputTargetFolder: Specifies the folder in which the output assemblies should be placed. Los ensamblados de salida (y otros archivos de salida) se copian en sus respectivas carpetas de marco.The output assemblies (and other output files) are copied into their respective framework folders.

Referencias de paquetePackage references

Vea Referencias de paquete en archivos de proyecto.See Package References in Project Files.

Referencias entre proyectosProject to project references

Las referencias entre proyectos se consideran de forma predeterminada como referencias de paquetes NuGet, por ejemplo:Project to project references are considered by default as nuget package references, for example:

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

También puede agregar los metadatos siguientes a la referencia de proyecto:You can also add the following metadata to your project reference:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Inclusión de contenido en un paqueteIncluding content in a package

Para incluir contenido, agregue metadatos adicionales al elemento <Content> existente.To include content, add extra metadata to the existing <Content> item. De forma predeterminada todos los elementos de tipo "Content" se incluyen en el paquete a menos que los reemplace con entradas como la siguiente:By default everything of type "Content" gets included in the package unless you override with entries like the following:

<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:By default, everything gets added to the root of the content and contentFiles\any\<target_framework> folder within a package and preserves the relative folder structure, unless you specify a package path:

<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 ContentTargetFolders de MSBuild, cuyo valor predeterminado es "content;contentFiles", pero que se puede establecer en cualquier otro nombre de carpeta.If you want to copy all your content to only a specific root folder(s) (instead of content and contentFiles both), you can use the MSBuild property ContentTargetFolders, which defaults to "content;contentFiles" but can be set to any other folder names. 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.Note that just specifying "contentFiles" in ContentTargetFolders puts files under contentFiles\any\<target_framework> or contentFiles\<language>\<target_framework> based on buildAction.

PackagePath puede ser un conjunto de rutas de acceso de destino delimitadas por punto y coma.PackagePath can be a semicolon-delimited set of target paths. Especificar una ruta de acceso de paquete vacía agregaría el archivo a la raíz del paquete.Specifying an empty package path would add the file to the root of the package. Por ejemplo, en el ejemplo siguiente se agrega libuv.txt a content\myfiles, content\samples y la raíz del paquete:For example, the following adds libuv.txt to content\myfiles, content\samples, and the package root:

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

También hay una propiedad $(IncludeContentInPack) de MSBuild, cuyo valor predeterminado es true.There is also an MSBuild property $(IncludeContentInPack), which defaults to true. Si esto se establece en false en cualquier proyecto, el contenido de ese proyecto no se incluye en el paquete NuGet.If this is set to false on any project, then the content from that project are not included in the nuget package.

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.Other pack specific metadata that you can set on any of the above items includes <PackageCopyToOutput> and <PackageFlatten> which sets CopyToOutput and Flatten values on the contentFiles entry in the output nuspec.

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.Apart from Content items, the <Pack> and <PackagePath> metadata can also be set on files with a build action of Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreateableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource or 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.For pack to append the filename to your package path when using globbing patterns, your package path must end with the folder separator character, otherwise the package path is treated as the full path including the file name.

IncludeSymbolsIncludeSymbols

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).When using MSBuild -t:pack -p:IncludeSymbols=true, the corresponding .pdb files are copied along with other output files (.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.Note that setting IncludeSymbols=true creates a regular package and a symbols package.

IncludeSourceIncludeSource

Esto equivale a IncludeSymbols, salvo que también copia los archivos de código fuente junto con los archivos .pdb.This is the same as IncludeSymbols, except that it copies source files along with .pdb files as well. 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.All files of type Compile are copied over to src\<ProjectName>\ preserving the relative path folder structure in the resulting package. Lo mismo sucede para los archivos de código fuente de cualquier ProjectReference en la que TreatAsPackageReference se establece en false.The same also happens for source files of any ProjectReference which has TreatAsPackageReference set to false.

Si un archivo de tipo Compile está fuera de la carpeta de proyecto, simplemente se agrega a src\<ProjectName>\.If a file of type Compile, is outside the project folder, then it's just added to src\<ProjectName>\.

Empaquetado de una expresión de licencia o un archivo de licenciaPacking a license expression or a license file

Cuando se usa una expresión de licencia, se debe usar la propiedad PackageLicenseExpression.When using a license expression, the PackageLicenseExpression property should be used. Ejemplo de expresión de licencia.License expression sample.

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

Obtenga más información sobre las expresiones de licencia y las licencias que acepta NuGet.org.Learn more about license expressions and licenses that are accepted by NuGet.org.

Al empaquetar un archivo de licencia, debe usar la propiedad PackageLicenseFile para especificar la ruta de acceso del paquete, relativa a la raíz del paquete.When packing a license file, you need to use PackageLicenseFile property to specify the package path, relative to the root of the package. Además, debe asegurarse de que el archivo está incluido en el paquete.In addition, you need to make sure that the file is included in the package. Por ejemplo:For example:

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

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

Ejemplo de archivo de licencia.License file sample.

IsToolIsTool

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.When using MSBuild -t:pack -p:IsTool=true, all output files, as specified in the Output Assemblies scenario, are copied to the tools folder instead of the lib folder. Tenga en cuenta que esto es diferente de DotNetCliTool, que se especifica estableciendo PackageType en el archivo .csproj.Note that this is different from a DotNetCliTool which is specified by setting the PackageType in .csproj file.

Empaquetado mediante un archivo .nuspecPacking using a .nuspec

Aunque se recomienda incluir todas las propiedades que suelen estar en el archivo .nuspec en el archivo del proyecto, puede optar por usar un .nuspec archivo para empaquetar el proyecto.Although it is recommended that you include all the properties that are usually in the .nuspec file in the project file instead, you can choose to use a .nuspec file to pack your project. 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 del paquete.For a non-SDK-style project that uses PackageReference, you must import NuGet.Build.Tasks.Pack.targets so that the pack task can be executed. Todavía es necesario restaurar el proyecto para poder empaquetar un archivo nuspec.You still need to restore the project before you can pack a nuspec file. (Un proyecto de estilo SDK incluye los destinos Pack de forma predeterminada).(An SDK-style project includes the pack targets by default.)

El marco de trabajo de destino del archivo de proyecto es irrelevante y no se usa cuando se empaqueta un archivo nuspec.The target framework of the project file is irrelevant and not used when packing a nuspec. Las tres propiedades de MSBuild siguientes son relevantes para el empaquetado mediante un archivo .nuspec:The following three MSBuild properties are relevant to packing using a .nuspec:

  1. NuspecFile: ruta de acceso relativa o absoluta al archivo .nuspec que se usa para el empaquetado.NuspecFile: relative or absolute path to the .nuspec file being used for packing.
  2. NuspecProperties: lista de pares clave=valor separados por punto y coma.NuspecProperties: a semicolon-separated list of key=value pairs. 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".Due to the way MSBuild command-line parsing works, multiple properties must be specified as follows: -p:NuspecProperties="key1=value1;key2=value2".
  3. NuspecBasePath: ruta de acceso base para el archivo .nuspec.NuspecBasePath: Base path for the .nuspec file.

Si se usa dotnet.exe para empaquetar el proyecto, use un comando similar al siguiente:If using dotnet.exe to pack your project, use a command like the following:

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:If using MSBuild to pack your project, use a command like the following:

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

Tenga en cuenta que al empaquetar un nuspec mediante dotnet.exe o MSBuild también se genera el proyecto de forma predeterminada.Please note that packing a nuspec using dotnet.exe or msbuild also leads to building the project by default. Esto se puede evitar pasando --no-build Property a dotnet.exe, que es el equivalente de la configuración <NoBuild>true</NoBuild> en el archivo de proyecto, junto con <IncludeBuildOutput>false</IncludeBuildOutput> el valor en el archivo de proyecto.This can be avoided by passing --no-build property to dotnet.exe, which is the equivalent of setting <NoBuild>true</NoBuild> in your project file, along with setting <IncludeBuildOutput>false</IncludeBuildOutput> in the project file.

Un ejemplo de un archivo . csproj para empaquetar un archivo nuspec es el siguiente:An example of a .csproj file to pack a nuspec file is:

<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 personalizadoAdvanced extension points to create customized package

El pack destino proporciona dos puntos de extensión que se ejecutan en la compilación interna específica de la plataforma de destino.The pack target provides two extension points that run in the inner, target framework specific build. Los puntos de extensión admiten, incluidos los ensamblados y el contenido específico de la plataforma de destino en un paquete:The extension points support including target framework specific content and assemblies into a package:

  • TargetsForTfmSpecificBuildOutput destino: se usa para los archivos dentro de la lib carpeta o en una carpeta especificada mediante BuildOutputTargetFolder .TargetsForTfmSpecificBuildOutput target: Use for files inside the lib folder or a folder specified using BuildOutputTargetFolder.
  • TargetsForTfmSpecificContentInPackage destino: se usa para archivos fuera de BuildOutputTargetFolder .TargetsForTfmSpecificContentInPackage target: Use for files outside the BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutputTargetsForTfmSpecificBuildOutput

Escriba un destino personalizado y especifíquelo como el valor de la $(TargetsForTfmSpecificBuildOutput) propiedad.Write a custom target and specify it as the value of the $(TargetsForTfmSpecificBuildOutput) property. En el caso de los archivos que necesiten entrar en BuildOutputTargetFolder (de forma predeterminada, lib), el destino debe escribir esos archivos en el ItemGroup BuildOutputInPackage y establecer los dos valores de metadatos siguientes:For any files that need to go into the BuildOutputTargetFolder (lib by default), the target should write those files into the ItemGroup BuildOutputInPackage and set the following two metadata values:

  • FinalOutputPath: Ruta de acceso absoluta del archivo; Si no se proporciona, la identidad se utiliza para evaluar la ruta de acceso de origen.FinalOutputPath: The absolute path of the file; if not provided, the Identity is used to evaluate source path.
  • TargetPath: (Opcional) se establece cuando el archivo debe ir a una subcarpeta dentro de lib\<TargetFramework> , como los ensamblados satélite que se encuentran bajo sus respectivas carpetas de referencia cultural.TargetPath: (Optional) Set when the file needs to go into a subfolder within lib\<TargetFramework> , like satellite assemblies that go under their respective culture folders. Tiene como valor predeterminado el nombre del archivo.Defaults to the name of the file.

Ejemplo:Example:

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

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

TargetsForTfmSpecificContentInPackageTargetsForTfmSpecificContentInPackage

Escriba un destino personalizado y especifíquelo como el valor de la $(TargetsForTfmSpecificContentInPackage) propiedad.Write a custom target and specify it as the value of the $(TargetsForTfmSpecificContentInPackage) property. En el caso de los archivos que se van a incluir en el paquete, el destino debe escribir esos archivos en el ItemGroup TfmSpecificPackageFile y establecer los metadatos opcionales siguientes:For any files to include in the package, the target should write those files into the ItemGroup TfmSpecificPackageFile and set the following optional metadata:

  • PackagePath: Ruta de acceso en la que el archivo debe generarse en el paquete.PackagePath: Path where the file should be output in the package. NuGet emite una advertencia si se agrega más de un archivo a la misma ruta de acceso del paquete.NuGet issues a warning if more than one file is added to the same package path.
  • BuildAction: Acción de compilación que se va a asignar al archivo, que solo es necesario si la ruta de acceso del paquete está en la contentFiles carpeta.BuildAction: The build action to assign to the file, required only if the package path is in the contentFiles folder. El valor predeterminado es "none".Defaults to "None".

Por ejemplo:An example:

<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 restorerestore target

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:MSBuild -t:restore (which nuget restore and dotnet restore use with .NET Core projects), restores packages referenced in the project file as follows:

  1. Leer todas las referencias entre proyectosRead all project to project references
  2. Leer las propiedades del proyecto para buscar las carpetas y plataformas de destino intermediasRead the project properties to find the intermediate folder and target frameworks
  3. Pasar datos de MSBuild a NuGet.Build.Tasks.dllPass MSBuild data to NuGet.Build.Tasks.dll
  4. Ejecutar la restauraciónRun restore
  5. Descarga de paquetesDownload packages
  6. Escribir el archivo de activos, destinos y propiedadesWrite assets file, targets, and props

El restore destino solo funciona con los proyectos que usan el formato PackageReference.The restore target works only for projects using the PackageReference format. No funciona para los proyectos que usan el packages.config formato; use la restauración de Nuget en su lugar.It does not work for projects using the packages.config format; use nuget restore instead.

Restaurar las propiedadesRestore properties

Otra configuración de restauración puede proceder de propiedades de MSBuild en el archivo de proyecto.Additional restore settings may come from MSBuild properties in the project file. También se pueden establecer valores desde la línea de comandos mediante el modificador -p: (vea los ejemplos siguientes).Values can also be set from the command line using the -p: switch (see Examples below).

PropiedadProperty DescripciónDescription
RestoreSourcesRestoreSources Lista delimitada por punto y coma de orígenes de paquetes.Semicolon-delimited list of package sources.
RestorePackagesPathRestorePackagesPath Ruta de acceso de la carpeta de paquetes de usuario.User packages folder path.
RestoreDisableParallelRestoreDisableParallel Limitar las descargas a una cada vez.Limit downloads to one at a time.
RestoreConfigFileRestoreConfigFile Ruta de acceso a un archivo Nuget.Config que se va a aplicar.Path to a Nuget.Config file to apply.
RestoreNoCacheRestoreNoCache Si es true, evita el uso de paquetes almacenados en caché.If true, avoids using cached packages. Consulte Administración de paquetes globales y carpetas de caché.See Managing the global packages and cache folders.
RestoreIgnoreFailedSourcesRestoreIgnoreFailedSources Si es true, ignora los orígenes de paquetes que producen errores o faltan.If true, ignores failing or missing package sources.
RestoreFallbackFoldersRestoreFallbackFolders Carpetas de reserva que se usan de la misma manera que se usa la carpeta de paquetes de usuario.Fallback folders, used in the same way the user packages folder is used.
RestoreAdditionalProjectSourcesRestoreAdditionalProjectSources Fuentes adicionales para usar durante la restauración.Additional sources to use during restore.
RestoreAdditionalProjectFallbackFoldersRestoreAdditionalProjectFallbackFolders Carpetas de reserva adicionales para usar durante la restauración.Additional fallback folders to use during restore.
RestoreAdditionalProjectFallbackFoldersExcludesRestoreAdditionalProjectFallbackFoldersExcludes Excluye las carpetas de reserva especificadas en RestoreAdditionalProjectFallbackFoldersExcludes fallback folders specified in RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFileRestoreTaskAssemblyFile Ruta de acceso a NuGet.Build.Tasks.dll.Path to NuGet.Build.Tasks.dll.
RestoreGraphProjectInputRestoreGraphProjectInput Lista delimitada por punto y coma de proyectos para restaurar, que debe contener rutas de acceso absolutas.Semicolon-delimited list of projects to restore, which should contain absolute paths.
RestoreUseSkipNonexistentTargetsRestoreUseSkipNonexistentTargets Cuando los proyectos se recopilan a través de MSBuild, determina si se recopilan con la SkipNonexistentTargets optimización.When the projects are collected via MSBuild it determines whether they are collected using the SkipNonexistentTargets optimization. Cuando no se establece, el valor predeterminado es true .When not set, defaults to true. La consecuencia es un comportamiento de error rápido cuando no se pueden importar los destinos de un proyecto.The consequence is a fail-fast behavior when a project's targets cannot be imported.
MSBuildProjectExtensionsPathMSBuildProjectExtensionsPath Carpeta de salida, que tiene como valor predeterminado BaseIntermediateOutputPath y la obj carpeta.Output folder, defaulting to BaseIntermediateOutputPath and the obj folder.
RestoreForceRestoreForce En los proyectos basados en PackageReference, fuerza la resolución de todas las dependencias, incluso si la última restauración se realizó correctamente.In PackageReference based projects, forces all dependencies to be resolved even if the last restore was successful. Especificar esta marca es similar a eliminar el project.assets.json archivo.Specifying this flag is similar to deleting the project.assets.json file. Esto no omite la memoria caché http.This does not bypass the http-cache.
RestorePackagesWithLockFileRestorePackagesWithLockFile Opta por el uso de un archivo de bloqueo.Opts into the usage of a lock file.
RestoreLockedModeRestoreLockedMode Ejecutar restauración en modo bloqueado.Run restore in locked mode. Esto significa que la restauración no volverá a evaluar las dependencias.This means that restore will not reevaluate the dependencies.
NuGetLockFilePathNuGetLockFilePath Una ubicación personalizada para el archivo de bloqueo.A custom location for the lock file. La ubicación predeterminada es junto al proyecto y se denomina packages.lock.json .The default location is next to the project and is named packages.lock.json.
RestoreForceEvaluateRestoreForceEvaluate Fuerza la restauración para volver a calcular las dependencias y actualizar el archivo de bloqueo sin ninguna advertencia.Forces restore to recompute the dependencies and update the lock file without any warning.

EjemplosExamples

Línea de comandos:Command line:

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

Archivo del proyecto:Project file:

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

Restaurar salidasRestore outputs

La restauración crea los archivos siguientes en la carpeta obj de compilación:Restore creates the following files in the build obj folder:

ArchivoFile DescripciónDescription
project.assets.json Contiene el gráfico de dependencias de todas las referencias de paquete.Contains the dependency graph of all package references.
{projectName}.projectFileExtension.nuget.g.props Referencias a propiedades de MSBuild incluidas en paquetesReferences to MSBuild props contained in packages
{projectName}.projectFileExtension.nuget.g.targets Referencias a destinos de MSBuild incluidos en paquetesReferences to MSBuild targets contained in packages

Restaurar y compilar con un comando de MSBuildRestoring and building with one MSBuild command

Debido al hecho de que NuGet puede restaurar paquetes que desactivan los destinos y las propiedades de MSBuild, las evaluaciones de la restauración y de la compilación se ejecutan con propiedades globales diferentes.Due to the fact that NuGet can restore packages that bring down MSBuild targets and props, the restore and build evaluations are run with different global properties. Esto significa que el siguiente tendrá un comportamiento imprevisible y a menudo incorrecto.This means that the following will have an unpredictable and often incorrect behavior.

msbuild -t:restore,build

En su lugar, el enfoque recomendado es:Instead the recommended approach is:

msbuild -t:build -restore

La misma lógica se aplica a otros destinos similares a build .The same logic applies to other targets similar to build.

PackageTargetFallbackPackageTargetFallback

El elemento PackageTargetFallback permite especificar un conjunto de destinos compatibles que se usarán al restaurar los paquetes.The PackageTargetFallback element allows you to specify a set of compatible targets to be used when restoring packages. Está diseñado para permitir que los paquetes que usan un TxM de dotnet funcionen con paquetes compatibles que no declaran un TxM de dotnet.It's designed to allow packages that use a dotnet TxM to work with compatible packages that don't declare a dotnet TxM. Es decir, si el proyecto usa el TxM de dotnet, todos los paquetes de los que depende también deben tener un TxM de dotnet, a menos que agregue <PackageTargetFallback> al proyecto para permitir que las plataformas que no sean de dotnet sean compatibles con dotnet.That is, if your project uses the dotnet TxM, then all the packages it depends on must also have a dotnet TxM, unless you add the <PackageTargetFallback> to your project in order to allow non-dotnet platforms to be compatible with dotnet.

Por ejemplo, si el proyecto usa el TxM netstandard1.6 y un paquete dependiente solo contiene lib/net45/a.dll y lib/portable-net45+win81/a.dll, se producirá un error al compilar el proyecto.For example, if the project is using the netstandard1.6 TxM, and a dependent package contains only lib/net45/a.dll and lib/portable-net45+win81/a.dll, then the project will fail to build. Si lo que quiere incluir es el último archivo DLL, puede agregar PackageTargetFallback como se indica a continuación para indicar que el archivo DLL portable-net45+win81 es compatible:If what you want to bring in is the latter DLL, then you can add a PackageTargetFallback as follows to say that the portable-net45+win81 DLL is compatible:

<PackageTargetFallback Condition="'$(TargetFramework)'=='netstandard1.6'">
    portable-net45+win81
</PackageTargetFallback>

Para declarar una reserva para todos los destinos del proyecto, excluya el atributo Condition.To declare a fallback for all targets in your project, leave off the Condition attribute. También puede extender cualquier PackageTargetFallback existente mediante la inclusión de $(PackageTargetFallback) como se muestra aquí:You can also extend any existing PackageTargetFallback by including $(PackageTargetFallback) as shown here:

<PackageTargetFallback>
    $(PackageTargetFallback);portable-net45+win81
</PackageTargetFallback >

Reemplazo de una biblioteca desde un gráfico de restauraciónReplacing one library from a restore graph

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.If a restore is bringing the wrong assembly, it's possible to exclude that packages default choice, and replace it with your own choice. En primer lugar, con una PackageReference de nivel superior, excluya todos los activos:First with a top level PackageReference, exclude all assets:

<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:Next, add your own reference to the appropriate local copy of the DLL:

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