Inicio rápido: Creación y publicación de un paquete con Visual Studio (.NET Framework, Windows)

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

El inicio rápido es solo para usuarios de Windows. Si usa Visual Studio para Mac, consulte las herramientas de la CLI de dotnet en su lugar.

Requisitos previos

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

  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 superiores incluyen automáticamente funcionalidades de NuGet cuando se instala una carga de trabajo. NET.

• 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

Siga los pasos siguientes para crear un proyecto de biblioteca de clases:

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 del proyecto, seleccione Biblioteca de clases (.NET Framework) y, a continuación, seleccione Siguiente.

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

5. 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).

6. (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. Sin embargo, si desea usar algún código funcional para este paquete de muestra, incluya el código siguiente:

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

   Dentro de un paquete NuGet real, se implementan muchas características útiles con las que otros usuarios pueden compilar aplicaciones. También puede establecer las plataformas de destino como quiera. Para obtener ejemplos, consulte UWP y Xamarin.

Configurar las propiedades del proyecto para el paquete

Un paquete NuGet contiene un manifiesto (un archivo .nuspec), que contiene metadatos relevantes, como el identificador del paquete, el número de versión, la descripción y mucho más. Algunos de estos metadatos se pueden obtener directamente de las propiedades del proyecto, lo que evita tener que actualizarlos por separado tanto en el proyecto como en el manifiesto. En los pasos siguientes se describe cómo establecer las propiedades aplicables:

1. Seleccione Proyecto > Propiedades y luego la pestaña Aplicación.

2. En el campo Nombre del ensamblado asigne un identificador único al paquete. Si intenta publicar un paquete con un nombre que ya existe, verá un error.

   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.

3. Seleccione el botón Información de ensamblado, que muestra un cuadro de diálogo en el que puede especificar otras propiedades que llevan al manifiesto (consulte Tokens de reemplazo). Los campos más usados son Título, Descripción, Empresa, Copyright y Versión de ensamblado. Como estas propiedades aparecen con el paquete en un host como nuget.org después de publicarlo, asegúrese de que sean lo más descriptivas posible.

   

4. (Opcional) Para ver y editar las propiedades directamente, abra el archivo Properties/AssemblyInfo.cs en el proyecto; para ello, seleccione Proyecto>Editar archivo del proyecto.

5. Después de administrar estas propiedades, establezca la configuración de la solución activa en Compilación>Administrador de configuración como Publicar y vuelva a compilar el proyecto para generar el archivo DLL actualizado.

Generación del manifiesto inicial

Después de establecer las propiedades del proyecto y crear el archivo DLL, ahora puede generar un archivo .nuspec inicial desde el proyecto. Este paso incluye los tokens de reemplazo correspondientes para extraer información del archivo de proyecto.

Ejecute nuget spec solo una vez para generar el manifiesto inicial. Si actualiza el paquete, puede cambiar los valores en el proyecto o editar el manifiesto directamente:

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 donde se encuentra el archivo AppLogger.csproj.

2. Ejecute el siguiente comando: nuget spec AppLogger.csproj.

   NuGet crea un manifiesto que coincide con el nombre del proyecto, en este caso AppLogger.nuspec. También se incluyen los tokens de reemplazo en el manifiesto.

3. Abra AppLogger.nuspec en un editor de texto para examinar su contenido, que será similar al código siguiente:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Editar el manifiesto

1. Edite las siguientes propiedades antes de continuar. De lo contrario, si intenta crear un paquete NuGet con los valores predeterminados en el archivo .nuspec, se produce un error. Para obtener información sobre estas propiedades, consulte Elementos de metadatos opcionales:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • etiquetas

2. 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.

3. También puede agregar otros elementos al manifiesto en este momento, tal como se describe en el tema Referencia de .nuspec.

4. Guarde el archivo antes de continuar.

Ejecutar el comando pack

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: nuget pack.

   NuGet genera un archivo .nupkg con el formato identifier.version.nupkg que encontrará en la carpeta actual.

Publicar el paquete

Cuando cree un archivo .nupkg, publíquelo en nuget.org mediante la CLI de NuGet con una clave de API que haya adquirido de nuget.org. En el caso de nuget.org, debe usar la versión nuget.exe 4.1.0 o posterior.

Si quiere probar y validar el paquete antes de publicarlo en una galería pública, puede cargarlo en un entorno de prueba como int.nugettest.org en lugar de nuget.org. Tenga en cuenta que es posible que no se conserven los paquetes cargados en int.nugettest.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

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.

   

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 NuGet

El uso de la CLI de NuGet (nuget.exe) es una alternativa al uso de la CLI de .NET:

1. Abra un símbolo del sistema y cambie a la carpeta que contiene el archivo .nupkg.

2. Ejecute el siguiente comando. Reemplace <nombre de archivo del paquete> por el nombre de archivo de su paquete y reemplace <valor de la clave de API> por su clave de API. El nombre de archivo del paquete es una concatenación del id. de su paquete y del número de versión con una extensión .nupkg. Por ejemplo, AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   El resultado del proceso de publicación se muestra de la siguiente manera:

   Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
       PUT https://www.nuget.org/api/v2/package/
       Created https://www.nuget.org/api/v2/package/ 6829ms
   Your package was pushed.
   

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

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:

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.

   

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.

   

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.

Pasos siguientes

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

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:

• Publicación de un paquete
• Compilación de un paquete de versión preliminar
• Compatibilidad con varias plataformas de destino
• Control de versiones del paquete
• Creación de un paquete localizado