Tworzenie pakietów symboli (.snupkg)

Dobre środowisko debugowania opiera się na obecności symboli debugowania, ponieważ zapewniają krytyczne informacje, takie jak skojarzenie między skompilowanym a kodem źródłowym, nazwami zmiennych lokalnych, śladami stosu i nie tylko. Za pomocą pakietów symboli (snupkg) można dystrybuować te symbole i ulepszać środowisko debugowania pakietów NuGet.

Pamiętaj, że pakiet symboli nie jest jedyną strategią udostępniania symboli debugowania użytkownikom biblioteki. Możliwe jest również embed użycie ich we dll właściwości lub exe z następującą właściwością projektu:<DebugType>embedded</DebugType>

Wymagania wstępne

nuget.exe w wersji 4.9.0 lub nowszej lub interfejsu wiersza polecenia dotnet w wersji 2.2.0 lub nowszej, co implementuje wymagane protokoły NuGet.

Tworzenie pakietu symboli

Jeśli używasz interfejsu IncludeSymbols wiersza polecenia dotnet lub msBuild, musisz ustawić właściwości i SymbolPackageFormat , aby utworzyć plik snupkg oprócz pliku nupkg.

• Dodaj następujące właściwości do pliku csproj:

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

• Możesz też określić te właściwości w wierszu polecenia:

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

  lub

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

Jeśli używasz NuGet.exe, możesz użyć następujących poleceń, aby utworzyć plik snupkg oprócz pliku nupkg:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

Właściwość SymbolPackageFormat może mieć jedną z dwóch wartości: symbols.nupkg (wartość domyślna) lub snupkg. Jeśli ta właściwość nie zostanie określona, zostanie utworzony starszy pakiet symboli.

Uwaga

Starszy format .symbols.nupkg jest nadal obsługiwany, ale tylko ze względów zgodności, takich jak pakiety natywne (zobacz Starsze pakiety symboli). Serwer symboli nuGet.org akceptuje tylko nowy format pakietu symboli — .snupkg.

Publikowanie pakietu symboli

Uwaga

Usługa Azure Devops Artifacts obecnie nie obsługuje debugowania za pośrednictwem .snupkg plików.

1. Dla wygody najpierw zapisz klucz interfejsu API za pomocą narzędzia NuGet (zobacz publikowanie pakietu).

   nuget SetApiKey Your-API-Key
   

2. Po opublikowaniu pakietu podstawowego w celu nuget.org wypchnij pakiet symboli w następujący sposób.

   nuget push MyPackage.snupkg
   

3. Jednocześnie można wypchnąć zarówno pakiety podstawowe, jak i pakiety symboli, używając poniższego polecenia. Pliki .nupkg i .snupkg muszą znajdować się w bieżącym folderze.

   nuget push MyPackage.nupkg
   

Narzędzie NuGet opublikuje oba pakiety w nuget.org. MyPackage.nupkg zostanie opublikowana jako pierwsza, a następnie .MyPackage.snupkg

Uwaga

Jeśli pakiet symboli nie został opublikowany, sprawdź, czy skonfigurowano źródło NuGet.org jako https://api.nuget.org/v3/index.json. Publikowanie pakietu symboli jest obsługiwane tylko przez interfejs API NuGet w wersji 3.

serwer symboli NuGet.org

NuGet.org obsługuje własne repozytorium serwerów symboli i akceptuje tylko nowy format pakietu symboli — .snupkg. Użytkownicy pakietów mogą używać symboli opublikowanych w celu nuget.org serwera symboli przez dodanie https://symbols.nuget.org/download/symbols ich do źródeł symboli w programie Visual Studio, co umożliwia przejście do kodu pakietu w debugerze programu Visual Studio. Aby uzyskać szczegółowe informacje na temat tego procesu, zobacz Określanie symboli (pdb) i plików źródłowych w debugerze programu Visual Studio.

NuGet.org ograniczenia pakietu symboli

NuGet.org ma następujące ograniczenia dla pakietów symboli:

• Tylko następujące rozszerzenia plików są dozwolone w pakietach symboli: .pdb, , .xml.nuspec, .psmdcp, , .rels.p7s
• Na serwerze symboli NuGet.org są obsługiwane tylko zarządzane przenośne pliki PDB .
• Pliki PDB i skojarzone z nimi biblioteki DLL nupkg muszą zostać skompilowane za pomocą kompilatora w programie Visual Studio w wersji 15.9 lub nowszej (zobacz skrót kryptograficzny pdB)

Pakiety symboli opublikowane w NuGet.org zakończy się niepowodzeniem, jeśli te ograniczenia nie zostaną spełnione.

Uwaga

Projekty natywne, takie jak projekty C++, generują pliki PDB systemu Windows zamiast przenośnych plików PDB. Nie są one obsługiwane przez serwer symboli NuGet.org. Zamiast tego użyj starszych pakietów symboli .

Walidacja i indeksowanie pakietów symboli

Pakiety symboli opublikowane w NuGet.org przechodzą kilka walidacji, w tym skanowanie w poszukiwaniu złośliwego oprogramowania. Jeśli sprawdzanie poprawności pakietu zakończy się niepowodzeniem, na stronie szczegółów pakietu zostanie wyświetlony komunikat o błędzie. Ponadto właściciele pakietu otrzymają wiadomość e-mail z instrukcjami dotyczącymi rozwiązywania zidentyfikowanych problemów.

Gdy pakiet symboli przeszedł wszystkie walidacje, symbole będą indeksowane przez serwery symboli NuGet.org i będą dostępne do użycia.

Walidacja i indeksowanie pakietów zwykle trwa poniżej 15 minut. Jeśli publikowanie pakietu trwa dłużej niż oczekiwano, odwiedź status.nuget.org , aby sprawdzić, czy NuGet.org występują jakiekolwiek przerwy. Jeśli wszystkie systemy działają, a pakiet nie został pomyślnie opublikowany w ciągu godziny, zaloguj się, aby nuget.org i skontaktuj się z nami przy użyciu linku Skontaktuj się z pomocą techniczną na stronie szczegółów pakietu.

Struktura pakietu symboli

Pakiet symboli (snupkg) ma następujące cechy:

1. Plik snupkg ma ten sam identyfikator i wersję co odpowiedni pakiet NuGet (nupkg).

2. Plik .snupkg ma taką samą strukturę folderów, jak odpowiedni plik .nupkg dla dowolnych plików DLL lub EXE z rozróżnieniem, że zamiast bibliotek DLL/EXEs odpowiednie pliki PDB zostaną uwzględnione w tej samej hierarchii folderów. Pliki i foldery z rozszerzeniami innymi niż PDB zostaną pominięte z snupkg.

3. Plik nuspec pakietu symboli ma SymbolsPackage typ pakietu:

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

4. Jeśli autor zdecyduje się użyć niestandardowego narzędzia nuspec do skompilowania ich nupkg i snupkg, snupkg powinien mieć tę samą hierarchię folderów i pliki szczegółowo opisane w 2).

5. Następujące pola zostaną wykluczone z nuspec snupkg: authors, , ownersrequireLicenseAcceptance, license type, licenseUrl, i icon.

6. Nie używaj <license> elementu . Plik snupkg jest objęty tą samą licencją co odpowiedni plik nupkg.

Zobacz też

Rozważ użycie linku źródłowego, aby włączyć debugowanie kodu źródłowego zestawów platformy .NET. Aby uzyskać więcej informacji, zapoznaj się ze wskazówkami dotyczącymi linku źródłowego.

Aby uzyskać więcej informacji na temat pakietów symboli, zapoznaj się ze specyfikacją projektu Ulepszenia projektu debugowania pakietów NuGet i symboli.