Création de packages de symboles (.snupkg)

  • Article
  • 5 minutes de lecture

Une bonne expérience de débogage s’appuie 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 traces de pile, etc. 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 le package de symboles n’est pas la seule stratégie permettant de mettre les symboles de débogage à la disposition des consommateurs de votre bibliothèque. Il est également possible de les utiliser embed dans ou dllexe avec la propriété de projet suivante : <DebugType>embedded</DebugType>

Prérequis

nuget.exe v4.9.0 ou version ultérieure ou dotnet CLI v2.2.0 ou ultérieure, qui implémentent les protocoles NuGet requis.

Création d’un package de symboles

Si vous utilisez l’interface CLI dotnet ou MSBuild, vous devez définir les IncludeSymbols propriétés 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>

  • Vous pouvez également spécifier ces propriétés sur la ligne de commande :

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

    ou

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

Notes

Le format .symbols.nupkg hérité est toujours pris en charge, mais uniquement pour des raisons de compatibilité telles que les packages natifs (voir 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

Notes

Azure Devops Artifacts ne prend actuellement pas en charge le débogage via .snupkg des fichiers.

  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.

Notes

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 de package de symboles NuGet.org

NuGet.org a 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 PDB portables managés sont pris en charge sur le serveur de symboles de NuGet.org.
  • Les fichiers PDB et les DLL .nupkg associées doivent être générés avec le compilateur dans Visual Studio version 15.9 ou ultérieure (voir Hachage de chiffrement PDB)

Les packages de symboles publiés sur NuGet.org échouent si ces contraintes ne sont pas remplies.

Notes

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

Validation et indexation du package de symboles

Les packages de symboles publiés sur NuGet.org font l’objet de plusieurs validations, notamment l’analyse des programmes malveillants. Si un package échoue à une vérification de validation, sa page des détails du package affiche un message d’erreur. En outre, les propriétaires du package recevront un e-mail contenant des instructions sur la façon de résoudre les problèmes identifiés.

Une fois que le package de symboles a réussi toutes les validations, les symboles sont indexés par les serveurs de symboles de NuGet.org et sont disponibles pour consommation.

La validation et l’indexation du package prend généralement moins de 15 minutes. Si la publication des packages prend plus de temps que prévu, consultez status.nuget.org pour vérifier si NuGet.org rencontre des interruptions. 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. .snupkg a l’ID et la même version que son package NuGet correspondant (.nupkg).

  2. Le fichier .snupkg a la même structure de dossiers que son fichier .nupkg correspondant pour tous les fichiers DLL ou EXE, avec la distinction qu’au lieu de DLL/EXE, leurs fichiers PDB correspondants seront inclus dans la même hiérarchie de dossiers. 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 SymbolsPackage package :

    <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 suivants sont exclus de la nuspec de snupkg : authors, , ownersrequireLicenseAcceptance, license type, , licenseUrlet 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 Source Link pour activer le débogage du code source des assemblys .NET. Pour plus d’informations, reportez-vous aux conseils Source Link.

Pour plus d’informations sur les packages de symboles, reportez-vous à la spécification de conception Des améliorations des symboles de débogage & de package NuGet .