Creación de un paquete mediante la CLI de nuget.exe

Independientemente de lo que haga el paquete o el código que contiene, use una de las herramientas de la interfaz de línea de comandos (CLI), ya sea nuget.exe o dotnet.exe, para empaquetar esa funcionalidad en un componente que otros desarrolladores pueden compartir y usar. Para instalar las herramientas de la CLI de NuGet, consulte Instalación de herramientas de cliente de NuGet. Visual Studio no incluye automáticamente una herramienta de la CLI.

• Para proyectos que no utilizan el estilo SDK, normalmente proyectos de .NET Framework, siga los pasos descritos en este artículo para crear un paquete. Para ver un inicio rápido que proporciona instrucciones paso a paso para usar Visual Studio y la CLI de nuget.exe, consulte Quickstart: Creación y publicación de un paquete mediante Visual Studio (.NET Framework, Windows).

• Para proyectos de .NET Core y .NET Standard que usan el formato de estilo SDK y cualquier otro proyecto de estilo SDK, consulte Crear un paquete NuGet con la CLI de dotnet.

• Para los proyectos migrados de packages.config a PackageReference, use el msbuild -t:pack comando .

Técnicamente, un paquete NuGet es un archivo ZIP cuyo nombre se ha cambiado para que la extensión .nupkg y cuyo contenido coincida con determinadas convenciones. En este artículo se describe el proceso detallado de creación de un paquete que cumple esas convenciones.

El empaquetado comienza con el código compilado (ensamblados), símbolos y otros archivos que desea entregar como paquete. Para obtener información general sobre el proceso de empaquetado, consulte Flujo de trabajo de creación de paquetes. Este proceso es independiente de la compilación o la generación de los archivos que van al paquete. Pero puede extraer información de un archivo de proyecto para mantener sincronizados los ensamblados y paquetes compilados.

Decidir qué ensamblados empaquetar

La mayoría de los paquetes de uso general contienen uno o varios ensamblados que otros desarrolladores pueden usar en sus propios proyectos.

En general, es mejor tener un ensamblado por paquete NuGet, siempre que cada ensamblado sea útil de forma independiente. Por ejemplo, considere los siguientes casos que implican un ensamblado denominado Utilities.dll que depende de un ensamblado denominado Parser.dll:

• Si Parser.dll es útil por su cuenta, cree un paquete para Utilities.dll y otro para Parser.dll. Al hacerlo, los desarrolladores pueden usar Parser.dll independientemente de Utilities.dll.

• Si Parser.dll contiene código que solo usa Utilities.dll, está bien mantener Parser.dll en el mismo paquete. En general, si la biblioteca se compone de varios ensamblados que no son útiles de forma independiente, es conveniente combinarlos en un paquete.

• Si Utilities.dll también depende de Utilities.resources.dll, y Utilities.resources.dll no es útil por sí solo, coloque ambos en el mismo paquete.

Los recursos, como el ensamblado Utilities.resources.dll en el ejemplo anterior, son un caso especial. Cuando se instala un paquete en un proyecto, NuGet agrega automáticamente referencias de ensamblado a los archivos DLL del paquete, excepto los denominados .resources.dll, ya que se supone que son ensamblados satélite localizados. Para obtener más información sobre las versiones localizadas de una biblioteca, consulte Creación de paquetes NuGet localizados. Por este motivo, evite usar .resources.dll para los archivos que contienen código de paquete esencial.

Si la biblioteca contiene ensamblados de interoperabilidad del modelo de objetos componentes (COM), siga las instrucciones adicionales de Creación de paquetes NuGet que contienen ensamblados de interoperabilidad COM.

El rol y la estructura del archivo .nuspec

Cuando sepa qué archivos desea empaquetar, el siguiente paso es crear un manifiesto de paquete en un archivo XML .nuspec .

El manifiesto:

• Describe el contenido del paquete y se incluye en el paquete.
• Impulsa la creación del paquete e indica a NuGet cómo instalar el paquete en un proyecto. Por ejemplo, el manifiesto identifica otras dependencias de paquete para que NuGet también pueda instalar esas dependencias cuando se instala el paquete principal.
• Contiene las propiedades obligatorias y opcionales, como se describe en el resto de esta sección. Para obtener información detallada, incluidas otras propiedades que no se mencionan aquí, vea Referencia de .nuspec.

En el manifiesto se requieren las siguientes propiedades:

• Identificador del paquete, que debe ser único en toda la galería que hospeda el paquete.
• Número de versión específico con el formato Major.Minor.Patch[-Suffix], donde -Suffix identifica las versiones preliminares.
• Título del paquete como debería aparecer en el host (como nuget.org)
• Información del autor
• Una descripción larga del paquete

Las siguientes propiedades son opcionales comunes:

• Notas de la versión.
• Información de copyright.
• Una breve descripción de la interfaz de usuario Administrador de paquetes en Visual Studio.
• Identificador de configuración regional.
• Dirección URL del proyecto.
• Una licencia como expresión o archivo. La licenseUrl propiedad está obsoleta. Use el license elemento de metadatos nuspec en su lugar.
• Un archivo read-me.
• Un archivo de icono. La iconUrl propiedad está obsoleta. Use el icon elemento de metadatos nuspec en su lugar.
• Listas de dependencias y referencias.
• Etiquetas que ayudan en las búsquedas de la galería.

El código siguiente es un archivo .nuspec típico (pero ficticio), con comentarios que describen las propiedades:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- An identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- A package version number that's used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- A comma-separated list of package authors that sometimes appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- A project URL that provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

        <!-- License information that's displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        
        <!-- The location of a read-me file that's displayed in the Visual Studio Package Manager UI -->
        <readme>readme.md</readme>

        <!-- An icon that's used in the Visual Studio Package Manager UI -->
        <icon>icon.png</icon>

        <!-- 
            A property that when true, prompts the user to accept the license when
            installing the package
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Detailed information about a particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            A description that can be used in the Package Manager UI. The
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2026 Contoso Corporation</copyright>

        <!-- Tags that appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies that are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A read-me Markdown file that's displayed in the Package Manager UI -->
    <files>
        <file src="readme.md" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Para obtener información detallada sobre cómo declarar dependencias y especificar números de versión, consulte packages.config y Control de versiones de paquetes. También puede usar los include atributos y exclude en el dependency elemento para especificar los recursos de dependencia que desea incluir o excluir en el paquete. Para obtener más información, vea la Referencia de .nuspec: elemento de dependencias.

Dado que el manifiesto se incluye en el paquete creado a partir de él, puede encontrar ejemplos examinando los paquetes existentes. Una buena fuente es la carpeta global-packages en tu equipo. Para buscar su ubicación, use el siguiente comando:

nuget locals -list global-packages

Después de conocer la ubicación de la carpeta global-packages , siga estos pasos para buscar un archivo de manifiesto:

1. Vaya a la carpeta global-packages .
2. En esa carpeta, vaya a la subcarpeta de cualquier paquete y, a continuación, vaya a una subcarpeta para cualquier versión de ese paquete.
3. En la subcarpeta version, realice una copia del archivo .nupkg y cambie la extensión de la copia a zip.
4. Abra el archivo .zip y examine el archivo .nuspec dentro de él.

Creación del archivo .nuspec

La creación de un manifiesto completo suele comenzar con un archivo .nuspec básico generado a través de uno de los métodos siguientes:

• Un directorio de trabajo según convenciones
• Un archivo DLL de ensamblado
• Un proyecto de Visual Studio
• Nuevo archivo con valores predeterminados

A continuación, edita el archivo manualmente para que describa el contenido exacto que desee en el paquete final.

Desde un directorio de trabajo establecido por convención

Dado que un paquete NuGet es un archivo ZIP cuyo nombre se ha cambiado con la extensión .nupkg , a menudo es más fácil crear la estructura de carpetas que desee en el sistema de archivos local y, a continuación, crear el archivo .nuspec directamente desde esa estructura. A continuación, el nuget pack comando agrega automáticamente todos los archivos de esa estructura de carpetas, pero excluye las carpetas que comienzan por un punto, por lo que puede mantener los archivos privados en la misma estructura.

La ventaja de este enfoque es que no es necesario especificar en el manifiesto qué archivos desea incluir en el paquete, como se explica más adelante en esta sección. En su lugar, puede hacer que el proceso de compilación genere la estructura de carpetas exacta que entra en el paquete. También puede incluir fácilmente otros archivos que podrían no formar parte de un proyecto de lo contrario:

• Contenido y código fuente que se deben insertar en el proyecto de destino
• Scripts de PowerShell
• Transformaciones en archivos de configuración y código fuente existentes en un proyecto

Las carpetas se alinean con las convenciones siguientes:

Dado que la estructura de carpetas puede contener ensamblados para muchos marcos de destino, este método es necesario cuando se crean paquetes que admiten varios marcos de trabajo.

Cuando tenga la estructura de carpetas deseada en su lugar, ejecute el siguiente comando en esa carpeta para crear el archivo .nuspec :

nuget spec

El archivo .nuspec generado no contiene referencias explícitas a los archivos de la estructura de carpetas. NuGet incluye automáticamente todos los archivos cuando se crea el paquete. Sin embargo, debe editar los valores de marcador de posición en otras partes del manifiesto.

Desde un archivo DLL de ensamblado

En el caso básico de crear un paquete a partir de un ensamblado, puede generar un archivo .nuspec a partir de los metadatos del ensamblado mediante el siguiente comando:

nuget spec <assembly-name>.dll

El uso de este formulario sustituye varios marcadores de posición en el manifiesto por valores específicos del ensamblado. Por ejemplo, la <id> propiedad se establece en el nombre del ensamblado y <version> se establece en la versión del ensamblado. Sin embargo, otras propiedades del manifiesto no tienen valores coincidentes en el ensamblado. Esas propiedades todavía contienen marcadores de posición después de ejecutar el comando.

Desde un proyecto de Visual Studio

La creación de un archivo .nuspec a partir de un archivo .csproj o .vbproj es conveniente, ya que se hace referencia automáticamente a otros paquetes instalados en el proyecto como dependencias. Para crear un manifiesto a partir de un archivo de proyecto, use el siguiente comando en la carpeta que contiene el archivo del proyecto:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget spec

El archivo project-name.nuspec< resultante> contiene tokens que se reemplazan en tiempo de empaquetado por valores del proyecto, incluidas las referencias a cualquier otro paquete que ya se haya instalado.

Si tiene dependencias de paquete que se van a incluir en .nuspec, use nuget packen su lugar . A continuación, obtenga el archivo .nuspec desde el archivo .nupkg generado. Por ejemplo, use el siguiente comando:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget pack myproject.csproj

Un token se delimita por $ símbolos en ambos lados de la propiedad del proyecto. Por ejemplo, el <id> valor de un manifiesto generado de esta manera suele ser similar a la siguiente línea:

<id>$id$</id>

Este token se reemplaza por el valor AssemblyName del archivo del proyecto durante el tiempo de empaquetado. Para obtener la asignación exacta de valores de proyecto a tokens de archivo .nuspec , consulte Tokens de reemplazo.

Los tokens le alivian de necesitar actualizar valores cruciales, como el número de versión en el archivo .nuspec a medida que actualiza el proyecto. Pero también puede reemplazar los tokens por valores literales.

Hay varias opciones de empaquetado adicionales disponibles cuando se trabaja desde un proyecto de Visual Studio, como se describe en Run nuget pack para generar el archivo .nupkg más adelante en este artículo.

Paquetes de nivel de solución

Solo NuGet 2.x. No está disponible en NuGet 3.0 y versiones posteriores.

NuGet 2.x admite la noción de un paquete de nivel de solución que instala herramientas o comandos adicionales para la consola de Administrador de paquetes (el contenido de la tools carpeta), pero no agrega referencias, contenido ni personalizaciones de compilación a ningún proyecto de la solución. Estos paquetes no contienen archivos en su biblioteca directa, contenido o carpetas de compilación , y ninguna de sus dependencias tiene archivos en sus respectivas carpetas lib, contenido o compilación .

NuGet realiza un seguimiento de los paquetes de nivel de solución instalados en un archivo packages.config de la carpeta .nuget , en lugar del archivo packages.config del proyecto.

Desde un nuevo archivo con valores predeterminados

El siguiente comando crea un manifiesto predeterminado con marcadores de posición, lo que ayuda a asegurarse de que comienza con la estructura de archivos adecuada:

nuget spec [<package-name>]

Si omite <package-name>, el archivo resultante se denomina Package.nuspec. Si proporciona un nombre como Contoso.Utility.UsefulStuff, el archivo se denomina Contoso.Utility.UsefulStuff.nuspec.

El archivo .nuspec resultante contiene marcadores de posición para valores como projectUrl. Antes de usar el archivo para crear el archivo .nupkg final, reemplace los marcadores de posición por los valores adecuados.

Elija un identificador de paquete único y establezca el número de versión.

El identificador de paquete (<id> elemento) y el número de versión (<version> elemento) son los dos valores más importantes del manifiesto, ya que identifican de forma única el código exacto que se encuentra en el paquete.

Procedimientos recomendados para el identificador del paquete

• Unicidad: el identificador debe ser único en la galería que hospeda el paquete, como nuget.org. Antes de decidir un identificador, busque en la galería aplicable para comprobar si el nombre ya está en uso. Para evitar conflictos, un buen patrón es usar el nombre de la empresa como la primera parte del identificador, como Contoso.
• Namespace-like names: Siga un patrón similar a los espacios de nombres de .NET, usando notación con puntos en lugar de guiones. Por ejemplo, use Contoso.Utility.UsefulStuff en lugar de Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. Los consumidores también lo consideran útil cuando el identificador del paquete coincide con los espacios de nombres usados en el código.
• Paquetes de ejemplo: si genera un paquete de código de ejemplo que muestra cómo usar otro paquete, adjunte .Sample como sufijo al identificador, como en Contoso.Utility.UsefulStuff.Sample. Un paquete de ejemplo de este tipo tiene una dependencia del paquete que muestra cómo usar. Al crear un paquete de ejemplo, use el método de directorio de trabajo basado en convención descrito anteriormente. En la carpeta de contenido , organice el código de ejemplo en una carpeta denominada \Samples\<identifier>, como en \Samples\Contoso.Utility.UsefulStuff.Sample.

Procedimientos recomendados para la versión del paquete

• En general, establezca la versión del paquete para que coincida con la biblioteca. Esta guía se recomienda, pero no es estrictamente necesaria. Esta práctica es sencilla cuando se limita un paquete a un único ensamblado, como se describe anteriormente en Decidir qué ensamblados empaquetar. En general, recuerde que NuGet se ocupa de las versiones del paquete al resolver las dependencias, no las versiones de ensamblado.
• Al usar un esquema de versión no estándar, tenga en cuenta las reglas de control de versiones de NuGet, como se explica en Control de versiones de paquetes.

Para ver otros recursos que resultan útiles para comprender el control de versiones, consulte la siguiente serie de entradas de blog breves:

• Parte 1: Enfrentando DLL Hell
• Parte 2: El algoritmo principal
• Parte 3: Unificación mediante redirecciones de enlace

Agregar un archivo read-me y otros archivos

Para especificar directamente los archivos que se van a incluir en el paquete, use el nodo <files> en el archivo .nuspec, que sigue la etiqueta <metadata>:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add files from an arbitrary folder that's not necessarily in the project. -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Para incluir un archivo read-me en el paquete, use el elemento de metadatos readme para especificar la ruta de acceso de destino al archivo read-me. Use también un file elemento de metadatos para especificar la ruta de acceso de origen y la carpeta de destino del archivo read-me. Para obtener más información, consulte readme.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
        <readme>docs\readme.md</readme>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add a read-me file. -->
        <file src="..\readme.md" target="docs\" />
    </files>
</package>

Visual Studio muestra el contenido del archivo read-me en la interfaz de usuario de Administrador de paquetes. Por ejemplo, en la captura de pantalla siguiente se muestra el archivo read-me del HtmlAgilityPack paquete:

Incluir en un paquete las propiedades y objetivos de MSBuild

En algunos casos, es posible que quiera agregar destinos de compilación personalizados o propiedades a proyectos que consumen el paquete, como ejecutar una herramienta personalizada o un proceso durante la compilación. Para obtener más información sobre los destinos de compilación personalizados y las propiedades, vea MSBuild .props y .targets en un paquete.

Cree archivos <package-id.targets> o <package-id.props>, como Contoso.Utility.UsefulStuff.targets, en las carpetas de build del proyecto.

A continuación, en el archivo .nuspec, consulte estos archivos en el nodo <files>:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- In the package build folder, include everything that's in the local build folder. -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Cuando se agregan paquetes a un proyecto, NuGet incluye automáticamente estas propiedades y destinos.

Ejecución del paquete nuget para generar el archivo .nupkg

Cuando utilice un ensamblado o un directorio de trabajo basado en convenciones, cree un paquete ejecutando nuget pack con su archivo .nuspec. En el comando siguiente, reemplace por <project-name> el nombre del proyecto:

nuget pack <project-name>.nuspec

Cuando se usa un proyecto de Visual Studio, ejecute nuget pack con el archivo de proyecto. Este comando carga automáticamente el archivo .nuspec del proyecto y reemplaza los tokens en él por los valores correspondientes en el archivo del proyecto:

nuget pack <project-name>.csproj

En todos los casos, nuget pack excluye las carpetas que comienzan por un punto, como .git o .hg.

NuGet indica si hay errores en el archivo .nuspec que necesitan corregir, como los valores de marcador de posición del manifiesto que deben actualizarse.

Una vez nuget pack realizado correctamente, tiene un archivo .nupkg que puede publicar en una galería adecuada, tal como se describe en Publicación de paquetes NuGet.

Opciones adicionales

Puede usar varios modificadores de línea de comandos con nuget pack para excluir archivos, invalidar el número de versión en el manifiesto y cambiar la carpeta de salida, entre otras características. Para obtener una lista completa, consulte comando pack (CLI de NuGet).

Las siguientes opciones son algunas de las que son comunes con los proyectos de Visual Studio:

• Proyectos a los que se hace referencia: si el proyecto hace referencia a otros proyectos, puede agregar los proyectos a los que se hace referencia como parte del paquete, o como dependencias, mediante la -IncludeReferencedProjects opción :

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Este proceso de inclusión es recursivo. Por ejemplo, si MyProject.csproj hace referencia a los proyectos B y C, y esos proyectos hacen referencia a D, E y F, los archivos de B, C, D, E y F se incluyen en el paquete.

  Si un proyecto al que se hace referencia incluye un archivo .nuspec propio, NuGet agrega ese proyecto al que se hace referencia como dependencia en su lugar. Debe empaquetar y publicar ese proyecto por separado.

• Configuración de compilación: de forma predeterminada, NuGet usa la configuración de compilación predeterminada establecida en el archivo de proyecto, normalmente Debug. Para empaquetar archivos desde una configuración de compilación diferente, como Release, use la -properties opción con la configuración:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Símbolos: Para incluir símbolos que permitan a los consumidores recorrer paso a paso el código de su paquete en el depurador, use las opciones -Symbols y -SymbolPackageFormat. Para la -SymbolPackageFormat opción , especifique un formato de snupkg:

  nuget pack MyProject.csproj -symbols -SymbolPackageFormat snupkg
  

Prueba de la instalación del paquete

Antes de publicar un paquete, normalmente quiere probar el proceso de instalación del paquete en un proyecto. Una prueba ayuda a garantizar que todos los archivos necesarios terminen en el lugar correcto en el proyecto.

Puede probar las instalaciones manualmente en Visual Studio o en la línea de comandos mediante los pasos de instalación estándar package.

Para las pruebas automatizadas, puede usar el siguiente proceso básico:

1. Copie el archivo .nupkg en una carpeta local.
2. Agregue la carpeta a los orígenes del paquete mediante el nuget sources add -name <name> -source <path> comando . Para más información, consulte el comando sources (CLI de NuGet). Debe establecer este origen local solo una vez en cualquier equipo determinado.
3. Instale el paquete desde ese origen mediante nuget install <package-ID> -source <name>. En este comando, <name> debe coincidir con el nombre del origen que use en el nuget sources comando . Al especificar el origen, se indica a NuGet que instale el paquete solo desde ese origen.
4. Examine el sistema de archivos para comprobar que los archivos están instalados correctamente.

Contenido relacionado

Después de crear un paquete, que es un archivo .nupkg , puede publicarlo en la galería de su elección. Para obtener más información, consulte Publicación de paquetes NuGet.

También puede ampliar las funcionalidades del paquete o admitir otros escenarios. Para obtener más información, consulte los artículos siguientes:

• Control de versiones de paquetes
• Soporta múltiples versiones de .NET
• Transformación del código fuente y los archivos de configuración
• Creación de paquetes NuGet localizados
• Creación de paquetes de versión preliminar
• Establecimiento de un tipo de paquete NuGet
• Creación de paquetes NuGet que contienen ensamblados de interoperabilidad COM

Para conocer otros tipos de paquetes, consulte los siguientes artículos:

• Creación de paquetes nativos
• Crear paquetes de símbolos (.snupkg)