Referencia de .nuspec.nuspec reference

Un archivo .nuspec es un manifiesto XML que contiene metadatos de paquete.A .nuspec file is an XML manifest that contains package metadata. Este manifiesto se usa para crear el paquete y para proporcionar información a los consumidores.This manifest is used both to build the package and to provide information to consumers. El manifiesto siempre se incluye en un paquete.The manifest is always included in a package.

En este tema:In this topic:

Esquema y forma generalGeneral form and schema

El archivo de esquema nuspec.xsd actual se encuentra en el repositorio NuGet de GitHub.The current nuspec.xsd schema file can be found in the NuGet GitHub repository.

En este esquema, los archivos .nuspec tienen el siguiente formato general:Within this schema, a .nuspec file has the following general form:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

Para tener una representación visual clara del esquema, abra el archivo de esquema en Visual Studio en modo de diseño y haga clic en el vínculo Explorador de esquemas XML.For a clear visual representation of the schema, open the schema file in Visual Studio in Design mode and click on the XML Schema Explorer link. Como alternativa, abra el archivo como código, haga clic con el botón derecho en el editor y seleccione Mostrar en el Explorador de esquemas XML.Alternately, open the file as code, right-click in the editor, and select Show XML Schema Explorer. En cualquier caso, obtendrá una vista como la siguiente (cuando esté expandida en su mayoría):Either way you get a view like the one below (when mostly expanded):

Explorador de esquemas de Visual Studio con nuspec.xsd abierto

Elementos de metadatos necesariosRequired metadata elements

Aunque los elementos siguientes son los requisitos mínimos de un paquete, debe plantearse la posibilidad de agregar los elementos de metadatos opcionales para mejorar la experiencia general que tienen los desarrolladores con el paquete.Although the following elements are the minimum requirements for a package, you should consider adding the optional metadata elements to improve the overall experience developers have with your package.

Estos elementos deben aparecer dentro de un elemento <metadata>.These elements must appear within a <metadata> element.

idid

El identificador del paquete que no distingue entre mayúsculas y minúsculas, que debe ser único en nuget.org o en cualquier galería en la que resida el paquete.The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package resides in. Los identificadores no pueden contener espacios ni caracteres no válidos para una dirección URL y normalmente seguirán las reglas de espacios de nombres de .NET.IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules. Vea Choosing a unique package identifier (Elegir un identificador de paquete único) para obtener instrucciones.See Choosing a unique package identifier for guidance.

versionversion

La versión del paquete, siguiendo el patrón mayor.menor.revisión.The version of the package, following the major.minor.patch pattern. Los números de versión pueden incluir un sufijo de versión preliminar, tal y como se describe en Control de versiones de paquetes.Version numbers may include a pre-release suffix as described in Package versioning.

Descripcióndescription

Una descripción larga del paquete para su visualización en la interfaz de usuario.A long description of the package for UI display.

authorsauthors

Una lista separada por comas de los autores de los paquetes, que coinciden con los nombres de perfil de nuget.org. Estos se muestran en la galería de NuGet, en nuget.org, y se usan para hacer referencias cruzadas a paquetes de los mismos autores.A comma-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.

Elementos de metadatos opcionalesOptional metadata elements

títulotitle

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.A human-friendly title of the package, typically used in UI displays as on nuget.org and the Package Manager in Visual Studio. Si no se especifica, se usa el identificador del paquete.If not specified, the package ID is used.

ownersowners

Lista separada por comas de los creadores del paquete usando nombres de perfil en nuget.org. Suele ser la misma lista que en authors y se ignora al cargar el paquete en nuget.org. Vea Administrar los propietarios de paquetes en nuget.org.A comma-separated list of the package creators using profile names on nuget.org. This is often the same list as in authors, and is ignored when uploading the package to nuget.org. See Managing package owners on nuget.org.

projectUrlprojectUrl

Una dirección URL de la página principal del paquete, que a menudo se muestra en las visualizaciones de la interfaz de usuario, así como en nuget.org.A URL for the package's home page, often shown in UI displays as well as nuget.org.

licenseUrllicenseUrl

Dirección URL de la licencia del paquete, que a menudo se muestra en las visualizaciones de la interfaz de usuario, así como en nuget.org.A URL for the package's license, often shown in UI displays as well as nuget.org.

iconUrliconUrl

Dirección URL para una imagen de 64 x 64 con fondo transparente para usarla como icono para el paquete en la visualización de la interfaz de usuario.A URL for a 64x64 image with transparency background to use as the icon for the package in UI display. Asegúrese de que este elemento contiene la dirección URL directa a la imagen y no la dirección URL de una página web que contiene la imagen.Be sure this element contains the direct image URL and not the URL of a web page containing the image. Por ejemplo, para utilizar una imagen desde GitHub, use el archivo sin formato, como la dirección URL https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.For example, to use an image from GitHub, use the raw file URL like https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.

requireLicenseAcceptancerequireLicenseAcceptance

Valor booleano que especifica si el cliente debe pedir al consumidor que acepte la licencia del paquete antes de instalarlo.A Boolean value specifying whether the client must prompt the consumer to accept the package license before installing the package.

developmentDependencydevelopmentDependency

(2.8+) 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.(2.8+) A Boolean value specifying whether the package is be marked as a development-only-dependency, which prevents the package from being included as a dependency in other packages.

resumensummary

Descripción breve del paquete para su visualización en la interfaz de usuario.A short description of the package for UI display. Si se omite, se usará una versión truncada de description.If omitted, a truncated version of description is used.

releaseNotesreleaseNotes

(1.5+) Descripción de los cambios efectuados en esta versión del paquete. A menudo se usa en la interfaz de usuario como la pestaña Actualizaciones del Administrador de paquetes de Visual Studio, en lugar de la descripción del paquete.(1.5+) A description of the changes made in this release of the package, often used in UI like the Updates tab of the Visual Studio Package Manager in place of the package description.

(1.5+) Información de copyright del paquete.(1.5+) Copyright details for the package.

lenguajelanguage

Identificador de configuración regional del paquete.The locale ID for the package. Vea Creación de paquetes localizados.See Creating localized packages.

etiquetastags

Lista de etiquetas y palabras clave, delimitadas por espacios, que describen el paquete y ayudan a detectar los paquetes a través de búsquedas y filtrados.A space-delimited list of tags and keywords that describe the package and aid discoverability of packages through search and filtering.

posibilidad de mantenimientoserviceable

(3.3+) Solo para uso interno de NuGet.(3.3+) For internal NuGet use only.

repositoriorepository

Repositorio de metadatos, que consta de cuatro atributos opcionales: tipo y url (4.0 y versiones posteriores), y rama y confirmación (4.6 y versiones posteriores).Repository metadata, consisting of four optional attributes: type and url (4.0+), and branch and commit (4.6+). Estos atributos permiten asignar los archivos .nupkg en el repositorio que se crearon, con la posibilidad de obtener tal como se detalla como la rama individual o la confirmación de que se creó el paquete.These attributes allow you to map the .nupkg to the repository that built it, with the potential to get as detailed as the individual branch or commit that built the package. Debe ser una dirección url disponible públicamente que se puede invocar directamente mediante un software de control de versión.This should be a publicly available url that can be invoked directly by a version control software. No debe ser una página html tal como está pensado para el equipo.It should not be an html page as this is meant for the computer. Para vincular a la página del proyecto, use el projectUrl campo, en su lugar.For linking to project page, use the projectUrl field, instead.

MinClientVersionminClientVersion

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.Specifies the minimum version of the NuGet client that can install this package, enforced by nuget.exe and the Visual Studio Package Manager. Se usa siempre que el paquete depende de características específicas del archivo .nuspec que se agregaron en una versión concreta del cliente de NuGet.This is used whenever the package depends on specific features of the .nuspec file that were added in a particular version of the NuGet client. Por ejemplo, un paquete que usa el atributo developmentDependency debería especificar "2.8" para minClientVersion.For example, a package using the developmentDependency attribute should specify "2.8" for minClientVersion. Asimismo, un paquete que usa el elemento contentFiles (vea la sección siguiente) debería establecer minClientVersion en "3.3".Similarly, a package using the contentFiles element (see the next section) should set minClientVersion to "3.3". Observe también que, debido a que los clientes de NuGet anteriores a la versión 2.5 no reconocen esta marca, siempre rechazan instalar el paquete, independientemente de lo que contenga minClientVersion.Note also that because NuGet clients prior to 2.5 do not recognize this flag, they always refuse to install the package no matter what minClientVersion contains.

Elementos de colecciónCollection elements

PackageTypespackageTypes

(3.5+) Colección de cero o más elementos <packageType> que especifican el tipo del paquete si es distinto de un paquete de dependencias tradicional.(3.5+) A collection of zero or more <packageType> elements specifying the type of the package if other than a traditional dependency package. Cada tipo de paquete tiene atributos de name y version.Each packageType has attributes of name and version. Vea Establecimiento de un tipo de paquete.See Setting a package type.

dependenciasdependencies

Colección de cero o más elementos <dependency> que especifican las dependencias del paquete.A collection of zero or more <dependency> elements specifying the dependencies for the package. Cada dependencia tiene atributos de id, version, include (3.x+) y exclude (3.x+).Each dependency has attributes of id, version, include (3.x+), and exclude (3.x+). Vea Dependencias a continuación.See Dependencies below.

frameworkAssembliesframeworkAssemblies

(1.2+) Colección de cero o más elementos <frameworkAssembly> que identifican las referencias de ensamblado de .NET Framework que requiere este paquete, lo que garantiza que se agreguen las referencias a los proyectos que consumen el paquete.(1.2+) A collection of zero or more <frameworkAssembly> elements identifying .NET Framework assembly references that this package requires, which ensures that references are added to projects consuming the package. Cada frameworkAssembly tiene atributos assemblyName y targetFramework.Each frameworkAssembly has assemblyName and targetFramework attributes. Vea Referencias de ensamblado de plataforma a continuación.See Specifying framework assembly references GAC below. |

referenciasreferences

(1.5+) Colección de cero o más elementos <reference> que nombran ensamblados en la carpeta lib del paquete que se agregan como referencias de proyecto.(1.5+) A collection of zero or more <reference> elements naming assemblies in the package's lib folder that are added as project references. Cada referencia tiene un atributo file.Each reference has a file attribute. <references> también puede contener un elemento <group> con un atributo targetFramework, que contiene elementos <reference>.<references> can also contain a <group> element with a targetFramework attribute, that then contains <reference> elements. Si se omite, se incluyen todas las referencias de lib.If omitted, all references in lib are included. Vea Referencias de ensamblado explícitas a continuación.See Specifying explicit assembly references below.

contentFilescontentFiles

(3.3+) Colección de elementos <files> que identifican archivos de contenido que se incluirán en el proyecto de consumo.(3.3+) A collection of <files> elements that identify content files to include in the consuming project. Estos archivos se especifican con un conjunto de atributos que describen cómo se deben usar en el sistema del proyecto.These files are specified with a set of attributes that describe how they should be used within the project system. Vea Incluir archivos de ensamblado a continuación.See Specifying files to include in the package below.

archivosfiles

El nodo <package> puede contener un nodo <files> como un elemento del mismo nivel de <metadata>, o un elemento secundario <contentFiles> en <metadata>, para especificar los archivos de contenido y de ensamblado que se deben incluir en el paquete.The <package> node may contain a <files> node as a sibling to <metadata>, and a or <contentFiles> child under <metadata>, to specify which assembly and content files to include in the package. Vea las secciones Incluir archivos de ensamblado e Incluir archivos de contenido, que aparecen más adelante en este tema, para más información.See Including assembly files and Including content files later in this topic for details.

Tokens de reemplazoReplacement tokens

Al crear un paquete, el comando nuget pack reemplaza los tokens delimitados por $ en el nodo <metadata> del archivo .nuspec por valores procedentes de un archivo de proyecto o del conmutador -properties del comando pack.When creating a package, the nuget pack command replaces $-delimited tokens in the .nuspec file's <metadata> node with values that come from either a project file or the pack command's -properties switch.

En la línea de comandos, especifique valores de token con nuget pack -properties <name>=<value>;<name>=<value>.On the command line, you specify token values with nuget pack -properties <name>=<value>;<name>=<value>. Por ejemplo, puede usar un token como $owners$ y $desc$ en .nuspec y proporcionar los valores en el momento del empaquetado del siguiente modo:For example, you can use a token such as $owners$ and $desc$ in the .nuspec and provide the values at packing time as follows:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Para usar valores de un proyecto, especifique los tokens que se describen en la siguiente tabla (AssemblyInfo hace referencia al archivo de Properties, como AssemblyInfo.cs o AssemblyInfo.vb).To use values from a project, specify the tokens described in the table below (AssemblyInfo refers to the file in Properties such as AssemblyInfo.cs or AssemblyInfo.vb).

Para usar estos tokens, ejecute nuget pack con el archivo de proyecto en lugar de hacerlo solo con el archivo .nuspec.To use these tokens, run nuget pack with the project file rather than just the .nuspec. Por ejemplo, al usar el siguiente comando, los tokens $id$ y $version$ de un archivo .nuspec se reemplazan por los valores AssemblyName y AssemblyVersion del proyecto:For example, when using the following command, the $id$ and $version$ tokens in a .nuspec file are replaced with the project's AssemblyName and AssemblyVersion values:

nuget pack MyProject.csproj

Normalmente, cuando tiene un proyecto, crea el archivo .nuspec al principio con nuget spec MyProject.csproj, que incluye automáticamente algunos de estos tokens estándares.Typically, when you have a project, you create the .nuspec initially using nuget spec MyProject.csproj which automatically includes some of these standard tokens. Pero si a un proyecto le faltan valores de elementos .nuspec necesarios, se producirá un error en nuget pack.However, if a project lacks values for required .nuspec elements, then nuget pack fails. Además, si cambia los valores del proyecto, asegúrese de efectuar una recompilación antes de crear el paquete. Lo puede hacer cómodamente con el conmutador build del comando pack.Furthermore, if you change project values, be sure to rebuild before creating the package; this can be done conveniently with the pack command's build switch.

Con la excepción de $configuration$, se usan los valores del proyecto con preferencia a cualquier valor asignado al mismo token en la línea de comandos.With the exception of $configuration$, values in the project are used in preference to any assigned to the same token on the command line.

TokenToken Origen del valorValue source ValorValue
$id$$id$ Archivo del proyectoProject file AssemblyName (título) del archivo de proyectoAssemblyName (title) from the project file
$version$$version$ AssemblyInfoAssemblyInfo AssemblyInformationalVersion si está presente. En caso contrario, AssemblyVersionAssemblyInformationalVersion if present, otherwise AssemblyVersion
$author$$author$ AssemblyInfoAssemblyInfo AssemblyCompanyAssemblyCompany
$title$$title$ AssemblyInfoAssemblyInfo AssemblyTitleAssemblyTitle
$description$$description$ AssemblyInfoAssemblyInfo AssemblyDescriptionAssemblyDescription
$copyright$$copyright$ AssemblyInfoAssemblyInfo AssemblyCopyrightAssemblyCopyright
$configuration$$configuration$ Archivo DLL del ensambladoAssembly DLL Configuración usada para compilar el ensamblado. El valor predeterminado es Depurar.Configuration used to build the assembly, defaulting to Debug. Tenga en cuenta que, para crear un paquete con una configuración Release, siempre debe usar -properties Configuration=Release en la línea de comandos.Note that to create a package using a Release configuration, you always use -properties Configuration=Release on the command line.

Los tokens también se pueden usar para resolver rutas de acceso cuando se incluyen archivos de ensamblado y archivos de contenido.Tokens can also be used to resolve paths when you include assembly files and content files. Los tokens tienen los mismos nombres que las propiedades de MSBuild, lo que permite seleccionar archivos que se van a incluir en función de la configuración de compilación actual.The tokens have the same names as the MSBuild properties, making it possible to select files to be included depending on the current build configuration. Por ejemplo, si usa los tokens siguientes en el archivo .nuspec:For example, if you use the following tokens in the .nuspec file:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

Y compila un ensamblado cuyo AssemblyName es LoggingLibrary con la configuración Release en MSBuild, las líneas resultantes en el archivo .nuspec del paquete serán las siguientes:And you build an assembly whose AssemblyName is LoggingLibrary with the Release configuration in MSBuild, the resulting lines in the .nuspec file in the package is as follows:

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Elemento de dependenciasDependencies element

El elemento <dependencies> dentro de <metadata> contiene cualquier número de elementos <dependency> que identifican otros paquetes de los que depende el paquete de nivel superior.The <dependencies> element within <metadata> contains any number of <dependency> elements that identify other packages upon which the top-level package depends. Los atributos de cada <dependency> son los siguientes:The attributes for each <dependency> are as follows:

AtributoAttribute DescripciónDescription
id (Obligatorio) El identificador de paquete de la dependencia, como "EntityFramework" y "NUnit", que es el nombre del paquete nuget.org que se muestra en una página del paquete.(Required) The package ID of the dependency, such as "EntityFramework" and "NUnit", which is the name of the package nuget.org shows on a package page.
version (Obligatorio) Intervalo de versiones aceptable como dependencia.(Required) The range of versions acceptable as a dependency. Vea Control de versiones de paquetes para consultar la sintaxis exacta.See Package versioning for exact syntax.
includeinclude Lista delimitada por comas de etiquetas de inclusión/exclusión (vea más abajo) que indican la dependencia que se va a incluir en el paquete final.A comma-delimited list of include/exclude tags (see below) indicating of the dependency to include in the final package. El valor predeterminado es all.The default value is all.
excludeexclude Lista delimitada por comas de etiquetas de inclusión/exclusión (vea más abajo) que indican la dependencia que se va a excluir en el paquete final.A comma-delimited list of include/exclude tags (see below) indicating of the dependency to exclude in the final package. El valor predeterminado es build,analyzers que puede que se sobrescriban.The default value is build,analyzers which can be over-written. Pero content/ ContentFiles implícitamente también se excluyen en el paquete final que no se sobrescribe.But content/ ContentFiles are also implicitly excluded in the final package which can't be over-written. Las etiquetas especificadas con exclude tienen prioridad sobre las que se especifican con include.Tags specified with exclude take precedence over those specified with include. Por ejemplo, include="runtime, compile" exclude="compile" es lo mismo que include="runtime".For example, include="runtime, compile" exclude="compile" is the same as include="runtime".
Etiqueta Include o ExcludeInclude/Exclude tag Carpetas afectadas del destinoAffected folders of the target
contentFilescontentFiles ContenidoContent
motor en tiempo de ejecuciónruntime Runtime, Resources y FrameworkAssembliesRuntime, Resources, and FrameworkAssemblies
compilecompile liblib
compilaciónbuild build (propiedades y destinos de MSBuild)build (MSBuild props and targets)
nativasnative nativasnative
ningunanone Sin carpetasNo folders
todoall Todas las carpetasAll folders

Por ejemplo, las siguientes líneas indican las dependencias en PackageA versión 1.1.0 o posterior y en PackageB versión 1.x.For example, the following lines indicate dependencies on PackageA version 1.1.0 or higher, and PackageB version 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

Las líneas siguientes indican dependencias en los mismos paquetes, pero especifican que se deben incluir las carpetas contentFiles y build de PackageA y todo el contenido salvo las carpetas native y compile de PackageB.The following lines indicate dependencies on the same packages, but specify to include the contentFiles and build folders of PackageA and everything but the native and compile folders of PackageB"

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Nota: al crear un archivo .nuspec a partir de un proyecto mediante nuget spec, las dependencias que existen en ese proyecto se incluyen automáticamente en el archivo .nuspec resultante.Note: When creating a .nuspec from a project using nuget spec, dependencies that exist in that project are automatically included in the resulting .nuspec file.

Grupos de dependenciaDependency groups

Versión 2.0+Version 2.0+

Como alternativa a una lista plana, se pueden especificar dependencias según el perfil de plataforma del proyecto de destino usando elementos <group> dentro de <dependencies>.As an alternative to a single flat list, dependencies can be specified according to the framework profile of the target project using <group> elements within <dependencies>.

Cada grupo tiene un atributo denominado targetFramework y contiene cero o más elementos <dependency>.Each group has an attribute named targetFramework and contains zero or more <dependency> elements. Estas dependencias se instalan conjuntamente cuando la plataforma de destino es compatible con el perfil de plataforma del proyecto.Those dependencies are installed together when the target framework is compatible with the project's framework profile.

El elemento <group> sin un atributo targetFramework se usa como la lista de reserva o predeterminada de dependencias.The <group> element without a targetFramework attribute is used as the default or fallback list of dependencies. Vea Target frameworks (Plataformas de destino) para ver los identificadores de plataforma exactos.See Target frameworks for the exact framework identifiers.

Importante

El formato del grupo no se puede combinar con una lista plana.The group format cannot be intermixed with a flat list.

En el ejemplo siguiente se muestran diferentes variaciones del elemento <group>:The following example shows different variations of the <group> element:

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework="net40">
        <dependency id="jQuery" />
        <dependency id="WebActivator" />
    </group>

    <group targetFramework="sl30">
    </group>
</dependencies>

Referencias de ensamblado explícitasExplicit assembly references

El elemento <references> especifica explícitamente los ensamblados a los que debe hacer referencia el proyecto de destino al usar el paquete.The <references> element explicitly specifies the assemblies that the target project should reference when using the package. Cuando este elemento está presente, NuGet agrega referencias únicamente a los ensamblados enumerados. No agrega referencias a otros ensamblados en la carpeta lib del paquete.When this element is present, NuGet add references to only the listed assemblies; it does not add references for any other assemblies in the package's lib folder.

Por ejemplo, el siguiente elemento <references> indica a NuGet que agregue referencias solo a xunit.dll y xunit.extensions.dll, incluso si hay ensamblados adicionales en el paquete:For example, the following <references> element instructs NuGet to add references to only xunit.dll and xunit.extensions.dll even if there are additional assemblies in the package:

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Las referencias explícitas se suelen usar para ensamblados que solo son de tiempo de diseño.Explicit references are typically used for design-time only assemblies. Al usar contratos de código, por ejemplo, los ensamblados de contrato deben estar junto a los ensamblados en tiempo de ejecución que alimentan de manera que Visual Studio los pueda encontrar, pero no es necesario que el proyecto haga referencia a los ensamblados de contrato ni que se copien en la carpeta bin del proyecto.When using Code Contracts, for example, contract assemblies need to be next to the runtime assemblies that they augment so that Visual Studio can find them, but the contract assemblies need not be referenced by the project or copied into the project's bin folder.

De forma parecida, las referencias explícitas se pueden usar para los marcos de pruebas unitarias, como XUnit, que necesita que sus ensamblados de herramientas estén situados junto a los ensamblados en tiempo de ejecución, pero no necesita que se incluyan como referencias de proyecto.Similarly, explicit references can be used for unit test frameworks, such as XUnit, which needs its tools assemblies located next to the runtime assemblies, but does not need them included as project references.

Grupos de referenciasReference groups

Como alternativa a una lista plana, se pueden especificar referencias según el perfil de plataforma del proyecto de destino usando elementos <group> dentro de <references>.As an alternative to a single flat list, references can be specified according to the framework profile of the target project using <group> elements within <references>.

Cada grupo tiene un atributo denominado targetFramework y contiene cero o más elementos <reference>.Each group has an attribute named targetFramework and contains zero or more <reference> elements. Estas referencias se agregan a un proyecto cuando la plataforma de destino es compatible con el perfil de plataforma del proyecto.Those references are added to a project when the target framework is compatible with the project's framework profile.

El elemento <group> sin un atributo targetFramework se usa como la lista de reserva o predeterminada de referencias.The <group> element without a targetFramework attribute is used as the default or fallback list of references. Vea Target frameworks (Plataformas de destino) para ver los identificadores de plataforma exactos.See Target frameworks for the exact framework identifiers.

Importante

El formato del grupo no se puede combinar con una lista plana.The group format cannot be intermixed with a flat list.

En el ejemplo siguiente se muestran diferentes variaciones del elemento <group>:The following example shows different variations of the <group> element:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Referencias de ensamblado de plataformaFramework assembly references

Los ensamblados de plataforma son aquellos que forman parte de .NET Framework y que ya deberían estar en la caché global de ensamblados (GAC) de cualquier equipo.Framework assemblies are those that are part of the .NET framework and should already be in the global assembly cache (GAC) for any given machine. Mediante la identificación de esos ensamblados dentro del elemento <frameworkAssemblies>, un paquete puede asegurarse de que se agreguen las referencias necesarias a un proyecto en caso de que el proyecto no tenga ya dichas referencias.By identifying those assemblies within the <frameworkAssemblies> element, a package can ensure that required references are added to a project in the event that the project doesn't have such references already. Estos ensamblados, por supuesto, no se incluyen directamente en un paquete.Such assemblies, of course, are not included in a package directly.

El elemento <frameworkAssemblies> contiene cero o más elementos <frameworkAssembly>, cada uno de los cuales especifica los siguientes atributos:The <frameworkAssemblies> element contains zero or more <frameworkAssembly> elements, each of which specifies the following attributes:

AtributoAttribute DescripciónDescription
assemblyNameassemblyName (Obligatorio) Nombre completo del ensamblado.(Required) The fully qualified assembly name.
targetFrameworktargetFramework (Opcional) Especifica la plataforma de destino a la que se aplica esta referencia.(Optional) Specifies the target framework to which this reference applies. Si se omite, indica que la referencia se aplica a todas las plataformas.If omitted, indicates that the reference applies to all frameworks. Vea Target frameworks (Plataformas de destino) para ver los identificadores de plataforma exactos.See Target frameworks for the exact framework identifiers.

En el ejemplo siguiente se muestra una referencia a System.Net para todas las plataformas de destino y una referencia a System.ServiceModel solo para .NET Framework 4.0:The following example shows a reference to System.Net for all target frameworks, and a reference to System.ServiceModel for .NET Framework 4.0 only:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Incluir archivos de ensambladoIncluding assembly files

Si sigue las convenciones descritas en Creating a Package (Crear un paquete), no es necesario que especifique explícitamente una lista de archivos en el archivo .nuspec.If you follow the conventions described in Creating a Package, you do not have to explicitly specify a list of files in the .nuspec file. El comando nuget pack selecciona automáticamente los archivos necesarios.The nuget pack command automatically picks up the necessary files.

Importante

Cuando se instala un paquete en un proyecto, NuGet agrega automáticamente las referencias de ensamblado a los archivos DLL del paquete, excepto los que se denominan .resources.dll porque se supone que son ensamblados satélite localizados.When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies. Por esta razón, evite usar .resources.dll para los archivos que, en otros casos, contienen código esencial del paquete.For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

Para omitir este comportamiento automático y controlar explícitamente los archivos que se incluyen en un paquete, coloque un elemento <files> como elemento secundario de <package> (y un elemento del mismo nivel de <metadata>), identificando cada archivo con un elemento <file> independiente.To bypass this automatic behavior and explicitly control which files are included in a package, place a <files> element as a child of <package> (and a sibling of <metadata>), identifying each file with a separate <file> element. Por ejemplo:For example:

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

Con NuGet 2.x y versiones anteriores, así como en los proyectos que usan packages.config, el elemento <files> también se usa para incluir archivos de contenido inmutable cuando se instala un paquete.With NuGet 2.x and earlier, and projects using packages.config, the <files> element is also used to include immutable content files when a package is installed. Con NuGet 3.3+ y los proyectos que usan PackageReference, se usa el elemento <contentFiles> en su lugar.With NuGet 3.3+ and projects PackageReference, the <contentFiles> element is used instead. Vea Incluir archivos de contenido a continuación para más información.See Including content files below for details.

Atributos del elemento FileFile element attributes

Cada elemento <file> especifica los siguientes atributos:Each <file> element specifies the following attributes:

AtributoAttribute DescripciónDescription
srcsrc Ubicación de los archivos que se deben incluir, sujeta a exclusiones especificadas por el atributo exclude.The location of the file or files to include, subject to exclusions specified by the exclude attribute. La ruta de acceso es relativa al archivo .nuspec, a menos que se especifique una ruta de acceso absoluta.The path is relative to the .nuspec file unless an absolute path is specified. El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
targettarget La ruta de acceso relativa a la carpeta del paquete donde se colocan los archivos de código fuente, que debe comenzar por lib, content, build o tools.The relative path to the folder within the package where the source files are placed, which must begin with lib, content, build, or tools. Vea Creating a .nuspec from a convention-based working directory (Crear un archivo .nuspec desde un directorio de trabajo basado en convenciones).See Creating a .nuspec from a convention-based working directory.
excludeexclude Una lista delimitada por punto y coma de archivos o patrones de archivo que se deben excluir de la ubicación src.A semicolon-delimited list of files or file patterns to exclude from the src location. El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.

EjemplosExamples

Ensamblado únicoSingle assembly

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Ensamblado único específico para una plataforma de destinoSingle assembly specific to a target framework

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

Conjunto de archivos DLL que usan un carácter comodínSet of DLLs using a wildcard

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

Archivos DLL para distintas plataformasDLLs for different frameworks

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Archivos de exclusiónExcluding files

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Incluir archivos de contenidoIncluding content files

Los archivos de contenido son archivos inmutables que un paquete tiene que incluir en un proyecto.Content files are immutable files that a package needs to include in a project. Como son inmutables, no se prevé que el proyecto de consumo los modifique.Being immutable, they are not intended to be modified by the consuming project. Entre los archivos de contenido se encuentran los siguientes:Example content files include:

  • Imágenes que se insertan como recursosImages that are embedded as resources
  • Archivos de código fuente que ya están compiladosSource files that are already compiled
  • Scripts que se deben incluir con la salida de la compilación del proyectoScripts that need to be included with the build output of the project
  • Archivos de configuración del paquete que se debe incluir en el proyecto pero que no necesitan cambios específicos del proyectoConfiguration files for the package that need to be included in the project but don't need any project-specific changes

Los archivos de contenido se incluyen en un paquete mediante el elemento <files>, especificando la carpeta content en el atributo target.Content files are included in a package using the <files> element, specifying the content folder in the target attribute. Pero estos archivos se ignoran cuando el paquete se instala en un proyecto que usa PackageReference, que utiliza el elemento <contentFiles> en su lugar.However, such files are ignored when the package is installed in a project using PackageReference, which instead uses the <contentFiles> element.

Para lograr la máxima compatibilidad con los proyectos de consumo, un paquete idealmente especifica los archivos de contenido en ambos elementos.For maximum compatibility with consuming projects, a package ideally specifies the content files in both elements.

Usar el elemento files para los archivos de contenidoUsing the files element for content files

En cuanto a los archivos de contenido, basta con usar el mismo formato que para los archivos de ensamblado, pero se debe especificar content como carpeta base en el atributo target, como se muestra en los ejemplos siguientes.For content files, simply use the same format as for assembly files, but specify content as the base folder in the target attribute as shown in the following examples.

Archivos de contenido básicosBasic content files

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

Archivos de contenido con estructura de directoriosContent files with directory structure

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

Archivo de contenido específico para una plataforma de destinoContent file specific to a target framework

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

Archivo de contenido copiado en una carpeta con un punto en el nombreContent file copied to a folder with dot in name

En este caso, NuGet ve que la extensión de target no coincide con la extensión de src y, por lo tanto, trata esa parte del nombre de target como una carpeta:In this case, NuGet sees that the extension in target does not match the extension in src and thus treats that part of the name in target as a folder:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

Archivos de contenido sin extensiónContent files without extensions

Para incluir archivos sin extensión, use los caracteres comodín * o **:To include files without an extension, use the * or ** wildcards:

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

Archivos de contenido con una ruta de acceso y un destino profundosContent files with deep path and deep target

En este caso, puesto que las extensiones de archivo del origen y del destino coinciden, NuGet da por supuesto que el destino es un nombre de archivo y no una carpeta:In this case, because the file extensions of the source and target match, NuGet assumes that the target is a file name and not a folder:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Cambiar el nombre de un archivo de contenido del paqueteRenaming a content file in the package

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Archivos de exclusiónExcluding files

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

Usar el elemento contentFiles para los archivos de contenidoUsing the contentFiles element for content files

NuGet 4.0 + con PackageReferenceNuGet 4.0+ with PackageReference

De forma predeterminada, un paquete coloca contenido en una carpeta contentFiles (vea más abajo) y nuget pack incluye todos los archivos en esa carpeta usando atributos predeterminados.By default, a package places content in a contentFiles folder (see below) and nuget pack included all files in that folder using default attributes. En este caso no es necesario incluir un nodo contentFiles en el archivo .nuspec.In this case it's not necessary to include a contentFiles node in the .nuspec at all.

Para controlar los archivos que se incluyen, el elemento <contentFiles> especifica una colección de elementos <files> que identifican los archivos exactos que se deben incluir.To control which files are included, the <contentFiles> element specifies is a collection of <files> elements that identify the exact files include.

Estos archivos se especifican con un conjunto de atributos que describen cómo se deben usar en el sistema del proyecto:These files are specified with a set of attributes that describe how they should be used within the project system:

AtributoAttribute DescripciónDescription
includeinclude (Obligatorio) Ubicación de los archivos que se deben incluir, sujeta a exclusiones especificadas por el atributo exclude.(Required) The location of the file or files to include, subject to exclusions specified by the exclude attribute. La ruta de acceso es relativa al archivo .nuspec, a menos que se especifique una ruta de acceso absoluta.The path is relative to the .nuspec file unless an absolute path is specified. El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
excludeexclude Una lista delimitada por punto y coma de archivos o patrones de archivo que se deben excluir de la ubicación src.A semicolon-delimited list of files or file patterns to exclude from the src location. El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
buildActionbuildAction Acción de compilación que se debe asignar al elemento de contenido para MSBuild, como Content, None, Embedded Resource, Compile, etc. El valor predeterminado es Compile.The build action to assign to the content item for MSBuild, such as Content, None, Embedded Resource, Compile, etc. The default is Compile.
copyToOutputcopyToOutput Un valor booleano que indica si se va a copiar los elementos de contenido a la compilación de carpeta de salida (o publicar).A Boolean indicating whether to copy content items to the build (or publish) output folder. El valor predeterminado es false.The default is false.
flattenflatten Valor booleano que indica si se deben copiar los elementos de contenido en una carpeta en la salida de la compilación (true) o si se debe conservar la estructura de carpetas del paquete (false).A Boolean indicating whether to copy content items to a single folder in the build output (true), or to preserve the folder structure in the package (false). Esta marca solo funciona cuando la marca copyToOutput está establecida en true.This flag only works when copyToOutput flag is set to true. El valor predeterminado es false.The default is false.

Al instalar un paquete, NuGet aplica los elementos secundarios de <contentFiles> de arriba abajo.When installing a package, NuGet applies the child elements of <contentFiles> from top to bottom. Si hay varias entradas que coinciden con el mismo archivo, se aplicarán todas las entradas.If multiple entries match the same file then all entries are applied. La entrada de nivel superior invalida las entradas inferiores si hay un conflicto para el mismo atributo.The top-most entry overrides the lower entries if there is a conflict for the same attribute.

Estructura de carpetas de los paquetesPackage folder structure

El proyecto del paquete debe estructurar el contenido usando el siguiente patrón:The package project should structure content using the following pattern:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages puede ser cs, vb, fs, any o el equivalente en minúsculas de un $(ProjectLanguage) determinado.codeLanguages may be cs, vb, fs, any, or the lowercase equivalent of a given $(ProjectLanguage)
  • TxM es cualquier moniker de la plataforma de destino válido compatible con NuGet (vea Plataformas de destino).TxM is any legal target framework moniker that NuGet supports (see Target frameworks).
  • Se puede anexar cualquier estructura de carpetas al final de esta sintaxis.Any folder structure may be appended to the end of this syntax.

Por ejemplo:For example:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

Las carpetas vacías pueden usar . para no proporcionar contenido para ciertas combinaciones de idioma y TxM, por ejemplo:Empty folders can use . to opt out of providing content for certain combinations of language and TxM, for example:

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/.

Sección contentFiles de ejemploExample contentFiles section

<contentFiles>
    <!-- Embed image resources -->
    <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
    <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

    <!-- Embed all image resources under contentFiles/cs/ -->
    <files include="cs/**/*.png" buildAction="EmbeddedResource" />

    <!-- Copy config.xml to the root of the output folder -->
    <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

    <!-- Copy run.cmd to the output folder and keep the directory structure -->
    <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

    <!-- Include everything in the scripts folder except exe files -->
    <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
</contentFiles>

Archivos de ejemplo de nuspecExample nuspec files

Un archivo .nuspec simple que no especifica dependencias ni archivosA simple .nuspec that does not specify dependencies or files

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <licenseUrl>http://xunit.codeplex.com/license</licenseUrl>
    </metadata>
</package>

Un archivo .nuspec con dependenciasA .nuspec with dependencies

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

Un archivo .nuspec con archivosA .nuspec with files

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

Un archivo .nuspec con ensamblados de plataformaA .nuspec with framework assemblies

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

En este ejemplo se instalan los siguientes componentes para los destinos de proyecto específicos:In this example, the following are installed for specific project targets:

  • .NET4 -> System.Web, System.Net.NET4 -> System.Web, System.Net
  • .NET4 Client Profile -> System.Net.NET4 Client Profile -> System.Net
  • Silverlight 3 -> System.JsonSilverlight 3 -> System.Json
  • Silverlight 4 -> System.Windows.Controls.DomainServicesSilverlight 4 -> System.Windows.Controls.DomainServices
  • Windows Phone -> Microsoft.Devices.SensorsWindowsPhone -> Microsoft.Devices.Sensors