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

  • Artículo
  • 7 minutos para leer

Con independencia de lo que haga el paquete o lo que contenga el código, use una de las herramientas de CLI, ya sea nuget.exe o dotnet.exe, para empaquetar esa funcionalidad en un componente que se pueda compartir y usar por parte de otros desarrolladores. En este artículo se describe cómo crear un paquete con la CLI de dotnet. Para instalar la CLI de dotnet, consulte dotnet. A partir de Visual Studio 2017, la CLI de dotnet se incluye con las cargas de trabajo de .NET Core.

Con los proyectos .NET Core y .NET Standard que usan el formato de estilo SDK y cualquier otro proyecto de estilo SDK, NuGet usa la información del archivo de proyecto directamente para crear un paquete. Para consultar tutoriales paso a paso, vea Creación de paquetes de .NET Standard con la CLI de dotnet o Creación de paquetes de .NET Standard con Visual Studio.

msbuild -t:pack es funcionalmente equivalente a dotnet pack. Para compilar con MSBuild, vea Creación de un paquete de NuGet con MSBuild.

Importante

Este tema se aplica a los proyectos de estilo SDK, por lo general proyectos de .NET Core y .NET Standard.

Establecimiento de las propiedades

Las propiedades siguientes se requieren para crear un paquete.

  • PackageId, el identificador de paquete, que debe ser único en la galería que hospeda el paquete. Si no se especifica, el valor predeterminado es AssemblyName.
  • Version, un número de versión específico con el formato Version donde -Sufijo identifica las versiones preliminares. Si no se especifica, el valor predeterminado es 1.0.0.
  • El título del paquete como debe aparecer en el host (por ejemplo, nuget.org)
  • Authors, información del autor y el propietario. Si no se especifica, el valor predeterminado es AssemblyName.
  • Company, el nombre de la empresa. 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, elija Propiedades y seleccione la pestaña Paquete). También puede establecer estas propiedades directamente en los archivos del proyecto (.csproj).

<PropertyGroup>
  <PackageId>AppLogger</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Importante

Asigne al paquete un identificador que sea único en nuget.org o en el origen de paquete que esté usando.

En el ejemplo siguiente se muestra un archivo del proyecto sencillo y completo que incluye estas propiedades. (Puede crear un nuevo proyecto predeterminado mediante el comando dotnet new classlib).

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>AppLogger</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

También puede establecer las propiedades opcionales, como Title, PackageDescription y PackageTags, tal como se describe en los Title, la sección PackageDescription y PackageTags.

Nota

En el caso de los paquetes creados para consumo público, preste especial atención la propiedad PackageTags, dado que estas etiquetas ayudan a otros usuarios a encontrar el paquete y comprender lo que hace.

Para obtener más información sobre cómo declarar dependencias y especificar números de versión, vea Referencias del paquete en archivos del proyecto y Control de versiones de paquetes. También es posible exponer recursos directamente desde las dependencias en el paquete mediante los atributos <IncludeAssets> y <ExcludeAssets>. Para obtener más información, consulte Controlar los recursos de dependencias.

Adición de un campo opcional de descripción

La descripción opcional del paquete, que se muestra en la página NuGet.org del paquete, se extrae del elemento <description></description> que se usa en el archivo .csproj o a través del elemento $description en el <description></description>.

En el siguiente texto XML del archivo de un paquete .NET se muestra un ejemplo de un campo de descripción :

<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://docs.microsoft.com/en-us/azure/storage/
      Microsoft Azure Storage REST API Reference - https://docs.microsoft.com/en-us/rest/api/storageservices/
      REST API Reference for Blob Service - https://docs.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

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 son los dos valores más importantes del proyecto, ya que identifican de forma única el código exacto que se incluye en el paquete.

Procedimientos recomendados para el identificador del paquete:

  • Unicidad: el identificador debe ser único en nuget.org o en la galería que hospede el paquete. Antes de decidirse por un identificador, busque en la galería aplicable para comprobar si el nombre ya está en uso. Para evitar conflictos, un buen patrón consiste en usar el nombre de la empresa como la primera parte del identificador, por ejemplo Contoso..
  • Nombres de tipo espacio de nombres: siguen un patrón similar a los espacios de nombres de .NET, con notación de puntos en lugar de guiones. Por ejemplo, use Contoso.Utility.UsefulStuff en lugar de Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. También es útil para los consumidores cuando el identificador del paquete coincide con los espacios de nombres que se usan en el código.
  • Paquetes de ejemplo: si genera un paquete de código de ejemplo que muestra cómo usar otro paquete, adjunte como sufijo al identificador, como en Contoso.Utility.UsefulStuff.Sample. (El paquete de ejemplo tendría evidentemente una dependencia en el otro paquete). Cuando cree un paquete de ejemplo, use el valor contentFiles en <IncludeAssets>. En la carpeta content, 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 el proyecto (o ensamblado), aunque esto no es estrictamente necesario. Esto resulta muy sencillo cuando limita un paquete a un solo ensamblado. En general, recuerde que el propio NuGet trabaja con versiones del paquete al resolver las dependencias, no con versiones de ensamblado.
  • Cuando se usa un esquema de la 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 semver 2.

Para información sobre la resolución de las dependencias, consulte Resolución de dependencias con PackageReference. Para información anterior que también podría ser útil para entender mejor el control de versiones, consulte esta serie de entradas de blog.

Ejecutar el comando pack

Para compilar un paquete NuGet (un archivo .nupkg) desde el proyecto, ejecute el comando dotnet pack, que también genera el proyecto automáticamente:

# Uses the project file in the current folder by default
dotnet pack

El resultado mostrará la ruta de acceso al archivo .nupkg.

Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 29.91 ms for D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj.
  AppLogger -> D:\proj\AppLoggerNet\AppLogger\bin\Debug\netstandard2.0\AppLogger.dll
  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 automáticamente dotnet pack al ejecutar dotnet build, agregue la siguiente línea al archivo de proyecto en <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Cuando ejecuta dotnet pack en una solución, se empaquetan todos los proyectos de la solución que se pueden empaquetar (la propiedad se establece en true).

Nota

Cuando genera automáticamente el paquete, el tiempo de empaquetado aumenta el tiempo de compilación del proyecto.

Prueba de instalación del paquete

Antes de publicar un paquete, normalmente querrá probar el proceso de instalación de un paquete en un proyecto. Las pruebas aseguran que todos los archivos necesarios acaban en los lugares correctos en el proyecto.

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

Importante

Los paquetes son inmutables. Si corrige un problema, cambie el contenido del paquete y vuelva a empaquetar. Cuando vuelva a realizar la prueba, seguirá usando la versión anterior del paquete hasta que bote la carpeta global de paquetes. Esto resulta especialmente relevante cuando se prueban paquetes que no usan una etiqueta preliminar única en cada compilación.

Pasos siguientes

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

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

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