Erstellen von Symbolpaketen (.snupkg)Creating symbol packages (.snupkg)

Mithilfe von Symbolpaketen kann das Debuggen von NuGet-Paketen verbessert werden.Symbol packages allow you to improve the debugging experience of your NuGet packages.

Erforderliche KomponentenPrerequisites

nuget.exe v4.9.0 oder höher oder dotnet.exe v2.2.0 oder höher, die die erforderlichen NuGet-Protokolle implementieren.nuget.exe v4.9.0 or above or dotnet.exe v2.2.0 or above, which implement the required NuGet protocols.

Erstellen eines SymbolpaketsCreating a symbol package

Sie können ein snupkg-Symbolpaket mithilfe von „dotnet.exe“, „NuGet.exe“ oder MSBuild erstellen.You can create a snupkg symbol package using dotnet.exe, NuGet.exe, or MSBuild. Wenn Sie „NuGet.exe“ verwenden, können Sie folgende Befehle verwenden, um eine SNUPKG-Datei zusätzlich zur NUPKG-Datei zu erstellen: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

Wenn Sie „dotnet.exe“ oder MSBuild verwenden, können Sie folgende Schritte befolgen, um eine SNUPKG-Datei zusätzlich zur NUPKG-Datei zu erstellen:If you're using dotnet.exe or MSBuild, use the following steps to create a .snupkg file in addition to the .nupkg file:

  1. Fügen Sie folgende Eigenschaften zur CSPROJ-Datei hinzu:Add the following properties to your .csproj file:

    <PropertyGroup>
      <IncludeSymbols>true</IncludeSymbols>
      <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    </PropertyGroup>
    
  2. Packen Sie Ihr Projekt mit dotnet pack MyPackage.csproj oder msbuild -t:pack MyPackage.csproj.Pack your project with dotnet pack MyPackage.csproj or msbuild -t:pack MyPackage.csproj.

Die Eigenschaft SymbolPackageFormat kann einen von zwei Werten besitzen: symbols.nupkg (Standard) oder snupkg.The SymbolPackageFormat property can have one of two values: symbols.nupkg (the default) or snupkg. Wenn die Eigenschaft SymbolPackageFormat nicht festgelegt wurde, wird ein älteres Symbolpaket erstellt.If the SymbolPackageFormat property is not specified, a legacy symbol package will be created.

Hinweis

Das ältere Format .symbols.nupkg wir noch immer unterstützt, jedoch nur aus Kompatibilitätsgründen (weitere Informationen unter Erstellen von Symbolpaketen).The legacy format .symbols.nupkg is still supported but only for compatibility reasons (see Legacy Symbol Packages). Der NuGet.org-Symbolserver akzeptiert nur das neue Symbolpaketformat .snupkg.NuGet.org's symbol server only accepts the new symbol package format - .snupkg.

Veröffentlichen eines SymbolpaketsPublishing a symbol package

  1. Speichern Sie zunächst der Einfachheit halber Ihren API-Schlüssel mit NuGet (weitere Informationen unter publish a package (Veröffentlichen eines Pakets)).For convenience, first save your API key with NuGet (see publish a package).

    nuget SetApiKey Your-API-Key
    
  2. Nachdem Sie Ihr primäres Paket auf nuget.org veröffentlicht haben, übertragen Sie Ihr Symbol mithilfe von Push wie hier dargestellt:After publishing your primary package to nuget.org, push the symbol package as follows.

    nuget push MyPackage.snupkg
    
  3. Sie können mit dem folgenden Befehl auch das primäre Paket und Symbolpakete gleichzeitig mithilfe von Push übertragen, um Zeit zu sparen.You can also push both primary and symbol packages at the same time using the below command. Die NUPKG- und SNUPKG-Dateien müssen jeweils im aktuellen Ordner vorhanden sein.Both .nupkg and .snupkg files need to be present in the current folder.

    nuget push MyPackage.nupkg
    

NuGet veröffentlicht beide Pakete auf nuget.org. MyPackage.nupkg wird zuerst veröffentlicht, gefolgt von MyPackage.snupkg.NuGet will publish both packages to nuget.org. MyPackage.nupkg will be published first, followed by MyPackage.snupkg.

Hinweis

Wenn das Symbolpaket nicht veröffentlicht wird, vergewissern Sie sich, dass Sie die NuGet.org-Quelle folgendermaßen konfiguriert haben: 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. Die Veröffentlichung des Symbolpakets wird nur von der NuGet V3-API unterstützt.Symbol package publishing is only supported by the NuGet V3 API.

NuGet.org-SymbolserverNuGet.org symbol server

NuGet.org unterstützt das eigene Symbolserverrepository und akzeptiert ausschließlich das neue Symbolpaketformat .snupkg.NuGet.org supports its own symbols server repository and only accepts the new symbol package format - .snupkg. Paketverbraucher können die auf nuget.org-Symbolservern veröffentlichen Symbole verwenden, indem sie https://symbols.nuget.org/download/symbols zu ihren Symbolquellen in Visual Studio hinzufügen, wodurch Paketcode im Visual Studio Debugger schrittweise verwendet werden kann.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. Weitere Einzelheiten zu diesem Prozess finden Sie unter Angeben von Symbol- (PDB) und Quelldateien im Visual Studio Debugger.See Specify symbol (.pdb) and source files in the Visual Studio debugger for details on that process.

Einschränkungen für nuget.org-SymbolpaketeNuget.org symbol package constraints

Die auf nuget.org unterstützten Symbolpakete unterliegen den folgenden EinschränkungenThe symbol packages supported on nuget.org have the following contraints

  • Es dürfen ausschließlich die folgenden Dateierweiterungen an ein Symbolpaket angefügt werden.Only the following file extensions are allowed to be added to a symbol package. .pdb,.nuspec,.xml,.psmdcp,.rels,.p7s
  • Auf dem NuGet-Symbolserver werden derzeit nur verwaltete und portable PDB-Dateien unterstützt.Only managed Portable pdbs are currently supported on nuget symbol server.
  • Die PDB-Dateien und zugehörigen NUPKG-DLLs müssen mit dem Compiler in Visual Studio 15.9 oder höher erstellt worden sein (weiter Informationen unter pdb crypto hash (Kryptografiehash für PDB-Dateien)).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)

Das auf nuget.org veröffentlichte Symbolpaket schlägt fehl, wenn ein anderer Dateityp in der SNUPKG-Datei enthalten ist.The symbol package publish on nuget.org will fail if any other file types are included in the .snupkg.

Symbolpaketvalidierung und -indizierungSymbol package validation and indexing

Per Push an NuGet.org übertragene Symbolpakete werden verschiedenen Prüfungen, wie z.B. auf Viren, unterzogen.Symbol packages published to NuGet.org undergo several validations, such as virus checks.

Wenn das Paket alle Validierungsüberprüfungen bestanden hat, kann es dennoch eine Weile dauern, bis die Symbole indiziert werden und zur Nutzung über die NuGet.org-Symbolserver bereitstehen.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. Wenn das Paket eine Validierungsüberprüfung nicht besteht, wird die Paketdetailansicht für NUPKG aktualisiert und zeigt den entsprechenden Fehler an. Auch dann erhalten Sie eine E-Mail-Benachrichtigung.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.

Die Validierung und Indizierung eines Pakets nimmt für gewöhnlich unter 15 Minuten in Anspruch.Package validation and indexing usually takes under 15 minutes. Wenn das Veröffentlichen des Pakets längere Zeit als erwartet in Anspruch nimmt, besuchen Sie status.nuget.org, um zu überprüfen, ob gerade eine Störung auf nuget.org vorliegt.If the package publishing is taking longer than expected, visit status.nuget.org to check if nuget.org is experiencing any interruptions. Wenn alle Systeme in Betrieb sind und das Paket innerhalb einer Stunde nicht erfolgreich veröffentlicht wurde, melden Sie sich auf nuget.org an, und informieren Sie uns über den Link zum Support auf der Paketdetailseite.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.

SymbolpaketstrukturSymbol package structure

Die NUPKG-Datei wäre genau dieselbe wie heute, die SNUPKG-Datei würde jedoch folgende Eigenschaften aufweisen:The .nupkg file would be exactly the same as it is today, but the .snupkg file would have the following characteristics:

  1. Die SNUPKG-Datei besitzt dieselbe ID und Version wie die entsprechende NUPKG-Datei.The .snupkg will have the same id and version as the corresponding .nupkg.
  2. Für jede DLL- oder EXE-Datei enthält die SNUPKG-Datei dann dieselbe Ordnerstruktur wie die NUPKG-Datei, mit dem einzigen Unterschied, dass die entsprechenden PDB-Dateien in der gleichen Ordnerhierarchie eingeschlossen werden würden (anstelle der DLL-/EXE-Dateien).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. Dateien und Ordner mit anderen Erweiterungen als PDB werden aus der SNUPKG-Datei ausgeschlossen.Files and folders with extensions other than PDB will be left out of the snupkg.
  3. Die NUSPEC-Datei im SNUPKG-Paket gibt auch einen neuen PackageType an, so wie unten dargestellt.The .nuspec file in the .snupkg will also specify a new PackageType as below. Dieser sollte der einzige angegebene PackageType sein.This should the only one PackageType specified.
<packageTypes>
  <packageType name="SymbolsPackage"/>
</packageTypes>
  1. Wenn sich ein Autor dazu entscheidet, eine benutzerdefinierte NUSPEC-Datei für die Erstellung von NUPKG- und SNUPKG-Dateien zu verwenden, muss die SNUPKG-Datei über die gleiche Ordnerhierarchie und die gleichen Dateien wie unter Punkt 2 beschrieben verfügen.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. Die Felder authors und owners werden aus der NUSPEC-Datei von SNUPKG ausgeschlossen.authors and owners field will be excluded from the snupkg's nuspec.

Siehe auchSee Also

NuGet-Package-Debugging-&-Symbols-Improvements (Verbesserungen für das Debuggen und die Symbole von NuGet-Paketen)NuGet-Package-Debugging-&-Symbols-Improvements