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

Crear un paquete NuGet desde una biblioteca de clases de .NET Framework implica crear el archivo DLL con Visual Studio en Windows y, después, usar la herramienta de línea de comandos nuget.exe para crear y publicar el paquete.

Requisitos previos

1. Instale cualquier edición de Visual Studio 2017 o versiones superiores desde visualstudio.com con cualquier carga de trabajo relacionada con .NET. Visual Studio de 2017 incluye automáticamente funcionalidades de NuGet cuando se instala una carga de trabajo. NET.

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

3. Registrar una cuenta gratuita en nuget.org si aún no tiene uno. Al crear una cuenta se envía un correo electrónico de confirmación. Debe confirmar la cuenta para poder cargar un paquete.

Crear un proyecto de biblioteca de clases

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

1. En Visual Studio, elija Archivo nuevo > Project, seleccione el nodo > seleccione la plantilla "Biblioteca de clases (.NET Framework)", asigne al proyecto el nombre AppLogger y haga clic en Aceptar.

2. Haga clic con el botón derecho en el archivo de proyecto resultante y seleccione Compilar para asegurarse de que el proyecto se ha creado correctamente. El archivo DLL se encuentra en la carpeta Debug (o Release si en su lugar compila esa configuración).

Por supuesto, dentro de un paquete NuGet real, se implementan muchas características útiles con las que otros usuarios pueden compilar aplicaciones. También puede establecer los marcos de destino como quiera. Por ejemplo, vea las guías de UWP y Xamarin.

Pero en este tutorial no escribirá código adicional porque para crear un paquete es suficiente con una biblioteca de clases desde la plantilla. No obstante, si desea algún código funcional para el paquete, use lo siguiente:

using System;

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

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. Algunas de ellas se pueden dibujar desde las propiedades del proyecto directamente, lo que evita tener que actualizarlas por separado en el proyecto y el manifiesto. En esta sección se describe dónde establecer las propiedades aplicables.

1. Seleccione el Project menú Propiedades y, a continuación, seleccione la pestaña Aplicación.

2. En el campo Nombre del ensamblado asigne un identificador único al paquete.

   Importante

   Debe asignar al paquete un identificador que sea único en nuget.org o en el host que use. En este tutorial, se recomienda incluir "muestra" o "prueba" en el nombre porque el paso de publicación posterior hace que el paquete sea visible públicamente (aunque no es probable que nadie lo use realmente).

   Si intenta publicar un paquete con un nombre que ya existe, verá un error.

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 (vea la sección Tokens de reemplazo en Referencia de .nuspec). Los campos más usados son Título, Descripción, Empresa, Copyright y Versión de ensamblado. Estas propiedades aparecen en última instancia con el paquete en un host como nuget.org, así que 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.

5. Cuando se hayan establecido las propiedades, establezca la configuración de proyecto en Versión y recompile el proyecto para generar la DLL actualizada.

Generación del manifiesto inicial

Una vez que tiene un archivo DLL y un conjunto de propiedades del proyecto, ya puede usar el comando nuget spec para 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. Al actualizar el paquete, puede cambiar los valores en el proyecto o editar el manifiesto directamente.

1. Abra un símbolo del sistema y desplácese hasta la carpeta del proyecto que contiene el archivo AppLogger.csproj.

2. Ejecute el siguiente comando: nuget spec AppLogger.csproj. Mediante la especificación de un proyecto, 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 debería aparecer como se muestra aquí:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>YourUsername</authors>
       <owners>YourUsername</owners>
       <license type="expression">MIT</license>
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2019</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Edición del manifiesto

1. NuGet genera un error si intenta crear un paquete con valores predeterminados en el archivo .nuspec, por lo que debe editar los campos que aquí se indican antes de continuar. Para una descripción de cómo se usan, vea el apartado Referencia de .nuspec - Elementos de metadatos opcionales.

   • licenseUrl
   • projectUrl
   • iconUrl
   • releaseNotes
   • etiquetas

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

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

4. Guarde el archivo antes de continuar.

Ejecutar el comando pack

1. Desde un símbolo del sistema en la carpeta que contiene el archivo .nuspec, ejecute el comando nuget pack.

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

Publicar el paquete

Una vez que tenga un archivo, puede publicarlo en nuget.org con una .nupkg clave de API adquirida de nuget.exe nuget.org. Por nuget.org debe usar nuget.exe 4.1.0 o posterior.

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.

   Para más información sobre cómo crear la cuenta, consulte Cuentas individuales.

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

3. Seleccione Crear,proporcione un nombre para la clave y seleccione Seleccionar ámbitos Push. Escriba * en patrón global y, luego, seleccione Crear. (Vea a continuación más información sobre ámbitos).

4. Cuando haya creado la clave, seleccione Copiar para recuperar la clave de acceso que va a necesitar en la CLI:

   

El ámbito permite crear claves de API independientes con distintos fines. Cada clave tiene su plazo de expiración y su ámbito puede establecerse en paquetes específicos (o patrones globales). El ámbito de cada clave también se puede establecer en operaciones específicas: insertar nuevos paquetes y actualizaciones, insertar solo actualizaciones o quitar de la lista. A través del ámbito, puede crear claves de API para distintas personas que administran paquetes para su organización, de manera que solo tengan los permisos que necesitan. Para más información, consulte las claves de API con ámbito.

Publicar con nuget push

1. Abra una línea de comandos y cambie a la carpeta que contiene el archivo .nupkg.

2. Ejecute el comando siguiente, especificando el nombre del paquete y reemplazando el valor de clave por la clave de API:

   nuget push AppLogger.1.0.0.nupkg qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -Source https://api.nuget.org/v3/index.json
   

3. nuget.exe muestra los resultados del proceso de publicación:

   Pushing AppLogger.1.0.0.nupkg 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.
   

Vea nuget push.

Errores de publicación

Los errores del comando push suelen indicar el problema. Por ejemplo, quizás 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 al intentar publicar un paquete con un identificador que ya existe en el host. Por ejemplo, el nombre "AppLogger" ya existe. En tal caso, el comando push genera 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 usa una clave de API válida que acaba de crear, este mensaje indica un conflicto de nomenclatura, que no queda completamente claro en la parte "permiso" del error. Cambie el identificador del paquete, recompile el proyecto, vuelva a crear el archivo .nupkg e intente ejecutar de nuevo el comando push.

Administrar el paquete publicado

Desde su perfil en nuget.org, seleccione Administrar paquetes para ver el que acaba de publicar. También recibirá un correo electrónico de confirmación. Tenga en cuenta que es posible que se tarde un tiempo en indexar el paquete y en aparecer en los resultados de la búsqueda donde otros usuarios puedan encontrarlo. Durante ese tiempo, la página del paquete muestra el mensaje siguiente:

Y listo. Acaba de publicar el primer paquete NuGet en nuget.org que otros desarrolladores pueden usar en sus propios proyectos.

Si en este tutorial crea un paquete que no es realmente útil (por ejemplo, un paquete creado con una biblioteca de clase vacía), lo debe quitar de la lista para ocultarlo en resultados de búsqueda:

1. En nuget.org, seleccione su nombre de usuario (esquina superior derecha de la página) y luego Administrar paquetes.

2. Busque el paquete que quiere quitar la de lista Publicado y seleccione el icono de la papelera de la derecha:

   

3. En la página subsiguiente, desactive la casilla List (package-name) in search results (Mostrar [nombre_del_paquete] en la lista de resultados de la búsqueda) y seleccione Guardar:

   

Pasos siguientes

¡Enhorabuena por crear su primer paquete NuGet!

Para explorar más de lo que NuGet ofrece, seleccione los siguientes vínculos.

• Publicación de un paquete
• Paquetes de versión preliminar
• Admitir varias plataformas de destino
• Control de versiones del paquete
• Creación de paquetes localizados