Partager via

Création de packages de symboles (.snupkg)

  • Article

Une bonne expérience de débogage repose sur la présence de symboles de débogage, car ils fournissent des informations critiques telles que l’association entre le code compilé et le code source, les noms des variables locales, les rapport d’appel de procédures, et plus encore. Vous pouvez utiliser des packages de symboles (.snupkg) pour distribuer ces symboles et améliorer l’expérience de débogage de vos packages NuGet.

Notez que les packages de symboles ne sont pas la seule stratégie pour rendre les symboles de débogage disponibles pour les consommateurs de votre bibliothèque. Il est également possible de les embed dans dll ou exe grâce à la propriété de projet : <DebugType>embedded</DebugType>

Prérequis

nuget.exe v4.9.0 ou version ultérieure, ou CLI dotnet v2.2.0 ou version ultérieure, implémentant les protocoles NuGet nécessaires.

Création d’un package de symboles

Si vous utilisez l’interface CLI dotnet ou MSBuild, vous devez définir les propriétés IncludeSymbols et SymbolPackageFormat pour créer un fichier .snupkg en plus du fichier .nupkg.

  • Ajoutez les propriétés suivantes à votre fichier .csproj :

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

  • Ou spécifiez ces propriétés sur la ligne de commande :

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

    or

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

Si vous choisissez NuGet.exe, vous pouvez utiliser les commandes suivantes pour créer un fichier .snupkg, en plus du fichier .nupkg :

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

La propriété SymbolPackageFormat peut avoir l’une des deux valeurs suivantes : symbols.nupkg (valeur par défaut) ou snupkg. Si cette propriété n’est pas spécifiée, un package de symboles hérité est créé.

Remarque

Le format hérité .symbols.nupkg est toujours pris en charge, mais uniquement pour des raisons de compatibilité avec package natifs par exemple (consultez Packages de symboles hérités). Le serveur de symboles NuGet.org accepte uniquement le nouveau format de package de symboles - .snupkg.

Publication d’un package de symboles

Remarque

Azure Devops Artifacts ne prend actuellement pas en charge le débogage par le biais de fichiers .snupkg.

  1. Pour des raisons pratiques, commencez par enregistrer votre clé API auprès de NuGet (consultez Publier un package).

    nuget SetApiKey Your-API-Key

  2. Après avoir publié votre package principal sur nuget.org, envoyez (push) le package de symboles comme suit.

    nuget push MyPackage.snupkg

  3. Vous pouvez également envoyer simultanément le package principal et le package de symboles à l’aide de la commande ci-dessous. Les fichiers .nupkg et .snupkg doivent être présents dans le dossier actuel.

    nuget push MyPackage.nupkg

NuGet publie les deux packages sur nuget.org. MyPackage.nupkg sera publié en premier, suivi de MyPackage.snupkg.

Remarque

Si le package de symboles n’est pas publié, vérifiez que vous avez configuré la source NuGet.org comme https://api.nuget.org/v3/index.json. La publication du package de symboles est uniquement prise en charge par l’API NuGet V3.

Serveur de symboles NuGet.org

NuGet.org prend en charge son propre dépôt de serveur de symboles et accepte uniquement le nouveau format de package de symboles - .snupkg. Les consommateurs de package peuvent utiliser les symboles publiés sur le serveur de symboles nuget.org en ajoutant https://symbols.nuget.org/download/symbols à leurs sources de symboles dans Visual Studio, ce qui permet d’effectuer un pas à pas détaillé du code de package dans le débogueur Visual Studio. Pour plus d’informations sur ce processus, consultez Spécifier les fichiers de symboles (.pdb) et les fichiers sources dans le débogueur Visual Studio.

Contraintes liées au package de symboles NuGet.org

NuGet.org impose les contraintes suivantes pour les packages de symboles :

  • Seules les extensions de fichier suivantes sont autorisées dans les packages de symboles : .pdb, .nuspec, .xml, .psmdcp, .rels, .p7s
  • Seuls les fichiers managés PDB portables sont pris en charge sur le serveur de symboles NuGet.org.
  • Les fichiers PDB et les fichiers DDL .nupkg associés doivent être générés avec le compilateur de Visual Studio version 15.9 ou version ultérieure (consultez code de hachage de chiffrement de fichier PDB)

Les packages de symboles publiés dans NuGet.org ne passeront pas la validation si ces contraintes ne sont pas remplies.

Remarque

Les projets natifs, tels que les projets C++, produisent des PDB Windows plutôt que des fichiers PDB portables. Ceux-ci ne sont pas pris en charge par le serveur de symboles NuGet.org. Utilisez plutôt les packages de symboles hérités.

Validation et indexation du package de symboles

Les packages de symboles publiés sur NuGet.org subissent plusieurs validations, y compris une analyse de recherche de programmes malveillants. Si un package échoue à une de ces validations, la page de détails du package affiche un message d’erreur. En outre, les propriétaires du package recevront un email contenant des instructions sur la façon de corriger les problèmes identifiés.

Lorsque le package de symboles a passé toutes les validations, les symboles sont indexés par les serveurs de symboles de NuGet.org et sont disponibles pour la consommation.

La validation et l’indexation du package prend généralement moins de 15 minutes. Si la publication du package prend plus de temps que prévu, visitez status.nuget.org pour vérifier si NuGet.org rencontre des interruptions de service. Si tous les systèmes sont opérationnels et si le package n’est pas correctement publié en moins d’une heure, connectez-vous à nuget.org et contactez-nous via le lien permettant de contacter le support dans la page des détails du package.

Structure des packages de symboles

Le package de symboles (.snupkg) présente les caractéristiques suivantes :

  1. Le fichier .snupkg a le même ID et la même version que le package NuGet correspondant (.nupkg).

  2. Le fichier .snupkg a la même structure de dossiers que le fichier .nupkg correspondant pour tous les fichiers DLL ou EXE, à la différence qu’au lieu de fichiers DLL/EXE, les fichiers PDB correspondants sont inclus dans la même arborescence de dossier. Les fichiers et dossiers ayant d’autres extensions que PDB ne sont pas inclus dans le fichier .snupkg.

  3. Le fichier .nuspec du package de symboles a le type de package SymbolsPackage :

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

  4. Si un auteur décide d’utiliser un nuspec personnalisé pour générer ses nupkg et snupkg, le snupkg doit avoir la même hiérarchie de dossiers et les mêmes fichiers que ceux décrits dans 2).

  5. Les champs suivant sont exclus du fichier .nuspec du .snupkg : authors, owners, requireLicenseAcceptance, license type, licenseUrl et icon.

  6. N'utilisez pas l’élément <license> . Un fichier .snupkg est couvert par la même licence que le fichier .nupkg correspondant.

Voir aussi

Envisagez d’utiliser un lien vers la source pour activer le débogage du code source des assemblys .NET. Pour plus d’informations, consultez l’aide relative au lien vers la source.

Pour plus d’informations sur les packages de symboles, reportez-vous aux spécifications de conception pour l’Amélioration des package de symboles et de débogage NuGet.