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

Für ein benutzerfreundliches Debugging sind Debugsymbole erforderlich, weil diese wichtige Informationen anzeigen, wie z. B. die Zuordnung des kompilierten Codes zum Quellcode, die Namen lokaler Variablen und Stapelüberwachungen.A good debugging experience relies on the presence of debug symbols as they provide critical information like the association between the compiled and the source code, names of local variables, stack traces, and more. Mithilfe von Symbolpaketen (.snupkg) können Sie diese Symbole verteilen und das Debugging Ihrer NuGet-Pakete optimieren.You can use symbol packages (.snupkg) to distribute these symbols and improve the debugging experience of your NuGet packages.

Beachten Sie, dass ein Symbolpaket nicht die einzige Strategie ist, mit der die Debugsymbole den Consumern Ihrer Bibliothek zur Verfügung gestellt werden können.Note that symbol package isn't the only strategy to make the debug symbols available to the consumers of your library. Sie können auch mit der folgenden Projekteigenschaft in die dll- oder die exe-Datei eingebettet werdenembed: <DebugType>embedded</DebugType>It's also possible to embed them in the dll or exe with the following project property: <DebugType>embedded</DebugType>

VoraussetzungenPrerequisites

nuget.exe, Version 4.9.0 oder höher oder die .NET-CLI, Version 2.2.0 oder höher, da diese die erforderlichen NuGet-Protokolle implementieren.nuget.exe v4.9.0 or above or dotnet CLI v2.2.0 or above, which implement the required NuGet protocols.

Erstellen eines SymbolpaketsCreating a symbol package

Wenn Sie die .NET-CLI oder MSBuild verwenden, müssen Sie die Eigenschaften IncludeSymbols und SymbolPackageFormat festlegen, um zusätzlich zur NUPKG-Datei eine SNUPKG-Datei zu erstellen.If you're using dotnet CLI or MSBuild, you need to set the IncludeSymbols and SymbolPackageFormat properties to create a .snupkg file in addition to the .nupkg file.

  • Fügen Sie entweder die folgenden Eigenschaften zur CSPROJ-Datei hinzu:Either add the following properties to your .csproj file:

    <PropertyGroup>
        <IncludeSymbols>true</IncludeSymbols>
        <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    </PropertyGroup>
    
  • Geben Sie alternativ diese Eigenschaften in der Befehlszeile an:Or specify these properties on the command-line:

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

    oderor

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

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

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 diese Eigenschaft nicht festgelegt wurde, wird ein älteres Legacypaket erstellt.If this property is not specified, a legacy symbol package will be created.

Hinweis

Das ältere Format .symbols.nupkg wird noch immer unterstützt, jedoch nur aus Kompatibilitätsgründen (z. B. native Pakete). Weitere Informationen finden Sie unter Erstellen von Legacysymbolpaketen (.symbols.nupkg).The legacy format .symbols.nupkg is still supported but only for compatibility reasons like native packages (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

NuGet.org weist die folgenden Einschränkungen für Symbolpakete auf:NuGet.org has the following constraints for symbol packages:

  • Nur die folgenden Dateierweiterungen sind in Symbolpaketen zulässig: .pdb, .nuspec, .xml, .psmdcp, .rels, .p7sOnly the following file extensions are allowed in symbol packages: .pdb, .nuspec, .xml, .psmdcp, .rels, .p7s
  • Auf dem NuGet-Symbolserver werden nur verwaltete Portable PDB-Dateien unterstützt.Only managed Portable PDBs are supported on NuGet.org's symbol server.
  • Die PDB-Dateien und ihre zugehörigen NUPKG-DLLs müssen mit dem Compiler in Visual Studio 15.9 oder höher erstellt worden sein (weitere Informationen unter PDB crypto hash (Kryptografiehash für PDB-Dateien)).The PDBs and their associated .nupkg DLLs need to be built with the compiler in Visual Studio version 15.9 or above (see PDB crypto hash)

Bei Symbol Paketen, die auf NuGet.org veröffentlicht werden, tritt bei der Überprüfung ein Fehler auf, wenn diese Bedingungen nicht erfüllt sind.Symbol packages published to NuGet.org will fail validation if these constraints aren't met.

Hinweis

Native Projekte wie C++-Projekte erzeugen Windows-PDB-Dateien anstelle von portierbaren PDB-Dateien.Native projects, such as C++ projects, produce Windows PDBs instead of Portable PDBs. Diese werden vom Symbolserver von NuGet.org nicht unterstützt.These are not supported by NuGet.org's symbol server. Verwenden Sie stattdessen Legacysymbolpakete.Please use Legacy Symbol Packages instead.

Symbolpaketvalidierung und -indizierungSymbol package validation and indexing

Per Push an NuGet.org übertragene Symbolpakete werden verschiedenen Prüfungen unterzogen, darunter eine Prüfung auf Schadsoftware.Symbol packages published to NuGet.org undergo several validations, including malware scanning. Wenn bei einem Paket ein Fehler bei der Überprüfung auftritt, wird auf dessen Paketdetailseite eine Fehlermeldung angezeigt.If a package fails a validation check, its package details page will display an error message. Darüber hinaus erhalten die Besitzer des Pakets eine E-Mail mit Anweisungen zum Beheben der erkannten Probleme.In addition, the package's owners will receive an email with instructions on how to fix the identified issues.

Wenn das Symbolpaket alle Überprüfungen bestanden hat, werden die Symbole von den Symbolservern von nuget.org indiziert und sind für die Verwendung verfügbar.When the symbol package has passed all validations, the symbols will be indexed by NuGet.org's symbol servers and will be available for consumption.

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änger als erwartet dauert, besuchen Sie status.nuget.org, um zu überprüfen, ob gerade eine Störung auf nuget.org vorliegt.If the package publishing takes 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

Das Symbolpaket (.snupkg) weist die folgenden Eigenschaften auf:The symbol package (.snupkg) has the following characteristics:

  1. Die SNUPKG-Datei hat dieselbe ID und Version wie das entsprechende NuGet-Paket (.nupkg).The .snupkg has the same id and version as its corresponding NuGet package (.nupkg).

  2. Das Symbolpaket (.snupkg) weist bei allen DLL- oder EXE-Dateien dieselbe Ordnerstruktur wie die das NuGet-Paket (.nupkg) auf. Der einzige Unterschied ist, dass anstelle der DLL-/EXE-Dateien die entsprechenden PDB-Dateien in dieselbe Ordnerhierarchie aufgenommen werden.The .snupkg has the same folder structure as its corresponding .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 des Symbolpakets ist vom Pakettyp SymbolsPackage:The symbol package's .nuspec file has the SymbolsPackage package type:

    <packageTypes>
       <packageType name="SymbolsPackage"/>
    </packageTypes>
    
  4. 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).

  5. Die folgenden Felder werden aus der NUSPEC-Datei von SNUPKG ausgeschlossen: authors, owners, requireLicenseAcceptance, license type, licenseUrl und icon.The following fields will be excluded from the snupkg's nuspec: authors, owners, requireLicenseAcceptance, license type, licenseUrl, and icon.

  6. Verwenden Sie nicht das <license>-Element.Do not use the <license> element. Eine SNUPKG-Datei wird von der gleichen Lizenz abgedeckt wie die entsprechende NUPKG-Datei.A .snupkg is covered under the same license as the corresponding .nupkg.

Siehe auchSee also

Erwägen Sie die Verwendung von SourceLink, um das Debuggen des Quellcodes von .NET-Assemblys zu aktivieren.Consider using Source Link to enable source code debugging of .NET assemblies. Weitere Informationen finden Sie in der SourceLink-Anleitung.For more information, please refer to the Source Link guidance.

Weitere Informationen zu Symbolpaketen finden Sie in den Entwurfsspezifikationen für NuGet Package Debugging & Symbols Improvements (Debuggen von NuGet-Paketen und Verbesserungen bei Symbolen).For more information on symbol packages, please refer to the NuGet Package Debugging & Symbols Improvements design spec.