Sdílet prostřednictvím

Vytváření balíčků symbolů (.snupkg)

  • Článek

Dobré prostředí ladění závisí na přítomnosti symbolů ladění, protože poskytují důležité informace, jako je přidružení mezi kompilovaným a zdrojovým kódem, názvy místních proměnných, trasování zásobníku a další. Balíčky symbolů (.snupkg) můžete použít k distribuci těchto symbolů a ke zlepšení prostředí ladění balíčků NuGet.

Všimněte si, že balíček symbolů není jedinou strategií, jak zpřístupnit symboly ladění uživatelům knihovny. Je také možné, aby embed byly v následující dll vlastnosti projektu nebo exe s následující vlastností projektu: <DebugType>embedded</DebugType>

Požadavky

nuget.exe v4.9.0 nebo novější nebo rozhraní příkazového řádku dotnet v2.2.0 nebo vyšší, které implementují požadované protokoly NuGet.

Vytvoření balíčku symbolů

Pokud používáte rozhraní příkazového řádku dotnet nebo MSBuild, je potřeba nastavit IncludeSymbols a SymbolPackageFormat vlastnosti pro vytvoření souboru .snupkg kromě souboru .nupkg.

  • Do souboru .csproj přidejte následující vlastnosti:

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

  • Nebo na příkazovém řádku zadejte tyto vlastnosti:

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

    nebo

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

Pokud používáte NuGet.exe, můžete kromě souboru .nupkg vytvořit soubor .snupkg pomocí následujících příkazů:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

Vlastnost SymbolPackageFormat může mít jednu ze dvou hodnot: symbols.nupkg (výchozí) nebo snupkg. Pokud tato vlastnost není zadána, vytvoří se starší balíček symbolů.

Poznámka:

Starší formát .symbols.nupkg je stále podporovaný, ale pouze z důvodů kompatibility, jako jsou nativní balíčky (viz Balíčky starších symbolů). Server symbolů NuGet.org přijímá pouze nový formát balíčku symbolů - .snupkg.

Publikování balíčku symbolů

Poznámka:

Azure Devops Artifacts v současné době nepodporuje ladění prostřednictvím .snupkg souborů.

  1. Pro usnadnění práce nejprve uložte klíč rozhraní API pomocí NuGetu (viz publikování balíčku).

    nuget SetApiKey Your-API-Key

  2. Po publikování primárního balíčku do nuget.org nasdílejte balíček symbolů následujícím způsobem.

    nuget push MyPackage.snupkg

  3. Balíčky primárních i symbolů můžete také odeslat současně pomocí následujícího příkazu. Soubory .nupkg i .snupkg musí být přítomné v aktuální složce.

    nuget push MyPackage.nupkg

NuGet publikuje oba balíčky do nuget.org. MyPackage.nupkg bude publikována jako první, následovaná MyPackage.snupkg.

Poznámka:

Pokud balíček symbolů není publikovaný, zkontrolujte, že jste nakonfigurovali zdroj NuGet.org jako https://api.nuget.org/v3/index.json. Publikování balíčků symbolů podporuje pouze rozhraní API NuGet v3.

server symbolů NuGet.org

NuGet.org podporuje vlastní úložiště serverů symbolů a přijímá pouze nový formát balíčku symbolů - .snupkg. Příjemci balíčků můžou používat symboly publikované na serveru symbolů nuget.org přidáním https://symbols.nuget.org/download/symbols do jejich zdrojů symbolů v sadě Visual Studio, což umožňuje krokování do kódu balíčku v ladicím programu sady Visual Studio. Podrobnosti o tomto procesu najdete v části Určení symbolu (.pdb) a zdrojových souborů v ladicím programu sady Visual Studio.

Omezení balíčku symbolů NuGet.org

NuGet.org má pro balíčky symbolů následující omezení:

  • V balíčcích symbolů jsou povoleny pouze následující přípony souborů: .pdb, .nuspec, .xml.psmdcp, , .rels.p7s
  • Na serveru symbolů NuGet.org se podporují jenom spravované přenosné soubory PDB .
  • Soubory PDB a jejich přidružené knihovny DLL nupkg je potřeba sestavit pomocí kompilátoru v sadě Visual Studio verze 15.9 nebo vyšší (viz kryptografická hodnota hash PDB).

Balíčky symbolů publikované do NuGet.org ověření selžou, pokud tato omezení nejsou splněna.

Poznámka:

Nativní projekty, jako jsou projekty C++, vytvářejí soubory PDB systému Windows místo přenosných souborů PDB. Server symbolů NuGet.org je nepodporuje. Místo toho použijte starší balíčky symbolů .

Ověřování a indexování balíčků symbolů

Balíčky symbolů publikované do NuGet.org prošly několika ověřeními, včetně kontroly malwaru. Pokud balíček selže při kontrole ověření, zobrazí se na stránce s podrobnostmi balíčku chybová zpráva. Vlastníci balíčku navíc dostanou e-mail s pokyny, jak vyřešit zjištěné problémy.

Když balíček symbolů prošel všemi ověřeními, budou symboly indexovány servery symbolů NuGet.org a budou k dispozici pro použití.

Ověření a indexování balíčků obvykle trvá méně než 15 minut. Pokud publikování balíčku trvá déle, než se čekalo, navštivte status.nuget.org a zkontrolujte, jestli u NuGet.org nedochází k přerušení. Pokud jsou všechny systémy funkční a balíček nebyl úspěšně publikován do hodiny, přihlaste se k nuget.org a kontaktujte nás pomocí odkazu Kontaktovat podporu na stránce s podrobnostmi balíčku.

Struktura balíčku symbolů

Balíček symbolů (.snupkg) má následující vlastnosti:

  1. .snupkg má stejné ID a verzi jako odpovídající balíček NuGet (.nupkg).

  2. Soubor .snupkg má stejnou strukturu složek jako odpovídající soubor .nupkg pro všechny soubory DLL nebo EXE s rozdílem, že místo knihoven DLL/EXEs budou jejich odpovídající soubory PDB zahrnuty ve stejné hierarchii složek. Soubory a složky s jinými příponami než PDB se vynechá z snupkg.

  3. Soubor .nuspec balíčku symbolu SymbolsPackage má typ balíčku:

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

  4. Pokud se autor rozhodne použít vlastní nuspec k sestavení jejich nupkg a snupkg, snupkg by měl mít stejnou hierarchii složek a soubory podrobně popsané ve 2).

  5. Následující pole budou vyloučena z nuspec snupkg: authors, owners, requireLicenseAcceptance, license type, licenseUrla icon.

  6. Nepoužívejte <license> prvek. Soubor .snupkg se vztahuje na stejnou licenci jako odpovídající .nupkg.

Viz také

Zvažte použití zdrojového odkazu k povolení ladění zdrojového kódu sestavení .NET. Další informace najdete v doprovodných materiálech ke zdrojovému odkazu.

Další informace o balíčcích symbolů najdete ve specifikaci návrhu ladění balíčků NuGet a vylepšení symbolů .