Compartir a través de

Inicio rápido: Creación y publicación de un paquete NuGet con Visual Studio (solo en Windows)

  • Artículo

Gracias a Microsoft Visual Studio, puede crear un paquete NuGet desde una biblioteca de clases de .NET y publicarla en nuget.org con una herramienta CLI.

El inicio rápido es solo para usuarios de Windows. Si usa Visual Studio para Mac, consulte Creación de un paquete NuGet a partir de proyectos de biblioteca existentes o use la CLI de .NET.

Requisitos previos

  • Instale Visual Studio 2022 para Windows con una carga de trabajo relacionada con .NET Core.

    Puede instalar la edición 2022 Community de forma gratuita desde visualstudio.microsoft.com o utilizar la edición Professional o Enterprise.

    Visual Studio 2017 y otras versiones posteriores incluyen automáticamente funcionalidades de NuGet cuando se instala una carga de trabajo relacionada con .NET.

  • Instale la CLI de .NET si no la tiene instalada ya.

    A partir de Visual Studio 2017 y versiones posteriores, la CLI de .NET se instala automáticamente con cualquier carga de trabajo relacionada con .NET Core. De lo contrario, instale el SDK de .NET Core para obtener la CLI de .NET. La CLI de .NET es necesaria para los proyectos de .NET que usan el formato de estilo SDK (atributo SDK). La plantilla de biblioteca de clases de .NET predeterminada en Visual Studio 2017 y versiones posteriore, utiliza el atributo SDK.

    Importante

    Si está trabajando con un proyecto que no sea de estilo SDK, siga los procedimientos que se describen en Creación y publicación de un paquete de .NET Framework (Visual Studio) para crear y publicar el paquete. En este artículo, se recomienda la CLI de .NET. Aunque puede publicar cualquier paquete NuGet mediante la CLI de .NET, algunos de los pasos de este artículo son específicos de los proyectos de estilo SDK y de la CLI de .NET. La CLI de NuGet se usa con proyectos que no son de estilo SDK (normalmente .NET Framework).

  • Registrar una cuenta gratuita en nuget.org si aún no tiene uno. Debe registrarse y confirmar la cuenta antes de cargar un paquete NuGet.

  • Instale la CLI de NuGet descargándola desde nuget.org, agregue el archivo nuget.exe en la carpeta adecuada y agregue esa carpeta a la variable de entorno PATH.

Crear un proyecto de biblioteca de clases

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

  1. Abra Visual Studio, seleccione Archivo>Nuevo>Proyecto.

  2. En la ventana Crear un nuevo proyecto, seleccione C#, Windows y Biblioteca en las listas desplegables.

  3. En la lista resultante de plantillas de proyecto, seleccione Biblioteca de clases (con la descripción Un proyecto para crear una biblioteca de clases que tenga como destino .NET o .NET Standard) y, a continuación, seleccione Siguiente.

  4. En la ventana Configurar el nuevo proyecto, escriba AppLogger como Nombre del proyecto y, después, seleccione Siguiente.

  5. En la ventana Información adicional, seleccione un marco adecuado y luego Crear.

    Si no sabe qué marco seleccionar, la versión más reciente es una buena opción y se puede cambiar fácilmente más adelante. Para obtener información sobre qué marco puede usar, consulte Cuándo se debe tener como destino .NET 5.0 o .NET 6.0 frente a .NET Standard.

  6. Para asegurarse de que el proyecto se creó correctamente, seleccione Compilar>Solución de compilación. El archivo DLL se encuentra en la carpeta Debug (o Release si en su lugar compila esa configuración).

  7. (Opcional) En este inicio rápido, no es necesario escribir ningún código adicional para el paquete NuGet porque la biblioteca de clases de la plantilla es suficiente para crear un paquete. No obstante, si desea agregar algún código funcional para el paquete, incluya el código siguiente:

    namespace AppLogger
{
    public class Logger
    {
        public void Log(string text)
        {
            Console.WriteLine(text);
        }
    }
}

Configurar propiedades del paquete

Después de crear el proyecto, puede configurar las propiedades del paquete NuGet siguiendo estos pasos:

  1. Seleccione el proyecto en el Explorador de soluciones y, a continuación, seleccione Proyecto>Propiedades de <nombre del proyecto>, donde <nombre del proyecto> es el nombre del proyecto.

  2. Expanda el nodo Paquete y, a continuación, seleccione General.

    El nodo Paquete solo aparece para proyectos de estilo SDK en Visual Studio. Si tiene como destino un proyecto de estilo que no es de SDK (normalmente .NET Framework), migre el proyecto o consulte Creación y publicación de un paquete de .NET Framework para obtener instrucciones paso a paso.

    Screenshot showing NuGet package properties in a Visual Studio project.

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

  4. Asigne al paquete un id. de paquete único y rellene las demás propiedades que quiera. Para obtener una tabla que muestra cómo las propiedades de MSBuild (para proyectos de estilo SDK) se asignan a las propiedades del archivo .nuspec, consulte los destinos del paquete. Para obtener una descripción de las propiedades del archivo .nuspec, consulte la referencia del archivo .nuspec. Todas las propiedades que aparecen aquí pasan al manifiesto .nuspec que Visual Studio crea para el proyecto.

    Importante

    Debe asignar al paquete un identificador que sea único en nuget.org o en el host que use. De lo contrario, se produce un error. En este inicio rápido se recomienda incluir Sample o Test en el nombre, ya que el paso de publicación hace que el paquete sea visible públicamente.

  5. (Opcional) Para ver las propiedades directamente en el archivo de proyecto AppLogger.csproj, seleccione Proyecto>Editar archivo del proyecto.

    Se carga la pestaña AppLogger.csproj.

    Esta opción solo está disponible a partir de Visual Studio 2017 para proyectos que usan el atributo de estilo SDK. Para versiones anteriores de Visual Studio, debe seleccionar Proyecto>Descargar proyecto para poder editar el archivo del proyecto.

Ejecutar el comando pack

Para crear un paquete NuGet desde el proyecto, siga estos pasos:

  1. Seleccione Compilar>Administrador de configuración y, a continuación, establezca la configuración de la solución activa en Versión.

  2. Seleccione el proyecto AppLogger en el Explorador de soluciones y, a continuación, seleccione Empaquetar.

    Visual Studio compila el proyecto y crea el archivo .nupkg.

  3. Examine la ventana Resultados para obtener más información, ya que contiene la ruta de acceso al archivo de paquete. En este ejemplo, el ensamblado compilado está en bin\Release\net6.0, según corresponda a un destino de .NET 6.0:

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

  4. Si no ve el comando Empaquetar en el menú, es probable que el proyecto no sea un proyecto de estilo SDK y que tenga que usar la CLI de NuGet. Migre el proyecto y use la CLI de .NET, o consulte el artículo Creación y publicación de un paquete de .NET Framework para obtener instrucciones paso a paso.

(Opcional) Generación del paquete en la compilación

Puede configurar Visual Studio para que genere automáticamente el paquete NuGet al compilar el proyecto:

  1. Seleccione el proyecto en el Explorador de soluciones y, a continuación, seleccione Proyecto>Propiedades de <nombre del proyecto>, donde <nombre del proyecto> es el nombre del proyecto (AppLogger en este caso).

  2. Expanda el nodo Paquete, seleccione General y, a continuación, seleccione Generar paquete NuGet al compilar.

    Screenshot showing package properties with Generate NuGet package on build selected.

Nota:

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

(Opcional) Empaquetado con MSBuild

Como alternativa al uso del comando de menú Empaquetar, NuGet 4.x y MSBuild 15.1 y las versiones posteriores de ambos admiten un destino de pack cuando el proyecto contiene los datos necesarios del paquete:

  1. Con el proyecto abierto en el Explorador de soluciones, abra un símbolo del sistema seleccionando Herramientas>Línea de comandos>Símbolo del sistema para desarrolladores.

    El símbolo del sistema se abre en el directorio del proyecto.

  2. Ejecute el siguiente comando: msbuild -t:pack.

Para obtener más información, consulte Creación de un paquete con MSBuild.

Publicar el paquete

Cuando haya creado un archivo .nupkg, publíquelo en nuget.org mediante la CLI de .NET o la CLI de NuGet y una clave de API adquirida 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.

Adquirir la clave de API

Antes de publicar el paquete NuGet, cree una 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.

    Screenshot that shows the new API key with the Copy link.

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.

Publicación con la CLI de .NET o la CLI de NuGet

Cada una de las siguientes herramientas de la CLI le permite insertar un paquete en el servidor y publicarlo. Seleccione la pestaña de la herramienta de la CLI, ya sea la CLI de .NET o la CLI de NuGet.

El uso de la CLI de .NET (dotnet.exe) es la alternativa recomendada al uso de la CLI de NuGet.

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:

Screenshot showing the publishing message that's displayed when you upload a package to 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.

    Screenshot that shows the Edit icon for a package listing on 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.

    Screenshot that shows clearing the List checkbox for a package on 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.

Inserción de un archivo Léame y otros archivos

Para especificar directamente los archivos que quiere incluir en el paquete, edite el archivo del proyecto y agregue la propiedad content:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

En este ejemplo, la propiedad especifica un archivo denominado readme.txt en la raíz del proyecto. Visual Studio muestra el contenido de ese archivo como texto sin formato inmediatamente después de instalar el paquete. Los archivos Léame no se muestran para paquetes instalados como dependencias. Por ejemplo, este es el aspecto del archivo Léame para el paquete HtmlAgilityPack:

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. 
7 This is normally found at 
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client 
9 or 
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. 
14 This is normally found at 
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client 
16 or 
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Nota:

Si solo agrega readme.txt en la raíz del proyecto sin incluirlo en la propiedad content del archivo del proyecto, no se incluirá en el paquete.

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

¡Enhorabuena! Ha creado un paquete NuGet mediante una biblioteca de clases de Visual Studio .NET. Vaya al siguiente artículo para aprender a crear un paquete NuGet con Visual Studio .NET Framework.

Creación de un paquete con la CLI de NuGet

Para explorar más y saber todo lo que NuGet tiene que ofrecer, consulte los artículos siguientes: