建立符號套件（.snupkg）

良好的除錯體驗依賴除錯符號的存在，因為它們提供了關鍵資訊，如編譯後與原始碼之間的關聯、本地變數名稱、堆疊追蹤等。 你可以使用符號套件（.snupkg）來分發這些符號，並提升 NuGet 套件的除錯體驗。

請注意，符號套件並不是讓除錯符號能提供給函式庫使用者的唯一策略。 他們也可以在以下專案屬性中 取得 embeddllexe ： <DebugType>embedded</DebugType>

先決條件

nuget.exe v4.9.0 或dotnet CLI v2.2.0 或以上，這些版本實作了所需的 NuGet 協定。

建立符號套件

如果你用的是 dotnet CLI 或 MSBuild，你需要設定 IncludeSymbols 和 SymbolPackageFormat 屬性，才能在 .nupkg 檔案之外建立一個 .snupkg 檔案。

  • 要麼在你的 .csproj 檔案中加入以下屬性：

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

  • 或者在命令列中指定以下屬性：

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

    或

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

如果你正在使用 NuGet.exe，你可以使用以下指令，除了 .nupkg 檔案外，還建立一個 .snupkg 檔案：

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

屬性 SymbolPackageFormat 可以有兩種值之一： symbols.nupkg （預設值）或 snupkg。 若未指定此屬性，將建立一個遺留符號套件。

Note

舊有格式 .symbols.nupkg 仍被支援，但僅基於相容性，如原生套件（參見 舊有符號套件）。 NuGet.org 的符號伺服器僅接受新的符號套件格式 - .snupkg。

發佈符號套件

Note

Azure DevOps Artifacts目前不支援透過 .snupkg 檔案進行除錯。

  1. 為了方便起見，先用 NuGet 儲存你的 API 金鑰（參見 發佈套件）。

    nuget SetApiKey Your-API-Key

    小提示

    從 NuGet 7.6 開始，你可以設定 NUGET_API_KEY 和 NUGET_SYMBOL_API_KEY 環境變數，而不是用 SetApiKey。 欲了解更多資訊，請參閱 環境變數。

  2. 將主套件發佈給 nuget.org 後，請依照以下方式推送符號套件。

    nuget push MyPackage.snupkg

  3. 你也可以同時使用以下指令推送主封裝和符號封裝。 .nupkg 和 .snupkg 檔案必須同時存在於目前的資料夾中。

    nuget push MyPackage.nupkg

NuGet 將同時發佈這兩個套件給 nuget.org。 MyPackage.nupkg 將先發表，接著是 MyPackage.snupkg。

Note

如果符號套件沒有公開，請檢查你是否已將 NuGet.org 原始碼設定為 https://api.nuget.org/v3/index.json。 符號套件發佈僅由 NuGet V3 API 支援。

NuGet.org 符號伺服器

NuGet.org 支援自己的符號伺服器儲存庫，且僅接受新的符號套件格式 - .snupkg。 套件使用者可以透過在 Visual Studio 中將 https://symbols.nuget.org/download/symbols 加入符號來源，使用 nuget.org 符號伺服器所發佈的符號，這允許在 Visual Studio 除錯器中進入套件程式碼。 有關該程序的詳細資訊，請參見Visual Studio除錯器中的指定符號（.pdb）及原始碼檔案。

NuGet.org 符號封包限制

NuGet.org 對符號封包有以下限制：

  • 符號套件.pdb中僅允許以下檔案副檔名：、、.nuspec、.psmdcp.xml.rels、.p7s
  • NuGet.org 的符號伺服器僅支援受管理的可攜式 PDB。
  • PDB 及其相關的 .nupkg DLL 必須在 15.9 或更高版本的編譯器中建構Visual Studio（參見 PDB 加密雜湊）

發佈給 NuGet.org 的符號套件若未符合這些限制，將無法通過驗證。

Note

原生專案，如 C++ 專案，會產生 Windows PDB 而非可攜式 PDB。 這些不被 NuGet.org 的符號伺服器支援。 請改用 傳承符號套件 。

符號套件驗證與索引

發佈給 NuGet.org 的符號套件會經過多項驗證，包括惡意軟體掃描。 若套件未通過驗證檢查，其套件細節頁面將顯示錯誤訊息。 此外，包裹擁有者還會收到一封電子郵件，說明如何修復已識別的問題。

當符號套件通過所有驗證後，符號將被 NuGet.org 的符號伺服器索引，並可供使用者使用。

套件驗證與索引通常不到 15 分鐘。 如果套件發佈比預期更久，請造訪 status.nuget.org 查看 NuGet.org 是否遇到任何中斷。 如果所有系統運作正常，且包裹在一小時內仍未成功發布，請登入 nuget.org 並透過包裹詳情頁面的聯絡支援連結與我們聯繫。

符號封包結構

符號封裝（.snupkg）具有以下特性：

  1. .snupkg 的 ID 和版本與其對應的 NuGet 套件（.nupkg）相同。

  2. .snupkg 與其對應的 .nupkg 資料夾結構相同，適用於任何 DLL 或 EXE 檔案，但不同之處在於，對應的 PDB 會包含在同一資料夾階層中，取代 DLL/EXE。 副檔名非 PDB 的檔案和資料夾會被排除在 snupkg 之外。

  3. 符號套件的 .nuspec 檔案具有 SymbolsPackage 以下套件類型：

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

  4. 如果作者決定使用自訂 nuspec 來建立他們的 nupkg 和 snupkg，snupkg 應該會有相同的資料夾階層和檔案，詳見 2）。

  5. 以下欄位將被排除在 snupkg 的 nuspec 之外：authors， ， licenseUrlrequireLicenseAcceptancelicense typeiconowners

  6. 不要使用元素 <license> 。 .snupkg 與對應的 .nupkg 使用相同的授權。

參見

考慮使用 Source Link 來啟用 .NET 組合的原始碼除錯。 欲了解更多資訊，請參閱 來源連結指引。

欲了解更多符號套件的資訊，請參閱 NuGet 套件除錯與符號改進 設計規範。

  • Last updated on