Compartir a través de

Inicio rápido: Creación y publicación de un paquete con la CLI de dotnet

  • Artículo

En este inicio rápido se muestra cómo crear rápidamente un paquete NuGet desde una biblioteca de clases de .NET y publicarlo en nuget.org mediante la interfaz de la línea de comandos de .NET o la CLI de dotnet.

Requisitos previos

  • El SDK de .NET, que ofrece la herramienta de línea de comandos de dotnet. A partir de Visual Studio 2017, la CLI de dotnet se instala automáticamente con cualquier carga de trabajo relacionada con .NET o .NET Core.

  • Una cuenta gratuita en nuget.org. Siga las instrucciones que aparecen en Agregar una nueva cuenta individual.

Crear un proyecto de biblioteca de clases

Puede usar un proyecto de biblioteca de clases de .NET existente para el código que quiera empaquetar o puede crear un proyecto simple tal y como se indica a continuación:

  1. Cree una carpeta llamada AppLogger.
  2. Abra un símbolo del sistema y cambie a la carpeta AppLogger. Todos los comandos de la CLI de dotnet de este inicio rápido se ejecutan en la carpeta actual de forma predeterminada.
  3. Escriba dotnet new classlib, que crea un proyecto con el nombre de la carpeta actual.

Para más información, vea dotnet new.

Agregar metadatos de paquete al archivo de proyecto

Cada paquete NuGet necesita un manifiesto que describa su contenido y sus dependencias. En el paquete final, el manifiesto es un archivo .nuspec que usa las propiedades de metadatos de NuGet que incluye en el archivo de proyecto.

Abra el archivo de proyecto .csproj, .fsproj o .vbproj y agregue las siguientes propiedades dentro de la etiqueta <PropertyGroup> existente. Use sus propios valores para el nombre y la empresa y reemplace el identificador del paquete con un valor único.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Importante

El identificador del paquete debe ser único entre nuget.org y otros orígenes de paquete. La publicación hace que el paquete sea visible públicamente, por lo que si usa la biblioteca AppLogger de ejemplo u otra biblioteca de prueba, use un nombre único que incluya Sample o Test.

Puede agregar cualquier propiedad opcional que se describe en Propiedades de metadatos de NuGet.

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.

Ejecutar el comando pack

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

dotnet pack

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

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

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

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

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Publicar el paquete

Publique el archivo .nupkg en nuget.org mediante el comando dotnet nuget push con una clave de API que obtenga de nuget.org.

Nota:

  • Nuget.org examina todos los paquetes cargados en busca de virus y los rechaza si encuentra algún virus. Nuget.org también analiza periódicamente todos los paquetes existentes que aparecen en la lista.

  • A menos que se quiten de la lista, los paquetes que publique en nuget.org están visibles públicamente para otros desarrolladores. Para hospedar paquetes de forma privada, consulte Hospedar sus propias fuentes de NuGet.

Obtener la clave de API

  1. Inicie sesión en su cuenta de nuget.org o cree una cuenta si aún no tiene una.

  2. Seleccione el nombre de usuario (en la esquina superior derecha) y luego Claves de API.

  3. Seleccione Crear y proporcione un nombre para la clave.

  4. En Seleccionar ámbitos, seleccione Insertar.

  5. En Seleccionar paquetes>Patrón global, escriba *.

  6. Seleccione Crear.

  7. Seleccione Copiar para copiar la clave nueva.

    Captura de pantalla que muestra la nueva clave de API con el vínculo Copiar.

Importante

  • Mantenga siempre la clave de API en secreto. La clave de API es como una contraseña que permite a cualquier usuario administrar paquetes en su nombre. Debe eliminar o volver a generar la clave de API si se revela accidentalmente.
  • Guarde la clave en una ubicación segura, ya que después no se puede volver a copiar. Si vuelve a la página de clave de API, ha de volver a generar la clave para copiarla. También puede quitar la clave de API si ya no desea insertar paquetes.

El ámbito le permite crear claves de API independientes con distintos fines. Cada clave tiene su período de expiración y su ámbito puede establecerse en paquetes específicos (o patrones globales). También puede limitar el uso de cada clave a operaciones específicas; por ejemplo, insertar nuevos paquetes y versiones de paquete, insertar solo nuevas versiones de paquete o quitar de la lista.

Gracias a esta limitación, puede crear claves de API para distintas personas que administran paquetes para su organización, de manera que solo tengan los permisos que necesiten.

Para más información, consulte las claves de API con ámbito.

Publicar con dotnet nuget push

En la carpeta que contiene el archivo .nupkg, ejecute el siguiente comando. Especifique el nombre de archivo .nupkg y reemplace el valor de clave por la clave de API.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

En la ventana de salida se muestran los resultados del proceso de publicación:

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Para obtener más información, consultedotnet nuget push.

Nota:

Si desea evitar que el paquete de prueba esté activo en nuget.org, puede insertarlo en el sitio de prueba de nuget.org en https://int.nugettest.org. Tenga en cuenta que es posible que no se conserven los paquetes que haya cargado en int.nugettest.org.

Errores de publicación

Los errores del comando push suelen indicar el problema. Por ejemplo, es posible que haya olvidado actualizar el número de versión del proyecto y, por tanto, está intentando publicar un paquete que ya existe.

También verá errores si la clave de API no es válida o ha expirado, o si intenta publicar un paquete mediante un identificador que ya existe en el host. Supongamos, por ejemplo, que el identificador AppLogger-test ya existe en nuget.org. Si intenta publicar un paquete con ese identificador, el comando push devuelve el siguiente error:

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

Si recibe este error, compruebe que usa una clave de API válida que no haya expirado. Si es así, el error indica que el identificador del paquete ya existe en el host. Para corregir este error, cambie el identificador del paquete para que sea único, vuelva a generar el proyecto, vuelva a crear el archivo .nupkg e intente ejecutar de nuevo el comando push.

Administrar el paquete publicado

Cuando el paquete se publique correctamente, recibirá un correo electrónico de confirmación. Para ver el paquete que acaba de publicar, vaya a nuget.org y seleccione el nombre de usuario en la esquina superior derecha; a continuación, seleccione Administrar paquetes.

Nota:

Es posible que se tarde un tiempo en indexar el paquete y en ver que aparece en los resultados de la búsqueda donde otros usuarios puedan encontrarlo. Durante ese tiempo, el paquete aparece en Paquetes no registrados y la página del paquete muestra el mensaje siguiente:

Captura de pantalla que muestra el mensaje de publicación que se visualiza al cargar un paquete en nuget.org.

Acaba de publicar un paquete NuGet en nuget.org que otros desarrolladores pueden usar en sus propios proyectos.

Si ha creado un paquete que no es útil (por ejemplo, este paquete de muestra que se creó con una biblioteca de clases vacía) o no quiere que el paquete sea visible, puede quitar de la lista el paquete para ocultarlo de los resultados de la búsqueda:

  1. Después de que el paquete aparezca en Paquetes publicados en la página Administrar paquetes, seleccione el icono con forma de lápiz situado junto a la lista de paquetes.

    Captura de pantalla que muestra el icono Editar de una lista de paquetes en nuget.org.

  2. En la página siguiente, seleccione Lista, anule la selección de la casilla Enumerar en los resultados de la búsqueda y, a continuación, seleccione Guardar.

    Captura que muestra el borrado de la casilla de lista de un paquete en nuget.org

El paquete aparece ahora en Paquetes no registrados de la opción Administrar paquetes y ya no aparecerá en los resultados de la búsqueda.

Nota:

Para evitar que el paquete de prueba esté activo en nuget.org, puede insertarlo en el sitio de prueba de nuget.org en https://int.nugettest.org. Tenga en cuenta que es posible que no se conserven los paquetes que haya cargado en int.nugettest.org.

¡Enhorabuena por crear y publicar su primer paquete NuGet!

Encuentre más vídeos de NuGet en Channel 9 y YouTube.

Pasos siguientes

Consulte más detalles sobre cómo crear paquetes con la CLI de dotnet:

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

Obtenga más información sobre cómo crear y publicar paquetes de NuGet: