建立符號套件 (snupkg)

文章
12/14/2023

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

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

必要條件

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

建立符號套件

如果您使用 dotnet CLI 或 MSBuild，除了 .nupkg 檔案之外，還需要設定 IncludeSymbols 和 SymbolPackageFormat 屬性來建立 .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 檔案進行偵錯。

為方便起見，請先使用 NuGet 儲存您的 API 金鑰 (請參閱發佈套件)。
```
nuget SetApiKey Your-API-Key
```
將主要套件發佈至 nuget.org 後，接著推送符號套件。
```
nuget push MyPackage.snupkg
```
您也可以使用以下命令，同時推送主要套件與符號套件。 .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）具有下列特性：

.snupkg 的標識符和版本與其對應的 NuGet 套件（.nupkg）相同。
.snupkg 與任何 DLL 或 EXE 檔案的對應 .nupkg 具有相同的資料夾結構，其對應的 PDB 會包含在相同的資料夾階層中。含有非 PDB 延伸模組的檔案與資料夾，將會排除在 snupkg 之外。

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

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

如果作者決定使用自訂 nuspec 來建置他們的 nupkg 和 snupkg，snupkg 應會有相同的資料夾階層與檔案，詳細資料位於 2)。
下列欄位將會從 snupkg 的 nuspec 中排除： authors、 owners、、 requireLicenseAcceptance、 license type、 licenseUrl和 icon。
請勿使用 <license> 元素。 .snupkg 的授權涵蓋範圍與對應的 .nupkg 相同。

另請參閱

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

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

分享方式：