NuGet

NuGet es un administrador de paquetes para el ecosistema de. NET y es la principal forma que tienen los desarrolladores para detectar y adquirir bibliotecas de código abierto de .NET. NuGet.org, un servicio gratuito proporcionado por Microsoft para hospedar paquetes NuGet, es el host principal para los paquetes NuGet públicos, pero usted puede publicar en los servicios de NuGet personalizados, como MyGet y Azure Artifacts.

Creación de un paquete NuGet

Un paquete NuGet (*.nupkg) es un archivo ZIP que contiene los ensamblados de .NET y los metadatos asociados.

Hay dos formas principales de crear un paquete NuGet. La forma más reciente y recomendada es crear un paquete a partir de un proyecto de estilo SDK (archivo de proyecto cuyo contenido empieza con <Project Sdk="Microsoft.NET.Sdk">). Los ensamblados y objetivos se agregan automáticamente al paquete y los metadatos restantes se agregan al archivo de MSBuild, como el nombre del paquete y el número de versión. La compilación con la el comando dotnet pack genera un archivo *.nupkg en lugar de ensamblados.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

La forma anterior de crear un paquete NuGet es con un archivo *.nuspec y la herramienta de línea de comandos nuget.exe. Un archivo nuspec ofrece un excelente control pero debe especificar meticulosamente qué ensamblados y destinos se van a incluir en el paquete NuGet final. Es fácil cometer un error o que alguien se olvide de actualizar nuspec al realizar cambios. La ventaja de nuspec es que se puede usar para crear paquetes NuGet para marcos que aún no admiten un archivo de proyecto de estilo SDK.

✔️ ES RECOMENDABLE usar un archivo de proyecto de estilo SDK para crear el paquete NuGet.

Dependencias de paquetes

Las dependencias de paquetes NuGet se tratan detalladamente en el artículo Dependences (Dependencias).

Metadatos importantes del paquete NuGet

Un paquete NuGet admite numerosas propiedades de metadatos. La tabla siguiente contiene los metadatos principales que deben proporcionar todos los paquetes de NuGet.org:

✔️ ES RECOMENDABLE elegir un nombre de paquete NuGet con un prefijo que cumpla los criterios de reserva de prefijos de NuGet.

✔️ NO use una href HTTPS para el icono del paquete.

Los sitios como NuGet.org se ejecutan con HTTPS habilitado y la representación de una imagen que no sea HTTPS creará una advertencia de contenido mixto.

✔️ USE una imagen de icono de paquete de 64 x 64 y que tenga un fondo transparente para obtener mejores resultados de visualización.

✔️ ES RECOMENDABLE configurar SourceLink para agregar metadatos de control de código fuente a los ensamblados y los paquetes NuGet.

SourceLink agrega automáticamente metadatos de RepositoryUrl y RepositoryType al paquete NuGet. SourceLink también agrega información sobre el código fuente exacto a partir del cual se creó el paquete. Por ejemplo, en un paquete creado a partir de un repositorio de Git se agregará el hash de confirmación como metadatos.

Paquetes de versión preliminar

Los paquetes NuGet con un sufijo de versión se consideran de versión preliminar. De forma predeterminada, la interfaz de usuario del administrador de paquetes de NuGet muestra versiones estables a menos que un usuario opte por los paquetes de versión preliminar, lo que hace que dichos paquetes resulten ideales para las pruebas limitadas de usuario.

<PackageVersion>1.0.1-beta1</PackageVersion>

✔️ PUBLIQUE un paquete de versión preliminar cuando pruebe, obtenga una vista previa o experimente.

✔️ PUBLIQUE un paquete estable cuando esté listo, de forma que otros paquetes estables puedan hacer referencia a él.

Paquetes de símbolos

El compilador de .NET genera los archivos de símbolos (*.pdb) junto con los ensamblados. Los archivos de símbolos asignan las ubicaciones de ejecución al código fuente original, por lo que puede recorrer dicho código a medida que se ejecuta usando un depurador. NuGet admite la generación de un paquete de símbolos independiente (*.snupkg) que contiene archivos de símbolos junto con el paquete principal que contiene ensamblados .NET. La idea de los paquetes de símbolos es que están hospedados en un servidor de símbolos y solo se descargan mediante una herramienta como Visual Studio a petición.

NuGet.org hospeda su propio repositorio del servidor de símbolos. Los desarrolladores pueden usar los símbolos que se publican en el servidor de símbolos de NuGet.org agregando https://symbols.nuget.org/download/symbols a sus orígenes de símbolos en Visual Studio.

Una alternativa a la creación de un paquete de símbolos es insertar los archivos de símbolos en el paquete NuGet principal. El paquete NuGet principal será mayor, pero los archivos de símbolo insertados implican que los desarrolladores no tendrán que configurar el servidor de símbolos de NuGet.org. Si va a crear el paquete NuGet mediante un proyecto de estilo SDK, puede insertar archivos de símbolos estableciendo la propiedad AllowedOutputExtensionsInPackageBuildOutputFolder:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

La desventaja de los archivos de símbolos insertados es que aumentan el tamaño del paquete en aproximadamente un 30 % para las bibliotecas de .NET compiladas mediante proyectos de estilo SDK. Si el tamaño del paquete es un problema, debe publicar símbolos en un paquete de símbolos.

✔️ ES RECOMENDABLE publicar los símbolos como un paquete de símbolos (*.snupkg) en NuGet.org.

Los paquetes de símbolos (*.snupkg) ofrecen a los desarrolladores una buena experiencia de depuración a petición sin incrementar el tamaño del paquete principal ni afectar al rendimiento de restauración para los que no tengan pensado depurar el paquete NuGet.

La salvedad es que es posible que los usuarios tengan que localizar y configurar el servidor de símbolos de NuGet en su IDE (como una instalación única) para obtener los archivos de símbolos. Visual Studio 2019 versión 16.1 ha agregado el servidor de símbolos NuGet.org a la lista de predeterminados.