分享方式:


建立符號套件 (snupkg)

良好的偵錯體驗依賴偵錯符號的存在,因為它們提供重要資訊,例如編譯和原始碼之間的關聯、局部變數的名稱、堆棧追蹤等等。 您可以使用符號套件 (.snupkg) 來散發這些符號,並改善 NuGet 套件的偵錯體驗。

請注意,符號套件不是讓偵錯符號可供連結庫取用者的唯一策略。 您也可以embed在或 exe 中使用dll下列項目屬性:<DebugType>embedded</DebugType>

必要條件

nuget.exe v4.9.0 或更新 版本或 dotnet CLI v2.2.0 或更新版本,以實作必要的 NuGet 通訊協定

建立符號套件

如果您使用 dotnet CLI 或 MSBuild,除了 .nupkg 檔案之外,還需要設定 IncludeSymbolsSymbolPackageFormat 屬性來建立 .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。 如果未指定此屬性,將會建立舊版符號套件。

注意

舊版格式 .symbols.nupkg 仍受支援,但只基於原生套件等相容性原因(請參閱 舊版符號套件)。 NuGet.org 的符號伺服器只接受新的符號套件格式 - .snupkg

發行符號套件

注意

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

  1. 為方便起見,請先使用 NuGet 儲存您的 API 金鑰 (請參閱發佈套件)。

    nuget SetApiKey Your-API-Key
    
  2. 將主要套件發佈至 nuget.org 後,接著推送符號套件。

    nuget push MyPackage.snupkg
    
  3. 您也可以使用以下命令,同時推送主要套件與符號套件。 .nupkg 與 .snupkg 檔案都必須出現在目前的資料夾中。

    nuget push MyPackage.nupkg
    

NuGet 會將兩個套件發行到 nuget.org。將會先發行 MyPackage.nupkg,再發行 MyPackage.snupkg

注意

若符號套件未發行,請檢查您是否已將 NuGet.org 來源設定為 https://api.nuget.org/v3/index.json。 只有 NuGet V3 API 才支援符號套件發行。

NuGet.org 符號伺服器

NuGet.org 支援自己的符號伺服器存放庫,且只接受新的符號套件格式 - .snupkg。 套件取用者可將 https://symbols.nuget.org/download/symbols 新增至其在 Visual Studio 中的符號來源,使用發佈至 nuget.org 符號伺服器的符號,如此即可在 Visual Studio 偵錯工具中,介入套件程式碼。 如需該程序的詳細資料,請參閱在 Visual Studio Debugger 中指定符號 (.pdb) 和原始程式檔

NuGet.org 符號套件條件約束

NuGet.org 符號套件具有下列條件約束:

  • 符號套件中只允許下列擴展名:.pdb、、.nuspec.xml.psmdcp.rels.p7s
  • NuGet.org 的符號伺服器僅支援受控 可攜式 PDB
  • PDB 及其相關聯的 .nupkg DLL 必須在 Visual Studio 15.9 版或更新版本中使用編譯程式建置(請參閱 PDB 密碼編譯哈希

如果不符合這些條件約束,發行至 NuGet.org 的符號套件將會失敗。

注意

原生專案,例如 C++ 專案,會產生 Windows PDB,而不是可攜式 PDB。 NuGet.org 的符號伺服器不支援這些專案。 請改用 舊版符號套件

符號套件的驗證與製作索引

發佈至 NuGet.org 的符號套件會經過數個驗證,包括惡意代碼掃描。 如果封裝驗證檢查失敗,其套件詳細數據頁面會顯示錯誤訊息。 此外,套件的擁有者會收到電子郵件,其中包含如何修正已識別問題的指示。

當符號套件通過所有驗證時,符號會由 NuGet.org 的符號伺服器編製索引,並可供取用。

套件驗證和編製索引通常在 15 分鐘內完成。 如果套件發佈花費的時間超過預期,請造訪 status.nuget.org 來檢查 NuGet.org 是否發生任何中斷。 若所有系統皆可運作,但套件未在一小時內成功發佈,請登入 nuget.org 並使用套件詳細資料頁面上的聯絡支援連結,連絡我們。

符號套件結構

符號套件 (.snupkg) 具有下列特性:

  1. .snupkg 的標識符和版本與其對應的 NuGet 套件 (.nupkg) 相同。

  2. .snupkg 與任何 DLL 或 EXE 檔案的對應 .nupkg 具有相同的資料夾結構,其對應的 PDB 會包含在相同的資料夾階層中。 含有非 PDB 延伸模組的檔案與資料夾,將會排除在 snupkg 之外。

  3. 符號套件的 .nuspec 檔案具有 SymbolsPackage 套件類型:

    <packageTypes>
       <packageType name="SymbolsPackage"/>
    </packageTypes>
    
  4. 如果作者決定使用自訂 nuspec 來建置他們的 nupkg 和 snupkg,snupkg 應會有相同的資料夾階層與檔案,詳細資料位於 2)。

  5. 下列欄位將會從 snupkg 的 nuspec 中排除: authorsowners、、 requireLicenseAcceptancelicense typelicenseUrlicon

  6. 請勿使用 <license> 元素。 .snupkg 的授權涵蓋範圍與對應的 .nupkg 相同。

另請參閱

請考慮使用來源連結來啟用 .NET 元件的原始程式碼偵錯。 如需詳細資訊,請參閱 來源連結指引

如需符號套件的詳細資訊,請參閱 NuGet 套件偵錯和符號改進 設計規格。