Referencias del paquete (PackageReference) en archivos de proyectoPackage references (PackageReference) in project files

Las referencias de paquetes, con el nodo PackageReference, administran las dependencias de NuGet directamente en los archivos de proyecto (a diferencia de un archivo packages.config independiente).Package references, using the PackageReference node, manage NuGet dependencies directly within project files (as opposed to a separate packages.config file). El uso de PackageReference, como así se llama, no afecta a otros aspectos de NuGet; por ejemplo, las opciones de los archivos NuGet.config (incluidos los orígenes de paquetes) se siguen aplicando como se explica en las configuraciones comunes de NuGet.Using PackageReference, as it's called, doesn't affect other aspects of NuGet; for example, settings in NuGet.config files (including package sources) are still applied as explained in Common NuGet configurations.

Con PackageReference, también puede usar las condiciones de MSBuild para elegir referencias de paquetes por plataforma de destino, configuración, plataforma u otras agrupaciones.With PackageReference, you can also use MSBuild conditions to choose package references per target framework, configuration, platform, or other groupings. También le proporciona un control específico sobre las dependencias y el flujo de contenido.It also allows for fine-grained control over dependencies and content flow. (Para saber más, vea NuGet pack and restore as MSBuild targets (Empaquetado y restauración de NuGet como destinos de MSBuild).(See For more details NuGet pack and restore as MSBuild targets.)

Compatibilidad con tipo de proyectoProject type support

De forma predeterminada, PackageReference se usa para proyectos de .NET Core, proyectos de .NET Standard y proyectos de UWP que tengan como destino Windows 10 Build 15063 (Creators Update) y versiones posteriores, con la excepción de los proyectos de UWP en C++.By default, PackageReference is used for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later, with the exception of C++ UWP projects. Los proyectos de .NET Framework admiten PackageReference, pero actualmente tienen como valor predeterminado packages.config..NET Framework projects support PackageReference, but currently default to packages.config. Para usar PackageReference, migre las dependencias de packages.config al archivo de proyecto y luego quite packages.config.To use PackageReference, migrate the dependencies from packages.config into your project file, then remove packages.config.

Las aplicaciones ASP.NET destinadas a .NET Framework por completo solo incluyen compatibilidad limitada para PackageReference.ASP.NET apps targeting the full .NET Framework include only limited support for PackageReference. Los tipos de proyecto de C++y JavaScript no son compatibles.C++ and JavaScript project types are unsupported.

Agregar una PackageReferenceAdding a PackageReference

Agregue una dependencia en el archivo de proyecto usando la sintaxis siguiente:Add a dependency in your project file using the following syntax:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Controlar la versión de una dependenciaControlling dependency version

La convención para especificar la versión de un paquete es la misma que cuando se usa packages.config:The convention for specifying the version of a package is the same as when using packages.config:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

En el ejemplo anterior, 3.6.0 hace referencia a cualquier versión que sea > = 3.6.0 con preferencia para la versión más antigua, tal como se describe en Package versioning (Control de versiones de paquetes).In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described on Package versioning.

Uso de una PackageReference para un proyecto sin PackageReferencesUsing PackageReference for a project with no PackageReferences

Avanzado: Si no tiene paquetes instalados en un proyecto (ninguna PackageReference en el archivo de proyecto y ningún archivo packages.config), pero quiere que el proyecto se restaure como de estilo PackageReference, puede establecer una propiedad de proyecto RestoreProjectStyle en PackageReference en el archivo de proyecto.Advanced: If you have no packages installed in a project (no PackageReferences in project file and no packages.config file), but want the project to be restored as PackageReference style, you can set a Project property RestoreProjectStyle to PackageReference in your project file.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>    

Esto puede resultar útil si hace referencia a proyectos de estilo PackageReference (csproj existente o proyectos de estilo SDK).This may be useful, if you reference projects which are PackageReference styled (existing csproj or SDK-style projects). Esto permitirá que el proyecto haga referencia "de manera transitiva" a los paquetes a los que hacen referencia dichos proyectos.This will enable packages that those projects refer to, to be "transitively" referenced by your project.

Versiones flotantesFloating Versions

Las versiones flotantes son compatibles con PackageReference:Floating versions are supported with PackageReference:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta*" />
    <!-- ... -->
</ItemGroup>

Controlar los recursos de dependenciasControlling dependency assets

Puede que esté usando una dependencia únicamente como instrumento de desarrollo y no quiera exponerla a proyectos que consumirán el paquete.You might be using a dependency purely as a development harness and might not want to expose that to projects that will consume your package. En este escenario, puede usar los metadatos PrivateAssets para controlar este comportamiento.In this scenario, you can use the PrivateAssets metadata to control this behavior.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Las siguientes etiquetas de metadatos controlan los recursos de dependencia:The following metadata tags control dependency assets:

EtiquetaTag DESCRIPCIÓNDescription Valor predeterminadoDefault Value
IncludeAssetsIncludeAssets Se consumirán estos recursosThese assets will be consumed todoall
ExcludeAssetsExcludeAssets No se consumirán estos recursosThese assets will not be consumed ningunanone
PrivateAssetsPrivateAssets Estos recursos se consumirán, pero no irán al proyecto principalThese assets will be consumed but won't flow to the parent project archivos de contenido; analizadores; compilacióncontentfiles;analyzers;build

A continuación se muestran los valores permitidos para estas etiquetas, con varios valores separados por un punto y coma, salvo all y none, que deben aparecer por sí mismos:Allowable values for these tags are as follows, with multiple values separated by a semicolon except with all and none which must appear by themselves:

ValorValue DESCRIPCIÓNDescription
compilecompile Contenido de la carpeta lib y controla si el proyecto se puede compilar con los ensamblados dentro de la carpetaContents of the lib folder and controls whether your project can compile against the assemblies within the folder
motor en tiempo de ejecuciónruntime Contenido de las carpetas lib y runtimes y controla si estos ensamblados se copiarán en el directorio de salida de compilaciónContents of the lib and runtimes folder and controls whether these assemblies will be copied out to the build output directory
contentFilescontentFiles Contenido de la carpeta contentfilesContents of the contentfiles folder
compilaciónbuild .props y .targets en la carpeta build.props and .targets in the build folder
buildMultitargetingbuildMultitargeting (4.0) .props y .targets en la carpeta buildMultitargeting, para los destinos multiplataforma(4.0) .props and .targets in the buildMultitargeting folder, for cross-framework targeting
buildTransitivebuildTransitive (5.0+) .props y .targets en la carpeta buildTransitive, para los recursos que fluyen de manera transitiva a cualquier proyecto de consumo.(5.0+) .props and .targets in the buildTransitive folder, for assets that flow transitively to any consuming project. Vea la página de la característica.See the feature page.
analyzersanalyzers Analizadores de .NET.NET analyzers
nativasnative Contenido de la carpeta nativeContents of the native folder
ningunanone No se usa ninguno de los anteriores.None of the above are used.
todoall Todo lo anterior (excepto none)All of the above (except none)

En el ejemplo siguiente, todo excepto los archivos de contenido del paquete sería consumido por el proyecto y todo excepto los analizadores y los archivos de contenido iría al proyecto principal.In the following example, everything except the content files from the package would be consumed by the project and everything except content files and analyzers would flow to the parent project.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets>
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Tenga en cuenta que, dado que build no se incluye con PrivateAssets, los destinos y las propiedades irán al proyecto principal.Note that because build is not included with PrivateAssets, targets and props will flow to the parent project. Imagínese, por ejemplo, que la referencia anterior se usa en un proyecto que genera un paquete de NuGet llamado AppLogger.Consider, for example, that the reference above is used in a project that builds a NuGet package called AppLogger. AppLogger puede consumir los destinos y las propiedades de Contoso.Utility.UsefulStuff, igual que los proyectos que consumen AppLogger.AppLogger can consume the targets and props from Contoso.Utility.UsefulStuff, as can projects that consume AppLogger.

Nota

Cuando developmentDependency se establece en true en un archivo .nuspec, esto marca un paquete como una dependencia de solo desarrollo, que impide que el paquete se incluya como una dependencia en otros paquetes.When developmentDependency is set to true in a .nuspec file, this marks a package as a development-only dependency, which prevents the package from being included as a dependency in other packages. Con PackageReference (NuGet 4.8 +) , esta marca también significa que excluirá los recursos en tiempo de compilación de la compilación.With PackageReference (NuGet 4.8+), this flag also means that it will exclude compile-time assets from compilation. Para más información, consulte Compatibilidad de DevelopmentDependency para PackageReference.For more information, see DevelopmentDependency support for PackageReference.

Agregar una condición PackageReferenceAdding a PackageReference condition

Puede usar una condición para controlar si se incluye un paquete, donde las condiciones pueden usar cualquier variable de MSBuild o una variable definida en el archivo de destinos o propiedades.You can use a condition to control whether a package is included, where conditions can use any MSBuild variable or a variable defined in the targets or props file. Pero actualmente solo se admite la variable TargetFramework.However, at presently, only the TargetFramework variable is supported.

Por ejemplo, imagínese que va a fijar como destino netstandard1.4 y net452, pero tiene una dependencia que solo es aplicable a net452.For example, say you're targeting netstandard1.4 as well as net452 but have a dependency that is applicable only for net452. En este caso no quiere que un proyecto netstandard1.4 que está consumiendo el paquete agregue esa dependencia innecesaria.In this case you don't want a netstandard1.4 project that's consuming your package to add that unnecessary dependency. Para evitarlo, especifique una condición en PackageReference como se indica a continuación:To prevent this, you specify a condition on the PackageReference as follows:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

Un paquete creado con este proyecto mostrará que Newtonsoft.Json se incluye como dependencia únicamente para un destino net452:A package built using this project will show that Newtonsoft.Json is included as a dependency only for a net452 target:

El resultado de aplicar una condición en PackageReference con VS2017

Las condiciones también se pueden aplicar a nivel de ItemGroup y se aplicarán a todos los elementos PackageReference secundarios:Conditions can also be applied at the ItemGroup level and will apply to all children PackageReference elements:

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Cargando las dependenciasLocking dependencies

Esta característica está disponible con NuGet 4.9 o superior y con Visual Studio 2017 15.9 o superior.This feature is available with NuGet 4.9 or above and with Visual Studio 2017 15.9 or above.

La entrada a la restauración de NuGet es un conjunto de referencias de paquete del archivo del proyecto (dependencias de nivel superior o directas) y la salida es un cierre completo de todas las dependencias de paquetes, incluidas las dependencias transitivas.Input to NuGet restore is a set of Package References from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. NuGet siempre intenta producir el mismo cierre completo de dependencias de paquetes si no ha cambiado la lista PackageReference de entrada.NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. Sin embargo, hay algunos escenarios en los que no se puede hacer.However, there are some scenarios where it is unable to do so. Por ejemplo:For example:

  • Al usar versiones flotantes como <PackageReference Include="My.Sample.Lib" Version="4.*"/>.When you use floating versions like <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Aunque la intención aquí es hacer flotante la última versión de todas las restauraciones de paquetes, hay escenarios en los que los usuarios necesitan que el gráfico se bloquee hacia una versión más reciente determinada y hacen flotante una versión posterior, en caso de estar disponible, en un gesto explícito.While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture.

  • Se publica una versión más reciente del paquete que coincide con los requisitos de la versión PackageReference.A newer version of the package matching PackageReference version requirements is published. P. ej.,E.g.

    • Día 1: si especificó <PackageReference Include="My.Sample.Lib" Version="4.0.0"/>, pero las versiones disponibles en los repositorios NuGet eran 4.1.0, 4.2.0 y 4.3.0.Day 1: if you specified <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> but the versions available on the NuGet repositories were 4.1.0, 4.2.0 and 4.3.0. En este caso, NuGet habría llevado a cabo la resolución de la versión 4.1.0 (la versión mínima más cercana)In this case, NuGet would have resolved to 4.1.0 (nearest minimum version)

    • Día 2: Se publica la versión 4.0.0.Day 2: Version 4.0.0 gets published. Ahora, NuGet encontrará la coincidencia exacta e iniciará la resolución de la versión 4.0.0NuGet will now find the exact match and start resolving to 4.0.0

  • Se quita una versión del paquete especificada del repositorio.A given package version is removed from the repository. Aunque nuget.org no permite la eliminación de paquetes, no todos los repositorios de paquetes tienen estas restricciones.Though nuget.org does not allow package deletions, not all package repositories have this constraints. Esto da lugar a la búsqueda por parte de NuGet de la mejor coincidencia cuando no puede llevar a cabo la resolución de la versión eliminada.This results in NuGet finding the best match when it cannot resolve to the deleted version.

Habilitación del archivo de bloqueoEnabling lock file

A fin de mantener el cierre completo de dependencias de paquetes, puede participar en la característica del archivo de bloqueo estableciendo la propiedad MSBuild RestorePackagesWithLockFile para su proyecto:In order to persist the full closure of package dependencies you can opt-in to the lock file feature by setting the MSBuild property RestorePackagesWithLockFile for your project:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>    

Si se establece esta propiedad, la restauración de NuGet generará un archivo de bloqueo: archivo packages.lock.json del directorio raíz del proyecto que incluye todas las dependencias de paquetes.If this property is set, NuGet restore will generate a lock file - packages.lock.json file at the project root directory that lists all the package dependencies.

Nota

Una vez que un proyecto tiene el archivo packages.lock.json en su directorio raíz, el archivo de bloqueo siempre se usa con la restauración incluso si no se establece la propiedad RestorePackagesWithLockFile.Once a project has packages.lock.json file in its root directory, the lock file is always used with restore even if the property RestorePackagesWithLockFile is not set. Así pues, otra forma de participar en esta característica consiste en crear un archivo packages.lock.json en blanco ficticio en el directorio raíz del proyecto.So another way to opt-in to this feature is to create a dummy blank packages.lock.json file in the project's root directory.

Comportamiento restore con el archivo de bloqueorestore behavior with lock file

Si un archivo de bloqueo está presente para el proyecto, NuGet usa este archivo de bloqueo para ejecutar restore.If a lock file is present for project, NuGet uses this lock file to run restore. NuGet realiza una rápida comprobación para ver si hubo algún cambio en las dependencias de paquetes tal como se mencionó en el archivo del proyecto (o archivos de los proyectos dependientes) y, en caso de no haber ningún cambio, simplemente restaura los paquetes mencionados en el archivo de bloqueo.NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files) and if there were no changes it just restores the packages mentioned in the lock file. No hay ninguna reevaluación de dependencias de paquetes.There is no re-evaluation of package dependencies.

Si NuGet detecta un cambio en las dependencias definidas tal como se menciona en los archivos del proyecto, volverá a evaluar el gráfico del paquete y actualizará el archivo de bloqueo para reflejar el nuevo cierre del paquete para el proyecto.If NuGet detects a change in the defined dependencies as mentioned in the project file(s), it re-evaluates the package graph and updates the lock file to reflect the new package closure for the project.

En CI/CD y otros escenarios, en los que no desearía cambiar las dependencias de paquetes en el camino, puede hacerlo estableciendo lockedmode en true:For CI/CD and other scenarios, where you would not want to change the package dependencies on the fly, you can do so by setting the lockedmode to true:

En dotnet.exe,ejecute:For dotnet.exe, run:

> dotnet.exe restore --locked-mode

En msbuild.exe, ejecute:For msbuild.exe, run:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

También puede establecer esta propiedad MSBuild condicional en su archivo del proyecto:You may also set this conditional MSBuild property in your project file:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup> 

Si el modo de bloqueo es true, la restauración restaurará los paquetes exactos tal como se incluyen en el archivo de bloqueo o producirá un error si actualizó las dependencias de paquetes definidas para el proyecto tras crearse el archivo de bloqueo.If locked mode is true, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created.

Haga que el archivo de bloqueo forme parte de su repositorio de origenMake lock file part of your source repository

Si crea una aplicación, un archivo ejecutable y el proyecto en cuestión se encuentra al principio de la cadena de dependencia, inserte el archivo de bloqueo en el repositorio de código fuente para que NuGet pueda hacer uso de este durante la restauración.If you are building an application, an executable and the project in question is at the start of the dependency chain then do check in the lock file to the source code repository so that NuGet can make use of it during restore.

Sin embargo, si su proyecto es un proyecto de biblioteca que no envía o un proyecto de código común del que dependen otros proyectos, no debe insertar en el repositorio el archivo de bloqueo como parte de su código fuente.However, if your project is a library project that you do not ship or a common code project on which other projects depend upon, you should not check in the lock file as part of your source code. No hay nada malo en el hecho de conservar el archivo de bloqueo, pero es posible que no se usen las dependencias de paquetes bloqueadas para el proyecto de código común, como se muestra en el archivo de bloqueo, durante la restauración/creación de un proyecto que depende de este proyecto de código común.There is no harm in keeping the lock file but the locked package dependencies for the common code project may not be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project.

EjemploEg.

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Si ProjectA tiene una dependencia de la versión 2.0.0 de PackageX y también hace referencia a ProjectB, que depende de la versión 1.0.0 de PackageX, el archivo de bloqueo para ProjectB mostrará una dependencia de la versión 1.0.0 de PackageX.If ProjectA has a dependency on a PackageX version 2.0.0 and also references ProjectB that depends on PackageX version 1.0.0, then the lock file for ProjectB will list a dependency on PackageX version 1.0.0. Sin embargo, al crearse ProjectA, su archivo de bloqueo contendrá una dependencia de la versión 2.0.0 de PackageX y no 1.0.0 como se muestra en el archivo de bloqueo para ProjectB.However, when ProjectA is built, its lock file will contain a dependency on PackageX version 2.0.0 and not 1.0.0 as listed in the lock file for ProjectB. Por tanto, el archivo de bloqueo de un proyecto de código común tiene poco que decir sobre los paquetes resueltos para los proyectos que dependen de él.Thus, the lock file of a common code project has little say over the packages resolved for projects that depend on it.

Extensibilidad del archivo de bloqueoLock file extensibility

Puede controlar diversos comportamientos de la restauración con el archivo de bloqueo como se describe a continuación:You can control various behaviors of restore with lock file as described below:

OpciónOption Opción equivalente de MSBuildMSBuild equivalent option
--use-lock-file Uso de arranques del archivo de bloqueo para un proyecto.Bootstraps use of lock file for a project. De forma alternativa, puede establecer la propiedad RestorePackagesWithLockFile en el archivo del proyectoYou can alternatively set RestorePackagesWithLockFile property in the project file
--locked-mode Habilita el modo de bloqueo para la restauración.Enables locked mode for restore. Esto resulta útil en los escenarios de CI/CD en los que desea obtener las compilaciones repetibles.This is useful in CI/CD scenarios where you would like to get the repeatable builds. También puede ser estableciendo la propiedad MSBuild RestoreLockedMode en trueThis can be also by setting the RestoreLockedMode MSBuild property to true
--force-evaluate Esta opción es útil con los paquetes con la versión flotante definida en el proyecto.This option is useful with packages with floating version defined in the project. De forma predeterminada, la restauración de NuGet no actualizará la versión del paquete automáticamente tras cada restauración a menos que ejecute esta con la opción --force-evaluate.By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with --force-evaluate option.
--lock-file-path Define una ubicación del archivo de bloqueo personalizada para un proyecto.Defines a custom lock file location for a project. Esto también puede lograrse estableciendo la propiedad MSBuild NuGetLockFilePath.This can be also achieved by setting the MSBuild property NuGetLockFilePath. De forma predeterminada, NuGet admite packages.lock.json en el directorio raíz.By default, NuGet supports packages.lock.json at the root directory. Si tiene varios proyectos en el mismo directorio, NuGet admite el archivo de bloqueo específico del proyecto packages.<project_name>.lock.jsonIf you have multiple projects in the same directory, NuGet supports project specific lock file packages.<project_name>.lock.json