Referencia de .nuspec
Un archivo .nuspec
es un manifiesto XML que contiene metadatos de paquete. Este manifiesto se usa para crear el paquete y para proporcionar información a los consumidores. El manifiesto siempre se incluye en un paquete.
En este tema:
- Esquema y forma general
- Tokens de reemplazo (cuando se usa con un proyecto de Visual Studio)
- Dependencias
- Referencias de ensamblado explícitas
- Referencias de ensamblado de plataforma
- Incluir archivos de ensamblado
- Incluir archivos de contenido
- Archivos nuspec de ejemplo
Use
.nuspec
con paranuget.exe pack
proyectos que no son de estilo SDK que usenpackages.config
.No se necesita un archivo
.nuspec
para crear paquetes para proyectos de estilo SDK (normalmente proyectos de .NET Core y .NET Standard que usan el atributo SDK). (Tenga en cuenta que al crear el paquete se genera un elemento.nuspec
).Si va a crear un paquete mediante
dotnet.exe pack
omsbuild pack target
, en su lugar se recomienda incluir todas las propiedades que normalmente están en el archivo.nuspec
. Pero puede optar por usar un archivo.nuspec
para empaquetar mediantedotnet.exe
omsbuild pack target
.En el caso de los proyectos migrados de
packages.config
a PackageReference, no se necesita un archivo.nuspec
para crear el paquete. En su lugar, use msbuild -t:pack.
Un archivo de esquema nuspec.xsd
se encuentra en el repositorio NuGet de GitHub.
Tenga en cuenta que este archivo solo representa el esquema más reciente de un archivo .nuspec
.
No existen versiones publicadas oficialmente y ninguna versión de ese archivo se corresponde con ninguna versión específica de NuGet.
En este esquema, los archivos .nuspec
tienen el siguiente formato general:
<?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. 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. En cualquier caso, obtendrá una vista como la siguiente (cuando esté expandida en su mayoría):
Todos los nombres de elementos XML del archivo .nuspec distinguen mayúsculas y minúsculas, como sucede con el código XML en general. Por ejemplo, el uso del elemento de metadatos <description>
es correcto y <Description>
no lo es. A continuación se documenta el uso de mayúsculas y minúsculas adecuado para cada nombre de elemento.
Importante
Aunque el archivo .nuspec
contiene una referencia a un esquema (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"
), NuGet-Team nunca ha publicado un archivo de esquema que se podría usar para la validación automática de esquemas.
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.
Estos elementos deben aparecer dentro de un elemento <metadata>
.
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. 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. Vea Choosing a unique package identifier (Elegir un identificador de paquete único) para obtener instrucciones.
Al cargar un paquete en nuget.org, el campo id
está limitado a 128 caracteres.
La versión del paquete, siguiendo el patrón mayor.menor.revisión. 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.
Al cargar un paquete en nuget.org, el campo version
está limitado a 64 caracteres.
Descripción larga del paquete para su visualización en la interfaz de usuario.
Al cargar un paquete en nuget.org, el campo description
está limitado a 4000 caracteres.
Una lista separada por comas de autores de paquetes.
authors
y owners
de nuspec se omiten al cargar el paquete en nuget.org. Para establecer la propiedad del paquete en nuget.org, consulte Administración de propietarios de paquetes en nuget.org.
Importante
owners está en desuso. Use authors en su lugar.
Lista separada por comas de propietarios de paquetes.
El owners
nuspec se omite al cargar el paquete en nuget.org. Para establecer la propiedad del paquete en nuget.org, consulte Administración de propietarios de paquetes en nuget.org.
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.
Al cargar un paquete en nuget.org, el campo projectUrl
está limitado a 4000 caracteres.
Importante
licenseUrl está en desuso. Use licence en su lugar.
Dirección URL de la licencia del paquete, que a menudo se muestra en interfaces de usuario como en nuget.org.
Al cargar un paquete en nuget.org, el campo licenseUrl
está limitado a 4000 caracteres.
Compatible con NuGet 4.9.0 y versiones posteriores
Expresión de licencia SPDX o ruta de acceso a un archivo de licencia dentro del paquete, que a menudo se muestra en interfaces de usuario como nuget.org. Si va a conceder licencias al paquete bajo una licencia común, como MIT o BSD-2-Clause, use el identificador de licencia SPDX asociado. Por ejemplo:
<license type="expression">MIT</license>
Nota
NuGet.org solo acepta expresiones de licencia aprobadas por Open Source Initiative o Free Software Foundation.
Si el paquete tiene licencia con varias licencias comunes, puede especificar una licencia compuesta mediante la sintaxis de expresiones SPDX versión 2.0. Por ejemplo:
<license type="expression">BSD-2-Clause OR MIT</license>
Si usa una licencia personalizada que no es compatible con expresiones de licencia, puede empaquetar un archivo .txt
o .md
con el texto de la licencia. Por ejemplo:
<package>
<metadata>
...
<license type="file">LICENSE.txt</license>
...
</metadata>
<files>
...
<file src="licenses\LICENSE.txt" target="" />
...
</files>
</package>
Para conocer la equivalencia en MSBuild, vea Empaquetado de una expresión de licencia o un archivo de licencia.
La sintaxis exacta de las expresiones de licencia de NuGet se describe a continuación en ABNF.
license-id = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>
license-exception-id = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>
simple-expression = license-id / license-id”+”
compound-expression = 1*1(simple-expression /
simple-expression "WITH" license-exception-id /
compound-expression "AND" compound-expression /
compound-expression "OR" compound-expression ) /
"(" compound-expression ")" )
license-expression = 1*1(simple-expression / compound-expression / UNLICENSED)
Importante
iconUrl está en desuso. Use icon en su lugar.
URL para una imagen de 128x128 con fondo transparente para usarla como icono para el paquete en la visualización de la interfaz de usuario. 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. Por ejemplo, para usar una imagen de GitHub, utilice la dirección URL del archivo sin procesar, como https://github.com/<nombre_de_usuario>/<repositorio>/raw/<rama>/<logo.png>.
Al cargar un paquete en nuget.org, el campo iconUrl
está limitado a 4000 caracteres.
Compatible con NuGet 5.3.0 y versiones posteriores
Ruta de acceso a un archivo de imagen dentro del paquete, que a menudo se muestra en interfaces de usuario como nuget.org como el icono del paquete. El tamaño del archivo de imagen está limitado a 1 MB. Entre los formatos de archivos admitidos se incluyen JPEG y PNG. Se recomienda una resolución de imagen de 128x128.
Por ejemplo, podría agregar lo siguiente a nuspec al crear un paquete mediante nuget.exe:
<package>
<metadata>
...
<icon>images\icon.png</icon>
...
</metadata>
<files>
...
<file src="..\icon.png" target="images\" />
...
</files>
</package>
Ejemplo de icono de paquete en nuspec.
Para el equivalente de MSBuild, vea Empaquetado de un archivo de imagen de icono.
Sugerencia
Para mantener la compatibilidad con versiones anteriores con clientes y orígenes que aún no admiten icon
, especifique icon
y iconUrl
. Visual Studio admite icon
para paquetes procedentes de un origen basado en carpetas.
Compatible con NuGet 5.10.0 preview 2 y versiones posteriores
Al empaquetar un archivo Léame, debe usar el elemento readme
para especificar la ruta de acceso del paquete relativa a la raíz del paquete. Además de esto, debe asegurarse de que el archivo se incluya en el paquete. Los formatos de archivo admitidos incluyen solo Markdown (.md).
Por ejemplo, podría agregar lo siguiente a nuspec para empaquetar un archivo Léame con el proyecto:
<package>
<metadata>
...
<readme>docs\readme.md</readme>
...
</metadata>
<files>
...
<file src="..\readme.md" target="docs\" />
...
</files>
</package>
Para obtener el equivalente en MSBuild, vea Empaquetado de un archivo Léame.
Valor booleano que especifica si el cliente debe pedir al consumidor que acepte la licencia del paquete antes de instalarlo.
(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. Con PackageReference (NuGet 4.8 +), esta marca también significa que excluirá los recursos en tiempo de compilación de la compilación. Vea Compatibilidad de DevelopmentDependency con PackageReference
Importante
summary
está en desuso. En su lugar, use description
.
Descripción breve del paquete para su visualización en la interfaz de usuario. Si se omite, se usará una versión truncada de description
.
Al cargar un paquete en nuget.org, el campo summary
está limitado a 4000 caracteres.
(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.
Al cargar un paquete en nuget.org, el campo releaseNotes
está limitado a 35 000 caracteres.
(1.5+) Información de copyright del paquete.
Al cargar un paquete en nuget.org, el campo copyright
está limitado a 4000 caracteres.
Identificador de configuración regional del paquete. Vea Creación de paquetes localizados.
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.
Al cargar un paquete en nuget.org, el campo tags
está limitado a 4000 caracteres.
(3.3+) Solo para uso interno de NuGet.
Metadatos de repositorio, que constan de cuatro atributos opcionales: type
y url
(4.0+), y branch
y commit
(4.6+). Estos atributos le permiten asignar .nupkg
al repositorio que lo ha creado, con el potencial de obtener tanto detalle como el nombre de rama individual o el hash SHA-1 de confirmación que ha creado el paquete. Debe ser una URL disponible públicamente que un software de control de versiones pueda invocar directamente. No debe ser una página html, ya que está pensada para el equipo. Para vincular a la página del proyecto, use el campo projectUrl
en su lugar.
Por ejemplo:
<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
...
<repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
...
</metadata>
</package>
Al cargar un paquete en nuget.org, el atributo type
está limitado a 100 caracteres y el atributo url
a 4000 caracteres.
Título descriptivo del paquete que se puede usar en algunas pantallas de interfaz de usuario. (En nuget.org y el Administrador de paquetes en Visual Studio no se muestra el título)
Al cargar un paquete en nuget.org, el campo title
está limitado a 256 caracteres, pero no se usa con fines de visualización.
(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. Cada tipo de paquete tiene atributos de name y version. Vea Establecimiento de un tipo de paquete.
Colección de cero o más elementos <dependency>
que especifican las dependencias del paquete. Cada dependencia tiene atributos de id, version, include (3.x+) y exclude (3.x+). Vea Dependencias a continuación.
(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. Cada frameworkAssembly tiene atributos assemblyName y targetFramework. Vea Referencias de ensamblado de plataforma a continuación.
(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. Cada referencia tiene un atributo file. <references>
también puede contener un elemento <group>
con un atributo targetFramework, que contiene elementos <reference>
. Si se omite, se incluyen todas las referencias de lib
. Vea Referencias de ensamblado explícitas a continuación.
(3.3+) Colección de elementos <files>
que identifican archivos de contenido que se incluirán en el proyecto de consumo. Estos archivos se especifican con un conjunto de atributos que describen cómo se deben usar en el sistema del proyecto. Vea Incluir archivos de ensamblado a continuación.
El nodo <package>
puede contener un nodo <files>
como un elemento del mismo nivel de <metadata>
, y un elemento secundario <contentFiles>
en <metadata>
, para especificar los archivos de contenido y de ensamblado que se deben incluir en el paquete. 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.
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. 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. Por ejemplo, un paquete que usa el atributo developmentDependency
debería especificar "2.8" para minClientVersion
. Asimismo, un paquete que usa el elemento contentFiles
(vea la sección siguiente) debería establecer minClientVersion
en "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
.
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata minClientVersion="100.0.0.1">
<id>dasdas</id>
<version>2.0.0</version>
<title />
<authors>dsadas</authors>
<owners />
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>My package description.</description>
</metadata>
<files>
<file src="content\one.txt" target="content\one.txt" />
</files>
</package>
Al crear un paquete, el comando nuget pack
reemplaza los tokens delimitados por $ en los nodos <metadata>
y <files>
del archivo .nuspec
por valores procedentes de un archivo del proyecto o del conmutador pack
del comando -properties
.
En la línea de comandos, especifique valores de token con 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:
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
).
Para usar estos tokens, ejecute nuget pack
con el archivo de proyecto en lugar de hacerlo solo con el archivo .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:
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. Pero si a un proyecto le faltan valores de elementos .nuspec
necesarios, se producirá un error en nuget pack
. 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.
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.
Token | Origen del valor | Valor |
---|---|---|
$id$ | Archivo del proyecto | AssemblyName (título) del archivo del proyecto |
$version$ | AssemblyInfo | AssemblyInformationalVersion si está presente. En caso contrario, AssemblyVersion |
$author$ | AssemblyInfo | AssemblyCompany |
$title$ | AssemblyInfo | AssemblyTitle |
$description$ | AssemblyInfo | AssemblyDescription |
$copyright$ | AssemblyInfo | AssemblyCopyright |
$configuration$ | Archivo DLL del ensamblado | Configuración usada para compilar el ensamblado. El valor predeterminado es Depurar. 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. |
Los tokens también se pueden usar para resolver rutas de acceso cuando se incluyen archivos de ensamblado y archivos de contenido. 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. Por ejemplo, si usa los tokens siguientes en el archivo .nuspec
:
<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:
<files>
<file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>
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. Los atributos de cada <dependency>
son los siguientes:
Atributo | Descripción |
---|---|
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. |
version |
(Obligatorio) Intervalo de versiones aceptable como dependencia. Vea Control de versiones de paquetes para consultar la sintaxis exacta. Las versiones flotantes no se admiten. |
include | 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. El valor predeterminado es all . |
exclude | 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. El valor predeterminado es build,analyzers que se puede sobrescribir. Pero también se excluyen content/ ContentFiles implícitamente del paquete final que no se puede sobrescribir. Las etiquetas especificadas con exclude tienen prioridad sobre las que se especifican con include . Por ejemplo, include="runtime, compile" exclude="compile" es lo mismo que include="runtime" . |
Al cargar un paquete en nuget.org, el atributo id
de cada dependencia está limitado a 128 caracteres y el atributo version
a 256 caracteres.
Etiqueta Include o Exclude | Carpetas afectadas del destino |
---|---|
contentFiles | Contenido |
motor en tiempo de ejecución | Runtime, Resources y FrameworkAssemblies |
compile | lib |
build | build (propiedades y destinos de MSBuild) |
nativas | nativas |
None | Sin carpetas |
all | Todas las carpetas |
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.
<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
.
<dependencies>
<dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
<dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>
Importante
Nota: Al crear una instancia de .nuspec
a partir de un proyecto mediante nuget spec
, las dependencias que existen en ese proyecto no se incluyen automáticamente en el archivo .nuspec
resultante. En su lugar, use nuget pack myproject.csproj
y obtenga el archivo .nuspec desde el archivo .nupkg generado. Este archivo .nuspec contiene las dependencias.
Versión 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>
.
Cada grupo tiene un atributo denominado targetFramework
y contiene cero o más elementos <dependency>
. Estas dependencias se instalan conjuntamente cuando la plataforma de destino es compatible con el perfil de plataforma del proyecto.
El elemento <group>
sin un atributo targetFramework
se usa como la lista de reserva o predeterminada de dependencias. Vea Target frameworks (Plataformas de destino) para ver los identificadores de plataforma exactos.
Importante
El formato del grupo no se puede combinar con una lista plana.
Nota
El formato del Moniker de la plataforma de destino (TFM) usado en la carpeta lib/ref
es diferente al TFM que se utiliza en dependency groups
. Si las plataformas de destino declaradas en dependencies group
y la carpeta lib/ref
del archivo .nuspec
no tienen coincidencias exactas, el comando pack
generará la advertencia de NuGet NU5128.
En el ejemplo siguiente se muestran diferentes variaciones del elemento <group>
:
<dependencies>
<group>
<dependency id="RouteMagic" version="1.1.0" />
</group>
<group targetFramework=".NETFramework4.7.2">
<dependency id="jQuery" version="1.6.2" />
<dependency id="WebActivator" version="1.4.4" />
</group>
<group targetFramework="netcoreapp3.1">
</group>
</dependencies>
El elemento <references>
lo usan los proyectos que utilizan packages.config
para especificar explícitamente los ensamblados a los que debe hacer referencia el proyecto de destino al usar el paquete. Las referencias explícitas se suelen usar para ensamblados que solo son de tiempo de diseño. Para más información, vea la página sobre cómo seleccionar ensamblados a los que hacen referencia los proyectos.
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:
<references>
<reference file="xunit.dll" />
<reference file="xunit.extensions.dll" />
</references>
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>
.
Cada grupo tiene un atributo denominado targetFramework
y contiene cero o más elementos <reference>
. Estas referencias se agregan a un proyecto cuando la plataforma de destino es compatible con el perfil de plataforma del proyecto.
El elemento <group>
sin un atributo targetFramework
se usa como la lista de reserva o predeterminada de referencias. Vea Target frameworks (Plataformas de destino) para ver los identificadores de plataforma exactos.
Importante
El formato del grupo no se puede combinar con una lista plana.
En el ejemplo siguiente se muestran diferentes variaciones del elemento <group>
:
<references>
<group>
<reference file="a.dll" />
</group>
<group targetFramework="net45">
<reference file="b45.dll" />
</group>
<group targetFramework="netcore45">
<reference file="bcore45.dll" />
</group>
</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. 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. Estos ensamblados, por supuesto, no se incluyen directamente en un paquete.
El elemento <frameworkAssemblies>
contiene cero o más elementos <frameworkAssembly>
, cada uno de los cuales especifica los siguientes atributos:
Atributo | Descripción |
---|---|
assemblyName | (Obligatorio) Nombre completo del ensamblado. |
targetFramework | (Opcional) Especifica la plataforma de destino a la que se aplica esta referencia. Si se omite, indica que la referencia se aplica a todas las plataformas. Vea Target frameworks (Plataformas de destino) para ver los identificadores de plataforma exactos. |
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:
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.Net" />
<frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>
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
. El comando nuget pack
selecciona automáticamente los archivos necesarios.
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. Por esta razón, evite usar .resources.dll
para los archivos que, en otros casos, contienen código esencial del paquete.
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. Por ejemplo:
<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. Con NuGet 3.3+ y los proyectos que usan PackageReference, se usa el elemento <contentFiles>
en su lugar. Vea Incluir archivos de contenido a continuación para más información.
Cada elemento <file>
especifica los siguientes atributos:
Atributo | Descripción |
---|---|
src | Ubicación de los archivos que se deben incluir, sujeta a exclusiones especificadas por el atributo exclude . La ruta de acceso es relativa al archivo .nuspec , a menos que se especifique una ruta de acceso absoluta. El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva. |
Destino | 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 . Vea Creating a .nuspec from a convention-based working directory (Crear un archivo .nuspec desde un directorio de trabajo basado en convenciones). |
exclude | Una lista delimitada por punto y coma de archivos o patrones de archivo que se deben excluir de la ubicación src . El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva. |
Ensamblado único
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 destino
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ín
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 plataformas
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ón
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)
Los archivos de contenido son archivos inmutables que un paquete tiene que incluir en un proyecto. Como son inmutables, no se prevé que el proyecto de consumo los modifique. Entre los archivos de contenido se encuentran los siguientes:
- Imágenes que se insertan como recursos
- Archivos de código fuente que ya están compilados
- Scripts que se deben incluir con la salida de la compilación del proyecto
- Archivos de configuración del paquete que se debe incluir en el proyecto pero que no necesitan cambios específicos del proyecto
Los archivos de contenido se incluyen en un paquete mediante el elemento <files>
, especificando la carpeta content
en el atributo target
. Pero estos archivos se ignoran cuando el paquete se instala en un proyecto que usa PackageReference, que utiliza el elemento <contentFiles>
en su lugar.
Para lograr la máxima compatibilidad con los proyectos de consumo, un paquete idealmente especifica los archivos de contenido en ambos elementos.
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.
Archivos de contenido básicos
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 directorios
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 destino
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 nombre
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:
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ón
Para incluir archivos sin extensión, use los caracteres comodín *
o **
:
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 profundos
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:
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 paquete
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ón
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)
NuGet 4.0 + con 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. En este caso no es necesario incluir un nodo contentFiles
en el archivo .nuspec
.
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.
Estos archivos se especifican con un conjunto de atributos que describen cómo se deben usar en el sistema del proyecto:
Atributo | Descripción |
---|---|
include | (Obligatorio) Ubicación de los archivos que se deben incluir, sujeta a exclusiones especificadas por el atributo exclude . La ruta de acceso es relativa a la carpeta contentFiles , a menos que se especifique una ruta de acceso absoluta. El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva. |
exclude | Una lista delimitada por punto y coma de archivos o patrones de archivo que se deben excluir de la ubicación src . El carácter comodín * está permitido y el carácter comodín doble ** implica una búsqueda de carpeta recursiva. |
buildAction | Acción de compilación que asigna al elemento de contenido para MSBuild, como Content , None , Embedded Resource , Compile , etc. La predeterminada es Compile . |
copyToOutput | Valor booleano que indica si se deben copiar los elementos de contenido en la carpeta de salida de la compilación (o de la publicación). El valor predeterminado es false. |
aplanar | 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). Esta marca solo funciona cuando la marca copyToOutput está establecida en true. El valor predeterminado es false. |
Al instalar un paquete, NuGet aplica los elementos secundarios de <contentFiles>
de arriba abajo. Si hay varias entradas que coinciden con el mismo archivo, se aplicarán todas las entradas. La entrada de nivel superior invalida las entradas inferiores si hay un conflicto para el mismo atributo.
El proyecto del paquete debe estructurar el contenido usando el siguiente patrón:
/contentFiles/{codeLanguage}/{TxM}/{any?}
codeLanguages
puede sercs
,vb
,fs
,any
o el equivalente en minúsculas de un$(ProjectLanguage)
determinado.TxM
es cualquier moniker de la plataforma de destino válido compatible con NuGet (vea Plataformas de destino).- Se puede anexar cualquier estructura de carpetas al final de esta sintaxis.
Por ejemplo:
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:
/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
...
<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>
</metadata>
</package>
Versión 5.1+ solo con PackageReference
Las referencias de marco son un concepto de .NET Core que representa marcos compartidos como WPF o Windows Forms. Al especificar un marco compartido, el paquete garantiza que todas sus dependencias del marco se incluyan en el proyecto de referencia.
Cada elemento <group>
necesita un atributo targetFramework
y cero o más elementos <frameworkReference>
.
En el ejemplo siguiente se muestra un archivo nuspec generado para un proyecto WPF de .NET Core. Tenga en cuenta que no se recomienda crear a mano archivos nuspec que contienen referencias de marco. Considere la posibilidad de usar el paquete targets en su lugar, que los deducirá automáticamente del proyecto.
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
<metadata>
<dependencies>
<group targetFramework=".NETCoreApp3.1" />
</dependencies>
<frameworkReferences>
<group targetFramework=".NETCoreApp3.1">
<frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
</group>
</frameworkReferences>
</metadata>
</package>
Un archivo .nuspec
simple que no especifica dependencias ni archivos
<?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>
<license type="expression">MIT</license>
</metadata>
</package>
Un archivo .nuspec
con dependencias
<?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 archivos
<?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 plataforma
<?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:
- .NET4 ->
System.Web
,System.Net
- Perfil de cliente .NET4 ->
System.Net
- Silverlight 3 ->
System.Json
- WindowsPhone ->
Microsoft.Devices.Sensors