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

Es muy sencillo crear un paquete NuGet desde una biblioteca de clases de .NET Standard con Visual Studio en Windows y después publicarlo en nuget.org con una herramienta CLI.

Requisitos previos

1. Instale cualquier edición de Visual Studio 2019 desde visualstudio.com con una carga de trabajo relacionada con .NET.

2. Si aún no lo está, instale la CLI dotnet.

   A partir de Visual Studio 2017, la CLI de dotnet 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 . La CLI de dotnet es necesaria para los proyectos .NET Standard que usan el dotnet (atributo SDK). La plantilla de biblioteca de clases de .NET Standard predeterminada en Visual Studio 2017 y versiones superiores, que se usa en este artículo, utiliza el atributo SDK.

   Importante

   Si está trabajando con un proyecto de este tipo, 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 su lugar. En este artículo, se recomienda la CLI de dotnet. Aunque puede publicar cualquier paquete NuGet mediante la CLI de nuget.exe, algunos de los pasos de este artículo son específicos de los proyectos de estilo SDK y de la CLI de dotnet. La CLI de nuget.exe se usa con proyectos que no son de estilo SDK (normalmente .NET Framework).

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 Standard existente para el código que quiere empaquetar o crear uno simple tal y como se indica aquí:

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

   Sugerencia

   A menos que tenga una razón para elegir otro, .NET Standard es el destino preferido para los paquetes NuGet, ya que proporciona compatibilidad con la gama más amplia de proyectos de consumo.

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

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

Configuración de las propiedades del paquete

1. Haga clic con el botón derecho en el proyecto en el Explorador de soluciones, elija el comando de menú Propiedades y, luego, seleccione la pestaña Paquete.

   La pestaña Paquete solo aparece con los proyectos de estilo SDK de Visual Studio, normalmente proyectos de la biblioteca de clases .NET Standard o .Net Core; si el proyecto de destino no es de estilo SDK (normalmente, .NET Framework), migre el proyecto o consulte Creación y publicación de un paquete de NET Framework para instrucciones paso a paso.

   

   Nota

   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 comprender lo que hace.

2. Asigne al paquete un identificador único y rellene las demás propiedades que quiera. Para una asignación de las propiedades de MSBuild (proyecto de estilo de SDK) a las propiedades de un archivo .nuspec, consulte los destinos de paquete. Para descripciones de las propiedades, consulte la referencia del archivo .nuspec. Todas las propiedades que aparecen aquí pasan al .nuspec manifiesto 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. 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. (Opcional) Para ver las propiedades directamente en el archivo del proyecto, haga clic con el botón derecho en el proyecto en el Explorador de soluciones y seleccione Editar AppLogger.csproj.

   Esta opción solo está disponible a partir de Visual Studio 2017 para los proyectos que usan el atributo del estilo de SDK. En caso contrario, haga clic con el botón derecho en el proyecto y elija Descargar proyecto. Después, haga clic con el botón derecho en el proyecto descargado y elija Editar AppLogger.csproj.

Ejecutar el comando pack

1. Establezca la configuración en Versión.

2. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione el comando Empaquetar:

   

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

3. Visual Studio compila el proyecto y crea el archivo .nupkg. Examine la ventana Resultados para obtener más información (similar a la siguiente), que contiene la ruta de acceso al archivo de paquete. Tenga en cuenta también que el ensamblado compilado se encuentra en bin\Release\netstandard2.0, ya que se adapta al destino de .NET Standard 2.0.

   1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
   1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\netstandard2.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 ==========
   

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

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

1. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y, luego, elija Propiedades.

2. En la pestaña Paquete, seleccione Generar paquete de NuGet al compilar.

   

(Opcional) Empaquetado con MSBuild

Como alternativa al uso del comando de menú Pack, NuGet 4.x+ y MSBuild 15.1+ admiten un destino cuando el proyecto contiene los datos de paquete necesarios. Abra un símbolo del sistema, navegue a la carpeta del proyecto y ejecute este comando. (Normalmente es preferible iniciar el "Símbolo del sistema para desarrolladores de Visual Studio" en el menú Inicio, ya que se configurará con todas las rutas de acceso necesarias para MSBuild).

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

Publicar el paquete

Cuando tenga un archivo .nupkg, publíquelo en nuget.org con la CLI de nuget.exe o la CLI de dotnet.exe y una clave de API adquirida de nuget.org.

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

Publicación con la CLI de dotnet o la CLI de nuget.exe

Seleccione la pestaña de la herramienta de la CLI, CLI de .NET Core (CLI de dotnet) o NuGet (CLI de nuget.exe).

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:

   

Adició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 use la propiedad content:

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

De este modo, se incluirá un archivo denominado readme.txt en la raíz del paquete. Visual Studio muestra el contenido de ese archivo como texto sin formato inmediatamente después de instalar el paquete directamente. (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:

Vídeo relacionado

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

Temas relacionados

• Crear un paquete
• 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
• Documentación de la biblioteca de .NET Standard
• Portabilidad a .NET Core desde .NET Framework