Bagikan melalui

Membuat paket simbol (.snupkg)

  • Artikel

Pengalaman debugging yang baik bergantung pada keberadaan simbol debug karena mereka memberikan informasi penting seperti hubungan antara kode sumber dan yang dikompilasi, nama variabel lokal, jejak tumpukan, dan banyak lagi. Anda dapat menggunakan paket simbol (.snupkg) untuk mendistribusikan simbol ini dan meningkatkan pengalaman penelusuran kesalahan paket NuGet Anda.

Perhatikan bahwa paket simbol bukan satu-satunya strategi untuk membuat simbol debug tersedia untuk konsumen pustaka Anda. Dimungkinkan juga untuk embed mereka di dll atau exe dengan properti proyek berikut: <DebugType>embedded</DebugType>

Prasyarat

nuget.exe v4.9.0 atau lebih tinggi atau dotnet CLI v2.2.0 atau lebih tinggi, yang menerapkan protokol NuGet yang diperlukan.

Membuat paket simbol

Jika Anda menggunakan dotnet CLI atau MSBuild, Anda perlu mengatur IncludeSymbols properti dan SymbolPackageFormat untuk membuat file .snupkg selain file .nupkg.

  • Tambahkan properti berikut ke file .csproj Anda:

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

  • Atau tentukan properti ini pada baris perintah:

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

    or

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

Jika Anda menggunakan NuGet.exe, Anda dapat menggunakan perintah berikut untuk membuat file .snupkg selain file .nupkg:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

Properti SymbolPackageFormat dapat memiliki salah satu dari dua nilai: symbols.nupkg (default) atau snupkg. Jika properti ini tidak ditentukan, paket simbol warisan akan dibuat.

Catatan

Format .symbols.nupkg warisan masih didukung tetapi hanya karena alasan kompatibilitas seperti paket asli (lihat Paket Simbol Warisan). Server simbol NuGet.org hanya menerima format paket simbol baru - .snupkg.

Menerbitkan paket simbol

Catatan

Artefak Azure Devops saat ini tidak mendukung penelusuran kesalahan melalui .snupkg file.

  1. Untuk kenyamanan, pertama-tama simpan kunci API Anda dengan NuGet (lihat menerbitkan paket).

    nuget SetApiKey Your-API-Key

  2. Setelah menerbitkan paket utama Anda ke nuget.org, dorong paket simbol sebagai berikut.

    nuget push MyPackage.snupkg

  3. Anda juga dapat mendorong paket utama dan simbol secara bersamaan menggunakan perintah di bawah ini. File .nupkg dan .snupkg perlu ada di folder saat ini.

    nuget push MyPackage.nupkg

NuGet akan menerbitkan kedua paket ke nuget.org. MyPackage.nupkg akan diterbitkan terlebih dahulu, diikuti oleh MyPackage.snupkg.

Catatan

Jika paket simbol tidak diterbitkan, periksa apakah Anda telah mengonfigurasi sumber NuGet.org sebagai https://api.nuget.org/v3/index.json. Penerbitan paket simbol hanya didukung oleh API NuGet V3.

server simbol NuGet.org

NuGet.org mendukung repositori server simbolnya sendiri dan hanya menerima format paket simbol baru - .snupkg. Konsumen paket dapat menggunakan simbol yang diterbitkan untuk nuget.org server simbol dengan menambahkan https://symbols.nuget.org/download/symbols ke sumber simbol mereka di Visual Studio, yang memungkinkan melangkah ke kode paket di debugger Visual Studio. Lihat Menentukan simbol (.pdb) dan file sumber di debugger Visual Studio untuk detail tentang proses tersebut.

batasan paket simbol NuGet.org

NuGet.org memiliki batasan berikut untuk paket simbol:

  • Hanya ekstensi file berikut yang diizinkan dalam paket simbol: .pdb, , .nuspec, .xml.psmdcp, .rels,.p7s
  • Hanya PDB Portabel terkelola yang didukung di server simbol NuGet.org.
  • PDB dan DLL .nupkg terkait perlu dibuat dengan pengkompilasi di Visual Studio versi 15.9 atau lebih tinggi (lihat hash kripto PDB)

Paket simbol yang diterbitkan ke NuGet.org akan gagal validasi jika batasan ini tidak terpenuhi.

Catatan

Proyek asli, seperti proyek C++, menghasilkan PDB Windows alih-alih PDB Portabel. Ini tidak didukung oleh server simbol NuGet.org. Silakan gunakan Paket Simbol Warisan sebagai gantinya.

Validasi dan pengindeksan paket simbol

Paket simbol yang diterbitkan ke NuGet.org menjalani beberapa validasi, termasuk pemindaian malware. Jika paket gagal dalam pemeriksaan validasi, halaman detail paketnya akan menampilkan pesan kesalahan. Selain itu, pemilik paket akan menerima email dengan instruksi tentang cara memperbaiki masalah yang diidentifikasi.

Ketika paket simbol telah melewati semua validasi, simbol akan diindeks oleh server simbol NuGet.org dan akan tersedia untuk dikonsumsi.

Validasi dan pengindeksan paket biasanya memakan waktu di bawah 15 menit. Jika penerbitan paket membutuhkan waktu lebih lama dari yang diharapkan, kunjungi status.nuget.org untuk memeriksa apakah NuGet.org mengalami gangguan. Jika semua sistem beroperasi dan paket belum berhasil diterbitkan dalam waktu satu jam, silakan masuk ke nuget.org dan hubungi kami menggunakan tautan Dukungan Kontak di halaman detail paket.

Struktur paket simbol

Paket simbol (.snupkg) memiliki karakteristik berikut:

  1. .snupkg memiliki id dan versi yang sama dengan paket NuGet yang sesuai (.nupkg).

  2. .snupkg memiliki struktur folder yang sama dengan .nupkg yang sesuai untuk file DLL atau EXE dengan perbedaan bahwa alih-alih DLL/EXEs, PDB yang sesuai akan disertakan dalam hierarki folder yang sama. File dan folder dengan ekstensi selain PDB akan dibiarkan keluar dari snupkg.

  3. File .nuspec paket simbol memiliki SymbolsPackage jenis paket:

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

  4. Jika penulis memutuskan untuk menggunakan nuspec kustom untuk membangun nupkg dan snupkg mereka, snupkg harus memiliki hierarki folder dan file yang sama yang dirinci dalam 2).

  5. Bidang berikut akan dikecualikan dari nuspec snupkg: authors, , owners, requireLicenseAcceptancelicense type, licenseUrl, dan icon.

  6. Jangan gunakan <license> elemen . .snupkg tercakup dalam lisensi yang sama dengan .nupkg yang sesuai.

Lihat juga

Pertimbangkan untuk menggunakan Tautan Sumber untuk mengaktifkan penelusuran kesalahan kode sumber rakitan .NET. Untuk informasi selengkapnya, silakan merujuk ke panduan Tautan Sumber.

Untuk informasi selengkapnya tentang paket simbol, silakan lihat spesifikasi desain Debugging Paket NuGet & Penyempurnaan Simbol.