Creación de un paquete NuGet con la CLI de dotnet

  • Artículo

Los paquetes NuGet contienen código que los desarrolladores pueden reutilizar en sus proyectos. Independientemente de lo que haga o contenga el código, use una herramienta de línea de comandos, ya sea nuget.exe o dotnet.exe, para crear el paquete NuGet.

En este artículo se describe cómo crear un paquete mediante la CLI de dotnet. A partir de Visual Studio 2017, la CLI de dotnet se incluye con todas las cargas de trabajo de .NET y .NET Core. Si necesita instalar la CLI de dotnet u otras herramientas cliente de NuGet, consulte Instalar herramientas cliente de NuGet.

Este tema se aplica únicamente a proyectos .NET y otros proyectos que utilizan el formato estilo SDK. Para estos proyectos, NuGet utiliza información del archivo de proyecto con el fin de crear un paquete. Si desea ver tutoriales de inicio rápido, consulte Crear paquetes con la CLI de dotnet o Crear paquetes con Visual Studio.

El comando msbuild -t:pack de MSBuild es funcionalmente equivalente a dotnet pack. Para más información sobre cómo crear un paquete con MSBuild, consulte Crear un paquete NuGet con MSBuild.

Nota:

Establecimiento de las propiedades

Puede crear un proyecto de biblioteca de clases de ejemplo con el comando dotnet new classlib y empaquetar el proyecto con dotnet pack. El comando dotnet pack utiliza las siguientes propiedades Si no especifica valores en el archivo de proyecto, el comando utiliza valores predeterminados.

  • PackageId, el identificador del paquete, debe ser único en nuget.org y en cualquier otro destino que aloje el paquete. Si no se especifica un valor, el comando utiliza AssemblyName.
  • Version es un número de versión específico en la forma Major.Minor.Patch[-Suffix], donde -Suffix identifica las versiones preliminares. Si no se especifica, el valor predeterminado es 1.0.0.
  • Authors son los autores del paquete. Si no se especifica, el valor predeterminado es AssemblyName.
  • Company es la información sobre la compañía. Si no se especifica, el valor predeterminado es Authors.
  • Product es la información del producto. Si no se especifica, el valor predeterminado es AssemblyName.

En Visual Studio, puede establecer estos valores en las propiedades del proyecto. Haga clic con el botón derecho en el proyecto en el Explorador de soluciones, seleccione Propiedades y, a continuación, seleccione la sección Paquete. También puede añadir las propiedades directamente al archivo .csproj u otro archivo de proyecto.

El siguiente ejemplo muestra un archivo de proyecto con propiedades de paquete añadidas.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Puede agregar otras propiedades opcionales, como Title, PackageDescription y PackageTags.

Nota:

En el caso de los paquetes que cree para el consumo público, preste especial atención a la propiedad PackageTags. Las etiquetas ayudan a otros a encontrar su paquete y entender lo que hace.

El comando dotnet pack convierte automáticamente PackageReference en sus archivos de proyecto a dependencias en el paquete creado. Puede controlar qué activos incluir mediante las etiquetas IncludeAssets, ExcludeAssets, PrivateAssets. Para obtener más información, consulte Controlar los recursos de dependencias.

Para más información sobre dependencias, propiedades opcionales y versionado, consulte:

Elección de un identificador de paquete único y establecimiento del número de versión

El identificador del paquete y el número de versión identifican de forma exclusiva el código exacto que contiene el paquete.

Siga estos procedimientos recomendados para crear el identificador del paquete:

  • El identificador debe ser único en nuget.org y en todas las demás ubicaciones que hospeden el paquete. Para evitar conflictos, una buena pauta es utilizar el nombre de su empresa como primera parte del identificador.

  • Siga una convención de nomenclatura similar a la de los espacios de nombres .NET, en la que se utilice la notación por puntos. Por ejemplo, use Contoso.Utility.UsefulStuff en lugar de Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. También es útil para los consumidores que el identificador del paquete coincida con el espacio de nombres que utiliza el código.

  • Si produce un paquete de código de ejemplo que demuestre cómo utilizar otro paquete, añada .Sample al identificador, como en Contoso.Utility.UsefulStuff.Sample.

    El paquete de ejemplo depende del paquete original. Al crear el paquete de muestra, añada <IncludeAssets> con el valor contentFiles. En la carpeta de contenido, organice el código de ejemplo en una carpeta llamada \Muestras<identificador>, como \MuestrasContoso.Utilidad.UsefulStuff.Sample.

Siga este procedimiento recomendado para establecer la versión del paquete:

  • En general, establezca la versión del paquete para que coincida con la versión del proyecto o ensamblado, aunque esto no es estrictamente necesario. Hacer coincidir la versión es sencillo cuando se limita un paquete a un único ensamblado. El propio NuGet se ocupa de las versiones de los paquetes al resolver las dependencias, no de las versiones de los ensamblados.

  • Si utiliza 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. NuGet es principalmente compatible con el Versionamiento Semántico 2.0.0.

Nota:

Para más información sobre la resolución de dependencias, consulte Resolución de dependencias con PackageReference. Si desea información que le ayude a entender el versionado, consulte esta serie de entradas de blog:

Adición de un campo opcional de descripción

La descripción opcional del paquete aparece en la pestaña LÉAME de la página nuget.org del paquete. La descripción se extrae de <Description> en el archivo de proyecto o de $description en el archivo .nuspec.

El siguiente ejemplo muestra una Description en el archivo .csproj para un paquete .NET:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Ejecutar el comando pack

Para compilar el paquete NuGet o el archivo .nupkg, ejecute el comando dotnet pack desde la carpeta del proyecto, que también compila el proyecto automáticamente.

dotnet pack

El resultado muestra la ruta al archivo .nupkg:

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Generación automática del paquete en la compilación

Para ejecutar dotnet pack automáticamente cada vez que ejecute dotnet build, agrega la siguiente línea al archivo de proyecto en la etiqueta <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Nota:

Al generar de forma automática el paquete, el empaquetado aumenta el tiempo de compilación del proyecto.

Al ejecutar dotnet pack en una solución se empaquetan todos los proyectos de la solución que son empaquetables, es decir, que tienen la propiedad IsPackable establecida en true.

Prueba de instalación del paquete

Antes de publicar un paquete, debe probar su instalación en un proyecto. Las pruebas garantizan que los archivos necesarios se encuentren en el lugar correcto del proyecto.

Pruebe la instalación manualmente en Visual Studio o en la línea de comandos mediante el proceso normal de instalación de paquetes.

Importante

  • No se pueden modificar los paquetes una vez creados. Si corrige un problema, cambie el contenido del paquete y vuelva a empaquetarlo.

  • Después de volver a crear el paquete, las pruebas seguirán utilizando la versión antigua del paquete hasta que borre la carpeta global de paquetes. Borrar la carpeta es especialmente importante para los paquetes que no utilizan una etiqueta única de versión preliminar en cada compilación.

Pasos siguientes

Una vez creado el paquete, puede publicar el archivo .nupkg en el host de su elección.

Publicación de un paquete

Consulte los siguientes artículos para saber cómo ampliar las capacidades de su paquete o dar soporte a otros escenarios: