Crear paquetes de símbolos (.snupkg)

  • Artículo

Una buena experiencia de depuración se basa en la presencia de símbolos de depuración, ya que proporcionan información crítica, como la asociación entre el código de origen y el compilado, los nombres de variables locales, los seguimientos de la pila, etc. Puede usar paquetes de símbolos (.snupkg) para distribuir estos símbolos y mejorar la experiencia de depuración de los paquetes NuGet.

Tenga en cuenta que el paquete de símbolos no es la única estrategia para poner los símbolos de depuración a disposición de los consumidores de la biblioteca. También es posible embed en dll o exe con la siguiente propiedad de proyecto: <DebugType>embedded</DebugType>

Requisitos previos

nuget.exe 4.9.0 o una versión superior o la CLI de dotnet 2.2.0 o una versión superior, que implementan los protocolos de NuGet requeridos.

Crear un paquete de símbolos

Si usa la CLI de dotnet o MSBuild, debe establecer las propiedades IncludeSymbols y SymbolPackageFormat para crear un archivo .snupkg además del archivo .nupkg.

  • Puede agregar las siguientes propiedades al archivo .csproj:

    <PropertyGroup>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

  • O bien especificar estas propiedades en la línea de comandos:

    dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg

    o

    msbuild MyPackage.csproj /t:pack /p:IncludeSymbols=true /p:SymbolPackageFormat=snupkg

Si usa NuGet.exe, puede emplear los siguientes comandos para crear un archivo .snupkg, además del archivo .nupkg:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

La propiedad SymbolPackageFormat puede tener uno de estos dos valores: symbols.nupkg (predeterminado) o snupkg. Si no se especifica la propiedad, se creará un paquete de símbolos heredado.

Nota:

El formato heredado .symbols.nupkg todavía se admite, pero solo por motivos de compatibilidad como los paquetes nativos (vea Paquetes de símbolos heredados). El servidor de símbolos de NuGet.org solo acepta el nuevo formato de paquete de símbolos, .snupkg.

Publicar un paquete de símbolos

Nota:

Azure Devops Artifacts actualmente no admite la depuración a través de archivos .snupkg.

  1. Para su comodidad, guarde primero la clave de API con NuGet (vea publicar un paquete).

    nuget SetApiKey Your-API-Key

  2. Después de publicar el paquete principal en nuget.org, inserte el paquete de símbolos tal y como se describe a continuación.

    nuget push MyPackage.snupkg

  3. También puede insertar ambos paquetes al mismo tiempo con el comando siguiente. Tanto los archivos .nupkg como .snupkg deben estar presentes en la carpeta actual.

    nuget push MyPackage.nupkg

NuGet publicará ambos paquetes en nuget.org. MyPackage.nupkg se publica en primer lugar, y luego MyPackage.snupkg.

Nota:

Si no se publica el paquete de símbolos, compruebe que ha configurado el origen de NuGet.org como https://api.nuget.org/v3/index.json. La publicación de paquetes de símbolos solo es compatible con la API de NuGet V3.

Servidor de símbolos de NuGet.org

NuGet.org admite su propio repositorio de servidor de símbolos y solo acepta el nuevo formato de paquete de símbolos, .snupkg. Los consumidores de paquetes 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 en Visual Studio, que permite entrar en el código del paquete en el depurador de Visual Studio. Vea Especificar archivos de código fuente y símbolos (.pdb) en el depurador de Visual Studio para obtener información detallada sobre ese proceso.

Restricciones de paquete de símbolos de NuGet.org

NuGet.org tiene estas restricciones para los paquetes de símbolos:

  • Solo se permiten las siguientes extensiones de archivo en los paquetes de símbolos: .pdb, .nuspec, .xml, .psmdcp, .rels, .p7s
  • En estos momentos, solo se admiten archivos PDB portátiles en el servidor de símbolos de NuGet.org.
  • Los archivos PDB y las DLL de .nupkg asociadas deben compilarse con el compilador de la versión 15.9 de Visual Studio o una superior (vea hash criptográfico de PDB).

Los paquetes de símbolos publicados en NuGet.org producirán un error de validación si no se cumplen estas restricciones.

Nota:

Los proyectos nativos, como los de C++, generan archivos PDB de Windows en lugar de archivos PDB portátiles. Estos no son compatibles con el servidor de símbolos de NuGet.org. En su lugar, use paquetes de símbolos heredados.

Validación e indexación de paquetes de símbolos

Los paquetes de símbolos publicados en NuGet.org se someten a varias validaciones, como análisis de malware. Si un paquete no supera la comprobación de validación, la página de detalles del paquete mostrará un mensaje de error. Además, los propietarios del paquete recibirán un correo electrónico con instrucciones sobre cómo corregir los problemas identificados.

Cuando el paquete de símbolos haya superado todas las validaciones, los símbolos se indexarán mediante los servidores de símbolos de NuGet.org y estarán listos para su consumo.

La validación y la indexación del paquete suelen tardar menos de 15 minutos. Si la publicación del paquete tarda más de lo esperado, visite status.nuget.org para comprobar si NuGet.org está experimentando alguna interrupción. Si todos los sistemas están operativos y el paquete no se ha publicado correctamente en una hora, inicie sesión en nuget.org y póngase en contacto con nosotros mediante el vínculo de contacto con el equipo de soporte técnico de la página de detalles del paquete.

Estructura del paquete de símbolos

El paquete de símbolos (.snupkg) tiene las siguientes características:

  1. El .snupkg tiene el mismo identificador y la misma versión que el paquete NuGet correspondiente (.nupkg).

  2. El archivo .snupkg tiene la misma estructura de carpetas que el archivo .nupkg correspondiente para cualquier archivo DLL o EXE con la diferencia de que, en vez de los archivos DLL o EXE, los archivos PDB correspondientes deben estar incluidos en la misma jerarquía de carpetas. El archivo .snupkg no debe incluir ningún archivos o carpetas con extensiones que no sean PDB.

  3. El archivo .nuspec del paquete de símbolos tiene el tipo de paquete SymbolsPackage:

    <packageTypes>
   <packageType name="SymbolsPackage"/>
</packageTypes>

  4. Si un autor decide usar un archivo .nuspec personalizado para compilar sus archivos .nupkg y .snupkg, estos deben tener la misma jerarquía de carpetas y archivos mostrados en el punto 2.

  5. Los siguientes campos se excluirán del archivo .nuspec del archivo .snupkg: authors, owners, requireLicenseAcceptance, license type, licenseUrl y icon.

  6. No utilice el elemento <license>. Se trata un .snupkg con la misma licencia que el .nupkg correspondiente.

Consulte también

Considere la posibilidad de usar el vínculo de origen para habilitar la depuración de código fuente de ensamblados .NET. Para obtener más información, vea la guía de vínculos de origen.

Para obtener más información sobre los paquetes de símbolos, vea la especificación de diseño de Mejoras de símbolos y depuración de paquetes NuGet.