Compartir a través de

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

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 Instalación de herramientas de cliente de NuGet.

Este tema solo se aplica a .NET y a otros proyectos que usan el formato de estilo SDK. Para estos proyectos, NuGet usa información del archivo de proyecto para crear un paquete. Para ver tutoriales de inicio rápido, consulte Creación de paquetes con la CLI de dotnet o Creación de paquetes con Visual Studio.

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

Nota:

Configurar propiedades

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

  • PackageId, el identificador del paquete debe ser único en nuget.org y cualquier otro destino que hospede el paquete. Si no especifica un valor, el comando usa .AssemblyName
  • Version es un número de versión específico con el formato 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 información de la empresa. Si no se especifica, el valor predeterminado es el Authors valor.
  • Product es 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 agregar las propiedades directamente al archivo .csproj u otro archivo de proyecto.

En el ejemplo siguiente se muestra un archivo de proyecto con las propiedades del paquete agregadas.

<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, PackageDescriptiony 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 usuarios a encontrar el paquete y a comprender lo que hace.

El comando dotnet pack convierte automáticamente los PackageReferences en los archivos de su proyecto en dependencias del paquete creado. Puede controlar qué recursos se van a incluir a través de las IncludeAssetsetiquetas , ExcludeAssets y PrivateAssets . Para obtener más información, consulte Control de los recursos de dependencia.

Para obtener más información sobre las dependencias, las propiedades opcionales y el control de versiones, consulte:

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

El identificador del paquete y el número de versión identifican de forma única el código exacto contenido en 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 hospedan el paquete. Para evitar conflictos, un buen patrón es usar el nombre de la empresa como primera parte del identificador.

  • Siga una convención de nomenclatura similar a un espacio de nombres de .NET mediante la notación de puntos. Por ejemplo, use Contoso.Utility.UsefulStuff en lugar de Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. También resulta útil para los consumidores si el identificador del paquete coincide con el espacio de nombres que usa el código.

  • Si genera un paquete de código de ejemplo que muestra cómo usar otro paquete, anexe .Sample al identificador, como en Contoso.Utility.UsefulStuff.Sample.

    El paquete de ejemplo tiene una dependencia del paquete original. Al crear el paquete de ejemplo, agregue <IncludeAssets> con el valor de contentFiles. En la carpeta de contenido , organice el código de ejemplo en una carpeta denominada \Samples\<identifier>, como \Samples\Contoso.Utility.UsefulStuff.Sample.

Siga estos procedimientos recomendados para establecer la versión del paquete:

  • En general, establezca la versión del paquete para que coincida con el proyecto o la versión del ensamblado, aunque esto no es estrictamente necesario. Coincidir con la versión es fácil cuando se limita un paquete a un único ensamblado. NuGet se ocupa de las versiones del paquete al resolver las dependencias, no las versiones de ensamblado.

  • Si usa 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 versiones semánticas 2.0.0.

Nota:

Para obtener más información sobre la resolución de dependencias, consulte Resolución de dependencias con PackageReference. Para obtener información que pueda ayudarle a comprender el control de versiones, consulte esta serie de entradas de blog:

Agregar un campo de descripción opcional

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 del <Description> en el archivo del proyecto o del $description en el archivo .nuspec.

En el ejemplo siguiente se muestra un 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

La salida muestra la ruta de acceso 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'.

Generar automáticamente el paquete en la compilación

Para ejecutar dotnet pack automáticamente cada vez que ejecute dotnet build, agregue la siguiente línea al archivo del proyecto en el etiqueta <PropertyGroup>.

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Nota:

Al generar automáticamente 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 configurada en true.

Prueba de la instalación del paquete

Antes de publicar un paquete, debe probar la instalación del paquete en un proyecto. Las pruebas garantizan que los archivos necesarios terminen en sus lugares correctos en el proyecto.

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

Importante

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

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

Pasos siguientes

Una vez creado el paquete, puede publicar el archivo .nupkg en el host que prefiera.

Publicación de un paquete

Consulte los artículos siguientes para obtener formas de ampliar las funcionalidades del paquete o admitir otros escenarios:

  • Last updated on