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

Con Microsoft Visual Studio, puede crear un paquete NuGet desde una biblioteca de clases de .NET Framework y, a continuación, publicarlo en nuget.org mediante la herramienta de la CLI de NuGet.

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

Prerequisites

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

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

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

• Regístrese para obtener una cuenta gratuita en nuget.org si aún no tiene una. Debe registrar y confirmar la cuenta para poder cargar un paquete NuGet.

• Para instalar la CLI de NuGet, descárguelo desde nuget.org. Agregue el archivo nuget.exe a una carpeta adecuada y agregue esa carpeta a la variable de entorno PATH.

Creación de un proyecto de biblioteca de clases

Para crear un proyecto de biblioteca de clases, siga estos pasos:

1. En Visual Studio, seleccione File>New>Project.

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

3. En la lista resultante de plantillas de proyecto, seleccione Class Library (.NET Framework) y, a continuación, seleccione Next.

4. En la ventana Configurar el nuevo proyecto, escriba AppLogger como nombre del proyecto y seleccione Crear.

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

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 plantilla es suficiente para crear un paquete. Sin embargo, si desea algún código funcional para este paquete de ejemplo, incluya el código siguiente:

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

   Dentro de un paquete NuGet real, es probable que implemente muchas características útiles con las que otros pueden compilar aplicaciones. También puede establecer las plataformas de destino. Para obtener un ejemplo, consulta UWP.

Configurar las propiedades del proyecto para el paquete

Un paquete NuGet incluye un manifiesto (un .nuspec archivo), 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 extraer 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 Project > Properties y, a continuación, seleccione la pestaña Application.

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

   Importante

   Debe proporcionar al paquete un identificador que sea único en nuget.org o cualquier host que esté usando. De lo contrario, se produce un error. Para este inicio rápido se recomienda incluir Sample o Test en el nombre porque el paso de publicación hace que el paquete sea visible públicamente.

3. Seleccione Información de ensamblado, que muestra un cuadro de diálogo en el que puede escribir otras propiedades que llevan al manifiesto (vea Tokens de reemplazo). Los campos más usados son Title, Description, Company, Copyright y Assembly version. Dado que estas propiedades aparecen con el paquete en un host como nuget.org después de publicarlo, asegúrese de que son totalmente descriptivos.

   

4. (Opcional) Para ver y editar las propiedades directamente, abra el archivo Properties/AssemblyInfo.cs en el proyecto seleccionando Project>Editar Archivo de Proyecto.

5. Después de establecer estas propiedades, establezca la configuración de la solución Active en Build>Configuration Manager en Release y recompile 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 pertinentes para extraer información del archivo del proyecto.

Ejecute nuget spec solo una vez para generar el manifiesto inicial. Si actualiza el paquete, cambie los valores del proyecto o edite el manifiesto directamente:

1. Con tu proyecto abierto en Solution Explorer, abre una ventana de comandos 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 incluye 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>
   

Edición del manifiesto

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

   • licenseUrl
   • projectUrl
   • releaseNotes
   • etiquetas

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

3. También puede agregar cualquier otro elemento al manifiesto en este momento, como se describe en la referencia del archivo .nuspec.

4. Guarde el archivo antes de continuar.

Ejecutar el comando pack

1. Con tu proyecto abierto en Solution Explorer, abre una ventana de comandos 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 en forma de identifier.version.nupkg en la carpeta actual.

Publicación del paquete

Después de crear un archivo .nupkg , publíquelo en nuget.org mediante la CLI de NuGet con una clave de API adquirida desde nuget.org. Para nuget.org, debe usar nuget.exe 4.1.0 o superior.

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.

Adquisición de 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. En la esquina superior derecha, seleccione el nombre de usuario y, a continuación, seleccione Claves de API.

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

4. En Seleccionar ámbitos, seleccione Push.

5. Bajo Seleccionar paquetes, para Patrón Glob, escriba un asterisco (*).

6. Selecciona Crear.

7. Seleccione Copiar para copiar la nueva clave.

   

La delimitación proporciona una manera de crear claves de API independientes con distintos fines. Cada clave tiene un período de caducidad y puedes limitar el uso de la clave a paquetes específicos o a patrones glob. También puede limitar cada clave a operaciones específicas: insertar nuevos paquetes y versiones de paquete, insertar solo nuevas versiones de paquete o anular la lista.

A través del ámbito, puede crear claves de API para diferentes personas que administran paquetes para su organización para que solo tengan los permisos que necesitan.

Para obtener 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 al directorio de la carpeta que contiene el archivo .nupkg.

2. Ejecute el siguiente comando: Reemplace <el nombre de archivo> del paquete por el nombre de archivo del paquete y reemplace <el valor> de la clave de API por la clave de API. El nombre de archivo del paquete es una concatenación del identificador de paquete y el 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 el comando nuget push.

Errores de publicación

Al ejecutar el push comando, a veces se produce un error. Por ejemplo, es posible que reciba un error en las situaciones siguientes:

• La clave de API no es válida o ha expirado.
• Intenta publicar un paquete que tenga un identificador que ya existe en el host.
• Realiza cambios en un paquete publicado, pero se olvida de actualizar el número de versión antes de intentar publicarlo de nuevo.

El mensaje de error suele indicar el origen del problema.

Por ejemplo, supongamos que el identificador Contoso.App.Logger.Test existe en nuget.org. Si intenta publicar un paquete con ese identificador, obtendrá 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.).

Para solucionar esta situación, compruebe el ámbito, la fecha de expiración y el valor de la clave de API. Si la clave es válida, el error indica que el identificador del paquete ya existe en el host. Para solucionar el problema, cambie el identificador del paquete para que sea único, recompile el proyecto, vuelva a crear el archivo .nupkg y vuelva a intentar el push comando.

Administrar el paquete publicado

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

Ahora que el paquete NuGet se publica en nuget.org, otros desarrolladores pueden usarlo en sus proyectos.

Si crea un paquete que no es útil (por ejemplo, este paquete de ejemplo desde una biblioteca de clases vacía) o si no desea que el paquete sea visible, puede anular la lista del 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 de lápiz situado junto a la lista de paquetes.

   

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

   

El paquete aparece ahora en Paquetes no registrados en Administrar paquetes y ya no aparece en los resultados de búsqueda.

Pasos siguientes

Enhorabuena por crear 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.

Para explorar más 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 de paquetes
• Creación de un paquete localizado