Compartir a través de

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 CLI, ya sea nuget.exe o dotnet.exe, para empaquetar esa funcionalidad en un componente que se pueda compartir y usar con cualquier número de otros desarrolladores. Para instalar las herramientas de la CLI de NuGet, consulte Instalación de herramientas de cliente de NuGet. Tenga en cuenta que Visual Studio no incluye automáticamente una herramienta de la CLI.

Técnicamente, un paquete NuGet es simplemente un archivo ZIP cuyo nombre se ha cambiado con la .nupkg extensión y cuyo contenido coincide con determinadas convenciones. En este tema 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 u otros archivos que desea entregar como paquete (consulte Información general y flujo de trabajo). Este proceso es independiente de compilar o generar los archivos que entran en el paquete, aunque puede extraer información de un archivo de proyecto para mantener sincronizados los ensamblados y paquetes compilados.

Importante

Este tema se aplica a proyectos que no son de estilo SDK, normalmente proyectos distintos de proyectos de .NET Core y .NET Standard con Visual Studio 2017 y versiones posteriores y NuGet 4.0 y versiones posteriores.

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, si tiene un Utilities.dll que depende de Parser.dlly Parser.dll es útil por sí mismo, cree un paquete para cada uno. Al hacerlo, los desarrolladores pueden usar Parser.dll independientemente de Utilities.dll.

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

  • Del mismo modo, si Utilities.dll depende de Utilities.resources.dll, donde de nuevo este último no es útil por sí solo, coloque ambos en el mismo paquete.

Los recursos son, de hecho, 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 que se denominan .resources.dll porque se supone que se localizan ensamblados satélite (consulte Creación de paquetes localizados). Por este motivo, evite usar .resources.dll para los archivos que de otro modo contienen código de paquete esencial.

Si la biblioteca contiene ensamblados de interoperabilidad COM, siga las instrucciones adicionales de Creación de paquetes con ensamblados de interoperabilidad COM.

El rol y la estructura del archivo .nuspec

Una vez que sepa qué archivos desea empaquetar, el siguiente paso consiste en crear un manifiesto de paquete en un .nuspec archivo XML.

El manifiesto:

  1. Describe el contenido del paquete y se incluye en el paquete.
  2. Controla 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, de modo que NuGet también puede instalar esas dependencias cuando se instala el paquete principal.
  3. Contiene las propiedades obligatorias y opcionales, como se describe a continuación. Para obtener detalles exactos, incluidas otras propiedades que no se mencionan aquí, vea la referencia .nuspec.

Propiedades necesarias:

  • 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 de autor y propietario.
  • Una descripción larga del paquete.

Propiedades opcionales comunes:

A continuación se muestra un archivo típico (pero ficticio), .nuspec con comentarios que describen las propiedades:

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

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

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

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

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

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

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Para obtener más información sobre cómo declarar dependencias y especificar números de versión, consulte packages.config y Control de versiones de paquetes. También es posible hacer visibles los recursos de las dependencias directamente en el paquete mediante los atributos include y exclude en el elemento dependency. Consulte Referencia de .nuspec: Dependencias.

Dado que el manifiesto se incluye en el paquete creado a partir de él, puede encontrar cualquier número de ejemplos adicionales examinando los paquetes existentes. Un buen origen es la carpeta global-packages del equipo, cuya ubicación se puede obtener con el siguiente comando:

nuget locals -list global-packages

Vaya a cualquier carpeta package\version, copie el .nupkg archivo en un .zip archivo, luego abra ese .zip archivo y examine el .nuspec contenido dentro de él.

Nota:

Al crear un .nuspec objeto a partir de un proyecto de Visual Studio, el manifiesto contiene tokens que se reemplazan por información del proyecto cuando se compila el paquete. Consulte Creación de .nuspec desde un proyecto de Visual Studio.

Creación del archivo .nuspec

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

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

Importante

Los archivos generados .nuspec contienen marcadores de posición que se deben modificar antes de crear el paquete con el nuget pack comando . El comando falla si .nuspec contiene algún marcador de posición.

Desde un directorio de trabajo establecido por convención

Dado que un paquete NuGet es simplemente un archivo ZIP cuyo nombre se ha cambiado con la .nupkg extensión, 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 .nuspec archivo directamente desde esa estructura. A continuación, el nuget pack comando agrega automáticamente todos los archivos de esa estructura de carpetas (excepto las carpetas que comienzan por ., lo que le permite mantener archivos privados en la misma estructura).

La ventaja de este enfoque es que no es necesario especificar en el manifiesto los archivos que desea incluir en el paquete (como se explica más adelante en este tema). Simplemente puede hacer que el proceso de compilación genere la estructura de carpetas exacta que entra en el paquete y 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 convenciones de carpeta son las siguientes:

Carpeta Description Acción tras la instalación del paquete
(root) Ubicación de readme.txt Visual Studio muestra un archivo readme.txt en la raíz del paquete cuando se instala el paquete.
lib/{tfm} Ensablado (.dll), documentación (.xml) y archivos de símbolos (.pdb) para el identificador del marco de trabajo de destino (TFM) dado Los ensamblados se agregan como referencias tanto para la compilación como para el tiempo de ejecución, y .xml y .pdb se copian en las carpetas del proyecto. Vea Compatibilidad con varios frameworks de destino para crear subcarpetas específicas del framework de destino.
ref/{tfm} Ensamblado (.dll) y archivos de símbolos (.pdb) para el moniker de la plataforma de destino (TFM) dado Los ensamblados se agregan como referencias solo para el tiempo de compilación; Por lo tanto, no se copiará nada en la carpeta bin del proyecto.
runtimes Archivos de ensamblados específicos de la arquitectura (.dll), símbolos (.pdb) y recursos nativos (.pri) Los ensamblajes se agregan como referencias únicamente durante el tiempo de ejecución; otros archivos se copian en carpetas de proyecto. Siempre debe haber un ensamblaje específico correspondiente (TFM) AnyCPU en la carpeta /ref/{tfm} para proporcionar el ensamblaje en tiempo de compilación correspondiente. Consulte Compatibilidad con varias plataformas de destino.
contenido Archivos arbitrarios El contenido se copia en la raíz del proyecto. Piense en la carpeta de contenido como la raíz de la aplicación de destino que, en última instancia, consume el paquete. Para que el paquete agregue una imagen en la carpeta /images de la aplicación, colóquela en la carpeta content/images del paquete.
Construir (3.x+) Archivos de MSBuild .targets y .props Insertado automáticamente en el proyecto.
buildMultiTargeting (4.0+) Archivos de MSBuild .targets y .props para la compatibilidad entre marcos Insertado automáticamente en el proyecto.
buildTransitive (5.0+) archivos de MSBuild .targets y .props que se transmiten de forma transitiva a cualquier proyecto que los consuma. Vea la página de la funcionalidad. Insertado automáticamente en el proyecto.
herramientas Scripts y programas de PowerShell accesibles desde la consola del Administrador de paquetes La carpeta tools se añade a la variable de entorno PATH solamente para la Consola del Administrador de Paquetes (específicamente, no a lo que PATH está configurado para MSBuild al construir el proyecto).

Dado que la estructura de carpetas puede contener cualquier número de ensamblados para cualquier número de marcos de destino, este método es necesario al crear paquetes que admiten varios marcos.

En cualquier caso, una vez que tenga la estructura de carpetas deseada en su lugar, ejecute el siguiente comando en esa carpeta para crear el .nuspec archivo:

nuget spec

De nuevo, el elemento generado .nuspec 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 sencillo de crear un paquete a partir de un ensamblado, puede generar un .nuspec archivo 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 y, por tanto, todavía contienen marcadores de posición.

Desde un proyecto de Visual Studio

Crear .nuspec a partir de un archivo .csproj o .vbproj es conveniente porque otros paquetes instalados en ese proyecto se referencian automáticamente como dependencias. Simplemente use el siguiente comando en la misma carpeta que el archivo del proyecto:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

El archivo resultante <project-name>.nuspec 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 packy obtenga el archivo .nuspec desde el archivo .nupkg generado. Por ejemplo, use el siguiente comando.

# Use in a folder containing a project file <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 aparecer de la siguiente manera:

<id>$id$</id>

Este token se reemplaza por el valor AssemblyName del archivo del proyecto durante el tiempo de empaquetado. Para obtener el mapeo exacto de los valores del proyecto a los .nuspec tokens, consulte la referencia de Tokens de Reemplazo.

Los tokens le evitan tener que actualizar valores cruciales como el número de versión en .nuspec a medida que actualiza el proyecto. (Siempre puede reemplazar los tokens por valores literales, si lo desea).

Tenga en cuenta que hay varias opciones de empaquetado adicionales disponibles al trabajar desde un proyecto de Visual Studio, como se describe en Ejecución del paquete nuget para generar el archivo .nupkg más adelante.

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 del 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 sus carpetas directas lib, contento build y ninguna de sus dependencias tiene archivos en sus respectivas libcarpetas , contento build .

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

Nuevo archivo con valores predeterminados

El siguiente comando crea un manifiesto predeterminado con marcadores de posición, lo que garantiza que comience con la estructura de archivos adecuada:

nuget spec [<package-name>]

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

El resultado .nuspec contiene marcadores de posición para valores como .projectUrl Asegúrese de editar el archivo antes de usarlo para crear el archivo final .nupkg .

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 porque 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 nuget.org o cualquier galería que hospede el paquete. 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..
  • Nombres similares al espacio de nombres: siga un patrón similar a los espacios de nombres en .NET, mediante la notación de 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. (Por supuesto, el paquete de ejemplo tendría una dependencia en el otro paquete). Al crear un paquete de ejemplo, use el método de directorio de trabajo basado en convención descrito anteriormente. En la content carpeta , 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, aunque esto no es estrictamente necesario. Esto es una cuestión 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, asegúrese de tener en cuenta las reglas de control de versiones de NuGet, como se explica en Control de versiones de paquetes.

La siguiente serie de entradas de blog breves también son útiles para comprender el control de versiones:

Agregar un archivo readme y otros archivos

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

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Sugerencia

Al usar el enfoque de directorio de trabajo basado en convención, puede colocar el readme.txt en la raíz del paquete y otros contenidos en la carpeta content. No son necesarios elementos <file> en el manifiesto.

Cuando se incluye un archivo denominado readme.txt en la raíz del paquete, Visual Studio muestra el contenido de ese archivo como texto sin formato inmediatamente después de instalar el paquete directamente. (Los archivos Léame no se muestran para los paquetes instalados como dependencias). Por ejemplo, así aparece el archivo README del paquete HtmlAgilityPack:

Visualización de un archivo Léame para un paquete NuGet tras la instalación

Nota:

Si incluye un nodo vacío <files> en el .nuspec archivo, NuGet no incluye ningún otro contenido en el paquete que no sea lo que se encuentra en la lib carpeta.

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 en proyectos que consumen el paquete, como ejecutar una herramienta personalizada o un proceso durante la compilación. Puede obtener más información sobre las propiedades y objetivos de MSBuild en paquetes NuGet.

Cree <package_id>.targets o <package_id>.props (como Contoso.Utility.UsefulStuff.targets) dentro de las carpetas de compilación del proyecto.

A continuación, en el .nuspec archivo, asegúrese de hacer referencia a estos archivos en el <files> nodo:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

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

Cuando se agregan paquetes a un proyecto, NuGet incluirá automáticamente los archivos .props y .targets.

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

Al usar un ensamblado o el directorio de trabajo basado en convención, cree un paquete ejecutando nuget pack con el archivo .nuspec, y sustituya <project-name> por su nombre de archivo específico.

nuget pack <project-name>.nuspec

Al usar un proyecto de Visual Studio, ejecute nuget pack con el archivo del proyecto, que carga automáticamente el archivo del .nuspec proyecto y reemplaza los tokens que contiene mediante valores en el archivo del proyecto:

nuget pack <project-name>.csproj

Nota:

El uso del archivo de proyecto directamente es necesario para el reemplazo de tokens porque el proyecto es el origen de los valores del token. El reemplazo de tokens no se produce si usa nuget pack con un .nuspec archivo.

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 .nuspec archivo que necesitan corregirse, como olvidar cambiar los valores de marcador de posición en el manifiesto.

Una vez nuget pack que tiene éxito, tendrá un archivo .nupkg que puede publicar en una galería adecuada, según se describe en Publicación de un paquete.

Sugerencia

Una manera útil de examinar un paquete después de crearlo es abrirlo en la herramienta Explorador de paquetes . Esto le proporciona una vista gráfica del contenido del paquete y su manifiesto. También puede cambiar el nombre del archivo resultante .nupkg a un .zip archivo y explorar su contenido directamente.

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 la referencia del comando pack.

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 lo que 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 .nuspec archivo propio, NuGet agrega ese proyecto al que se hace referencia como una dependencia en su lugar. Debe empaquetar y publicar ese proyecto por separado.

  • Configuración de compilación: De forma predeterminada, NuGet usa el conjunto de configuración de compilación predeterminado en el archivo de proyecto, normalmente Depurar. Para empaquetar archivos de 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 permiten a los consumidores recorrer paso a paso por el código del paquete en el depurador, use la -Symbols opción :

    nuget pack MyProject.csproj -symbols

Prueba de la instalación del paquete

Antes de publicar un paquete, normalmente quiere probar el proceso de instalación de un paquete en un proyecto. Las pruebas verifican que todos los archivos necesarios se colocan en las ubicaciones correctas en el proyecto.

Puede probar las instalaciones manualmente en Visual Studio o en la línea de comandos mediante los pasos de instalación de paquetes normales.

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

  1. Copie el .nupkg archivo en una carpeta local.
  2. Agregue la carpeta a los orígenes del paquete mediante el comando nuget sources add -name <name> -source <path> (consulte nuget sources). Tenga en cuenta que solo necesita establecer este origen local una vez en cualquier equipo determinado.
  3. Instala el paquete desde esa fuente mediante nuget install <packageID> -source <name> donde <name> coincida con el nombre de tu fuente tal como se indica a nuget sources. Especificar el origen garantiza que el paquete se instala solo desde ese origen.
  4. Examine el sistema de archivos para comprobar que los archivos están instalados correctamente.

Pasos siguientes

Una vez que haya creado un paquete, que es un .nupkg archivo, puede publicarlo en la galería que prefiera, tal como se describe en Publicación de un paquete.

Es posible que también desee ampliar las funcionalidades del paquete o admitir otros escenarios, tal como se describe en los temas siguientes:

Por último, hay tipos de paquete adicionales que debe tener en cuenta:

  • Last updated on