NuGet

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

Creación de un paquete NuGet

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

Hay dos maneras 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 comienza con <Project Sdk="Microsoft.NET.Sdk">). Los ensamblados y destinos 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 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 te brinda un gran control, pero debes especificar cuidadosamente qué ensamblados y destinos incluir en el paquete NuGet final. Es fácil cometer un error o para que alguien olvide actualizar el nuspec al realizar cambios. La ventaja de nuspec es que puede usarla para crear paquetes NuGet para marcos que aún no admiten un archivo de proyecto de estilo SDK.

✔️ CONSIDERE la posibilidad de usar un archivo de proyecto de estilo SDK para crear el paquete NuGet.

Dependencias de paquetes

Las dependencias del paquete NuGet se tratan en detalle en el artículo Dependencias.

Metadatos importantes del paquete NuGet

Un paquete NuGet admite numerosas propiedades de metadatos. En la tabla siguiente se incluyen los metadatos principales que deben proporcionar todos los paquetes de NuGet.org:

✔️ CONSIDERE la posibilidad de elegir un nombre de paquete NuGet con un prefijo que cumpla los criterios de reserva de prefijo de NuGet .

✔️ DEBES usar un href HTTPS para el icono de tu paquete.

Sitios como NuGet.org ejecutan con HTTPS habilitado y mostrar una imagen no segura creará una advertencia de contenido mixto.

✔️ Use una imagen de icono de paquete que sea de 64 x 64 y tenga un fondo transparente para obtener los 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.

Source Link agrega automáticamente RepositoryUrl y RepositoryType metadatos al paquete NuGet. Source Link también agrega información sobre el código fuente exacto desde el que se creó el paquete. Por ejemplo, un paquete creado a partir de un repositorio de Git tendrá agregado 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 NuGet muestra versiones estables a menos que un usuario opte por publicar paquetes preliminares, lo que hace que los paquetes de versión preliminar sean ideales para pruebas de usuario limitadas.

<PackageVersion>1.0.1-beta1</PackageVersion>

✔️ Publique un paquete de versión preliminar al probar, obtener una vista previa o experimentar.

✔️ Publique un paquete estable cuando esté listo para que otros paquetes estables puedan hacer referencia a él.

Paquetes de símbolos

Los archivos de símbolos (*.pdb) se generan mediante el compilador de .NET junto con ensamblados. Los archivos de símbolos asignan ubicaciones de ejecución al código fuente original para que pueda recorrer el código fuente a medida que se ejecuta mediante 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 se hospedan en un servidor de símbolos y solo las descarga 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 publicados en el servidor de símbolos de NuGet.org agregando https://symbols.nuget.org/download/symbols a sus orígenes de símbolos de en Visual Studio.

Una alternativa a la creación de un paquete de símbolos es insertar archivos de símbolos en el paquete NuGet principal. El paquete NuGet principal será mayor, pero los archivos de símbolos incrustados significan que los desarrolladores no necesitan configurar el servidor de símbolos de NuGet.org. Si va a compilar 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 insertar archivos de símbolos es que aumentan el tamaño del paquete en aproximadamente 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.

✔️ CONSIDERE la posibilidad de publicar símbolos como un paquete de símbolos (*.snupkg) para NuGet.org

Los paquetes de símbolos (*.snupkg) proporcionan a los desarrolladores una buena experiencia de depuración a petición sin sobredimensionar el tamaño principal del paquete y afectar al rendimiento de la restauración para aquellos que no piensan depurar el paquete NuGet.

La advertencia es que es posible que los usuarios necesiten buscar y configurar el servidor de símbolos de NuGet en su IDE (como una configuración única) para obtener archivos de símbolos. La versión 16.1 de Visual Studio 2019 agregó el servidor de símbolos de NuGet.org a la lista de servidores de símbolos predeterminados.