Création de packages de symboles (.snupkg)Creating symbol packages (.snupkg)

Les packages de symboles vous permettent d’améliorer le débogage de vos packages NuGet.Symbol packages allow you to improve the debugging experience of your NuGet packages.

PrérequisPrerequisites

nuget.exe v4.9.0 ou version ultérieure, ou dotnet.exe v2.2.0 ou version ultérieure, qui implémente les protocoles NuGet nécessaires.nuget.exe v4.9.0 or above or dotnet.exe v2.2.0 or above, which implement the required NuGet protocols.

Création d’un package de symbolesCreating a symbol package

Vous pouvez créer un package de symboles snupkg à l’aide de dotnet.exe, NuGet.exe ou MSBuild.You can create a snupkg symbol package using dotnet.exe, NuGet.exe, or MSBuild. Si vous choisissez NuGet.exe, vous pouvez utiliser les commandes suivantes pour créer un fichier .snupkg, en plus du fichier .nupkg :If you're using NuGet.exe, you can use the following commands to create a .snupkg file in addition to the .nupkg file:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

Si vous choisissez dotnet.exe ou MSBuild, effectuez les étapes suivantes pour créer un fichier .snupkg, en plus du fichier .nupkg :If you're using dotnet.exe or MSBuild, use the following steps to create a .snupkg file in addition to the .nupkg file:

  1. Ajoutez les propriétés suivantes à votre fichier .csproj :Add the following properties to your .csproj file:

    <PropertyGroup>
      <IncludeSymbols>true</IncludeSymbols>
      <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    </PropertyGroup>
    
  2. Compressez votre projet avec dotnet pack MyPackage.csproj ou msbuild -t:pack MyPackage.csproj.Pack your project with dotnet pack MyPackage.csproj or msbuild -t:pack MyPackage.csproj.

La propriété SymbolPackageFormat peut avoir l’une des deux valeurs suivantes : symbols.nupkg (valeur par défaut) ou snupkg.The SymbolPackageFormat property can have one of two values: symbols.nupkg (the default) or snupkg. Si la propriété SymbolPackageFormat n’est pas spécifiée, un package de symboles hérité est créé.If the SymbolPackageFormat property is not specified, a legacy symbol package will be created.

Notes

Le format hérité .symbols.nupkg est toujours pris en charge, mais uniquement pour des raisons de compatibilité (consultez Packages de symboles hérités).The legacy format .symbols.nupkg is still supported but only for compatibility reasons (see Legacy Symbol Packages). Le serveur de symboles NuGet.org accepte uniquement le nouveau format de package de symboles - .snupkg.NuGet.org's symbol server only accepts the new symbol package format - .snupkg.

Publication d’un package de symbolesPublishing a symbol package

  1. Pour des raisons pratiques, commencez par enregistrer votre clé API auprès de NuGet (consultez Publier un package).For convenience, first save your API key with NuGet (see publish a 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.After publishing your primary package to nuget.org, push the symbol package as follows.

    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.You can also push both primary and symbol packages at the same time using the below command. Les fichiers .nupkg et .snupkg doivent être présents dans le dossier actuel.Both .nupkg and .snupkg files need to be present in the current folder.

    nuget push MyPackage.nupkg
    

NuGet publie les deux packages sur nuget.org. MyPackage.nupkg sera publié en premier, suivi de MyPackage.snupkg.NuGet will publish both packages to nuget.org. MyPackage.nupkg will be published first, followed by 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.If the symbol package isn't published, check that you've configured the NuGet.org source as https://api.nuget.org/v3/index.json. La publication du package de symboles est uniquement prise en charge par l’API NuGet V3.Symbol package publishing is only supported by the NuGet V3 API.

Serveur de symboles NuGet.orgNuGet.org symbol server

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.NuGet.org supports its own symbols server repository and only accepts the new symbol package format - .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.Package consumers can use the symbols published to nuget.org symbol server by adding https://symbols.nuget.org/download/symbols to their symbol sources in Visual Studio, which allows stepping into package code in the Visual Studio debugger. 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.See Specify symbol (.pdb) and source files in the Visual Studio debugger for details on that process.

Contraintes liées au package de symboles Nuget.orgNuget.org symbol package constraints

Les packages de symboles pris en charge sur nuget.org ont les contraintes suivantesThe symbol packages supported on nuget.org have the following contraints

  • Seules les extensions de fichier suivantes peuvent être ajoutées à un package de symboles.Only the following file extensions are allowed to be added to a symbol package. .pdb,.nuspec,.xml,.psmdcp,.rels,.p7s
  • Seuls les fichiers pdb portables managés sont pris en charge sur le serveur de symboles nuget.Only managed Portable pdbs are currently supported on nuget symbol server.
  • Les fichiers pdb et les fichiers dll associés de nupkg 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)The pdbs and associated nupkg dlls need to be built with the compiler in Visual Studio version 15.9 or above (see pdb crypto hash)

La publication du package de symboles sur nuget.org ne peut pas s’effectuer correctement si d’autres types de fichier sont inclus dans le fichier .snupkg.The symbol package publish on nuget.org will fail if any other file types are included in the .snupkg.

Validation et indexation du package de symbolesSymbol package validation and indexing

Les packages de symboles publiés sur NuGet.org sont soumis à plusieurs validations, par exemple des contrôles antivirus.Symbol packages published to NuGet.org undergo several validations, such as virus checks.

Une fois que tous les contrôles de validation du package ont réussi, il est parfois nécessaire d’attendre un certain temps avant que les symboles ne soient indexés et disponibles pour être consommés à partir des serveurs de symboles NuGet.org.When the package has passed all validation checks, it might take a while for the symbols to index and be available for consumption from the NuGet.org symbol servers. En cas d’échec d’un contrôle de validation du package, la page des détails de package du fichier .nupkg se met à jour pour afficher l’erreur associée. De plus, vous recevez un e-mail de notification.If the package fails a validation check, the package details page for the .nupkg will update to display the associated error and you will also receive an email notifying you about it.

La validation et l’indexation du package prend généralement moins de 15 minutes.Package validation and indexing usually takes under 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.If the package publishing is taking longer than expected, visit status.nuget.org to check if nuget.org is experiencing any 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.If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package details page.

Structure des packages de symbolesSymbol package structure

Le fichier .nupkg est exactement le même qu’aujourd’hui. Toutefois, le fichier .snupkg présente les caractéristiques suivantes :The .nupkg file would be exactly the same as it is today, but the .snupkg file would have the following characteristics:

  1. Le fichier .snupkg a le même ID et la même version que le fichier .nupkg correspondant.The .snupkg will have the same id and version as the corresponding .nupkg.
  2. Le fichier .snupkg comporte la même structure de dossiers que le fichier .nupkg 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 hiérarchie de dossiers.The .snupkg will have the exact folder structure as the nupkg for any DLL or EXE files with the distinction that instead of DLLs/EXEs, their corresponding PDBs will be included in the same folder hierarchy. Les fichiers et dossiers ayant d’autres extensions que PDB ne sont pas inclus dans le fichier .snupkg.Files and folders with extensions other than PDB will be left out of the snupkg.
  3. Le fichier .nuspec dans le fichier .snupkg spécifie également un nouveau PackageType, comme indiqué ci-dessous.The .nuspec file in the .snupkg will also specify a new PackageType as below. Il doit s’agir du seul PackageType spécifié.This should the only one PackageType specified.
<packageTypes>
  <packageType name="SymbolsPackage"/>
</packageTypes>
  1. 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).If an author decides to use a custom nuspec to build their nupkg and snupkg, the snupkg should have the same folder hierarchy and files detailed in 2).
  2. Les champs authors et owners sont exclus du nuspec de snupkg.authors and owners field will be excluded from the snupkg's nuspec.

Voir aussiSee Also

Améliorations apportées au débogage et aux symboles de packages NuGetNuGet-Package-Debugging-&-Symbols-Improvements