Baca dalam bahasa Inggris

Bagikan melalui


Panduan Implementasi NuGet Server

Dalam beberapa kasus, Anda mungkin ingin menerapkan umpan paket NuGet Anda sendiri. Ada banyak implementasi yang ada yang memungkinkan Anda untuk menghosting umpan Anda sendiri dengan berbagai cara, tetapi protokol antara perangkat lunak klien NuGet resmi dan umpan paket didokumenkan yang memungkinkan Anda untuk membangun implementasi umpan Anda sendiri dari awal.

Protokol berkembang dari waktu ke waktu dan panduan ini ditujukan kepada mereka yang ingin atau sudah menerapkan server paket NuGet.

Sejak rilis awal protokol NuGet V3 pada tahun 2015, NuGet telah berevolusi untuk memberikan pengalaman yang lebih kaya kepada pengembang, dan ini memerlukan repositori paket untuk melakukan pekerjaan tambahan untuk memberikan nilai tambahan konsumen paket mereka, di luar hanya mengesahkan metadata dari paket yang dihosting dan mengembalikan metadata dalam berbagai bentuk. Misalnya, titik akhir metadata pencarian dan paket berisi lebih dari sekadar metadata yang ditemukan dalam file nuspec nupkg.

Perhatikan bahwa panduan ini difokuskan pada protokol NuGet V3 karena protokol V2 pada dasarnya tidak terdokumentasi dan, sejak 2015, protokol yang direkomendasikan untuk klien NuGet dan komunikasi server adalah protokol V3. Untuk informasi selengkapnya, baca tentang penerapan versi protokol.

Kronologi

Untuk membantu penulis repositori NuGet yang ada mengikuti perkembangan fitur terbaru NuGet, berikut adalah kronologi fitur relevan yang disebutkan dalam sisa dokumen.

Bidang Pemilik

Pertimbangkan dua bidang <authors> file manifes paket (.nuspec), dan <owners>. Penulis paket yang mengemas konten pihak ketiga sering memasukkan nama pihak ketiga di <authors> bidang . Bidang <owners> ini dimaksudkan untuk menunjukkan siapa yang menerbitkan paket pada repositori, dan oleh karena itu siapa yang harus dihubungi jika terjadi masalah atau pertanyaan pengemasan.

Ini dijelaskan dalam posting blog dari 2013, sehingga <owners> bidang dianggap tidak digunakan lagi dalam .nuspec file. Jika manifes paket berisi metadata ini, manifes tersebut harus diabaikan. Jangan mengembalikan nilai .nuspec bidang file <owners> di owners properti dalam sumber daya pencarian atau respons JSON sumber daya metadata paket.

Jika repositori Anda memiliki izin per paket, disarankan untuk melaporkan akun yang memiliki izin untuk menerbitkan versi baru dalam owner metadata untuk respons JSON sumber daya metadata pencarian dan paket.

verified bidang respons pencarian

UI Manajer Paket Visual Studio menunjukkan tanda centang biru di samping paket dalam hasil layanan pencarian, saat bidang verified baru diatur ke true.

NuGet.org menggunakan ini dengan data awalan paket (data sisi server, bukan bagian dari API NuGet), sehingga tanda centang ini hanya ditampilkan kepada pelanggan ketika akun yang memiliki paket mengunggah paket. Misalnya, paket apa pun dengan awalan microsoft.* hanya diverifikasi ketika paket dimiliki oleh akun Microsoft di nuget.org. Siapa pun yang mengunggah paket dengan id paket yang dimulai dengan microsoft. sebelum awalan yang dipesan diimplementasikan, tidak akan memiliki tanda centang terverifikasi ini. NuGet.org juga memungkinkan prefiks tidak eksklusif, sehingga siapa pun dapat mengunggah paket di bawah Contoso.ToolWithPlugins.Community.*, tetapi tidak akan mendapatkan tanda centang terverifikasi.

Dukungan Semantic Versioning 2.0.0

NuGet mendukung hibrid antara System.Version dan Versi Semantik, tetapi dukungan untuk Semantic Versi 2.0.0 ditambahkan pada tahun 2017. Oleh karena itu, sumber daya NUGet API yang mengembalikan versi ke versi klien yang lebih rendah dari 3.6.0 tidak boleh mengembalikan paket yang menggunakan fitur Semantic 2.0.0 yang tidak kompatibel dengan Semantic Versioning 1.0.0.

Perbedaan terpenting antara kedua versi adalah label pra-rilis, dan string metadata. Spesifikasi Semantic Versioning 1.0.0 menyediakan [0-9A-Za-z-] sebagai contoh string Regex untuk satu-satunya karakter yang diizinkan sebagai bagian dari label pra-rilis, dan tidak mendukung string metadata. Spesifikasi Semantic Versioning 2.0.0 memungkinkan pengidentifikasi pra-rilis dipisahkan oleh . karakter (dan melarang pengidentifikasi numerik memiliki nol awal), dan juga memungkinkan metadata build ditambahkan mengikuti +.

Dalam sumber daya metadata paket (RegistrationsBaseUrl), versi sumber daya di bawah 3.6.0 hanya boleh mengembalikan paket yang sesuai dengan . NET atau System.Version Semantic Versioning 1.0.0. Ini berarti paket yang versinya hanya sesuai dengan Semantic Versioning 2.0.0 tidak terlihat oleh versi klien ini.

Demikian pula, layanan kueri pencarian (SearchQueryService) dan layanan lengkapi otomatis (SearchAutocompleteService) menambahkan &semVerLevel={version} parameter kueri. Ketika semVerLevel hilang, asumsikan nilai 1.0.0. Seperti sumber daya metadata paket, paket yang versinya hanya kompatibel dengan Semantic Versioning 2.0.0 tidak boleh dikembalikan ketika semVerLevel nilainya di bawah 2.0.0.

File yang disematkan

Ikon paket, lisensi, dan file readme dapat (dan disarankan untuk) disematkan dalam paket. File-file ini memerlukan titik akhir URL, baik diekstrak dan diletakkan di server file statis, atau URL yang secara dinamis mengekstrak file dari .nupkg sesuai permintaan, sehingga dapat dilihat tanpa mengunduh seluruh nupkg. Jika repositori paket Anda menyediakan detail paket penjelajahan dan tampilan paket, Anda dapat menggunakan URL untuk menampilkan konten yang disematkan kepada pelanggan di situs web Anda.

Terakhir, sumber daya metadata paket dan sumber daya pencarian harus berisi URL yang dihosting di iconUrlproperti , , licenseUrldan/atau readmeUrl respons JSON. Paket (.nupkg file) tidak boleh dimodifikasi, karena fitur klien (file kunci dan paket yang ditandatangani) akan mendeteksi modifikasi karena paket telah dirusak.

Perhatikan bahwa lisensi bisa berupa ekspresi SPDX, atau file yang disematkan (tetapi tidak keduanya). Paket yang menggunakan ekspresi lisensi, ketika diwakili dalam hasil metadata pencarian dan paket, dapat mengatur licenseUrl ke ekspresi lisensi, URL yang dikodekan, dan ditambahkan ke akhir https://licenses.nuget.org/. Contohnya, https://licenses.nuget.org/Apache-2.0. Tim server NuGet.org memiliki dokumentasi tambahan tentang licenses.nuget.org.

Data kerentanan dan penghentian yang diketahui

Sumber Daya Metadata Paket (RegistrationsBaseUrl)

Sumber Daya Metadata Paket dapat berisi informasi penghentian dan kerentanan. Ini memungkinkan pelanggan menelusuri paket di Antarmuka Pengguna Manajer Paket Visual Studio, atau yang setara di ID Lain, untuk diberi tahu tentang masalah keamanan atau pemeliharaan penting.

Jika repositori paket Anda adalah paket "up-sourcing" dari repositori lain, untuk mencerminkan paket di umpan Anda sendiri, sebaiknya periksa sumber asli secara berkala jika ada data penghentian atau kerentanan, dan cerminkan metadata tersebut di repositori Anda sendiri. Jika repositori paket Anda ditingkatkan sumbernya dari nuget.org secara khusus, dengan menjaga status terakhir kali Anda memeriksa ("kursor"), Anda dapat menggunakan Catalog sumber daya untuk memeriksa secara efisien apakah ada pembaruan paket untuk paket yang Anda cerminkan, tanpa harus mengunduh sejumlah besar file JSON metadata paket dari umpan upstream. Ada panduan tentang menggunakan sumber daya katalog dengan kode sampel yang dapat membantu Anda memulai.

Database Kerentanan yang Diketahui (VulnerabilityInfo)

Untuk menyediakan pemindaian kerentanan berkinerja tinggi selama pemulihan paket, NuGet mengunduh daftar lengkap kerentanan yang diketahui dari VulnerabilityInfo sumber daya. Nuget.org menyediakan data kerentanan untuk semua saran yang ditinjau GitHub dari database GitHub Advisories, yang mencakup paket yang tidak dihosting di nuget.org.

Jika repositori paket Anda menghosting paket pihak pertama, dan Anda ingin memberikan informasi kerentanan kepada pelanggan menggunakan umpan Anda sendiri, tetapi belum memiliki kerentanan paket yang diungkapkan, Anda harus memberikan indeks kerentanan dengan satu atau beberapa halaman kerentanan yang kontennya adalah array JSON kosong ([]).

Jika repositori paket Anda dimaksudkan untuk digunakan oleh aplikasi sebagai repositori default (bukan nuget.org), Anda dapat menggunakan data kerentanan nuget.org. Salah satu opsinya adalah menggunakan URL indeks kerentanan nuget.org dalam indeks layanan Anda. Opsi lain adalah memeriksa indeks nuget.org VulnerabilityInfo secara berkala, dan mengunduh halaman yang diubah untuk dicerminkan secara lokal.

packageTypes kueri pencarian

.NET CLI memungkinkan pencarian paket alat .NET dengan dotnet tool search perintah . Ini diimplementasikan dengan menambahkan &packageTypes={value} parameter kueri ke sumber daya kueri pencarian, yang membaca nilai dari bidang file <packageTypes> paket.nuspec.

Struktur URL untuk umpan terautentikasi

Seperti yang dijelaskan dalam gambaran umum NUGet API, URL awal untuk semua komunikasi server NuGet adalah indeks layanan. Dokumen ini berisi URL untuk semua sumber daya lain yang akan dikueri klien NuGet. Pada NuGet 6.7 (Visual Studio & MSBuild 17.7, dan .NET SDK 7.0.400), NuGet menggunakan . HttpClientHandler.PreAuthenticateNET , yang hanya menghindari permintaan HTTP anonim ketika URL berikutnya berada di direktori virtual yang sama, atau subdirektori, dari URL yang sebelumnya telah diautentikasi. Ini akan secara dramatis mengurangi jumlah permintaan HTTP yang tidak diautentikasi yang dikirim ke server, dan oleh karena itu akan mengurangi beban kerja server Anda.

Berikut adalah beberapa contoh:

URL Akankah PreAuthenticate?
https://pkgs.contoso.com/nuget/v3/feed/index.json N/A, ini adalah indeks layanan.
https://pkgs.contoso.com/nuget/v3/search Tidak, tidak dalam sub-direktori yang sama dengan indeks layanan.
https://search.pkgs.contoso.com/nuget/v3/feed/ Tidak, tidak pada nama host yang sama dengan indeks layanan.
https://pkgs.contoso.com/nuget/v3/feed/search Ya, dalam direktori yang sama dengan indeks layanan.
https://pkgs.contoso.com/nuget/v3/registration/ Tidak, tidak dalam subdirektori indeks layanan.
https://pkgs.contoso.com/nuget/v3/feed/registration/ Ya, dalam subdirektori indeks layanan.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/ Lihat di bawah ini

Dalam contoh terakhir, server mungkin memiliki nama kanonis (dalam contoh ini guid), dan memiliki satu atau beberapa alias. Jika permintaan indeks layanan diautentikasi pada URL non-kanonis (nama "ramah", dalam contoh feedkami ), maka tidak, permintaan apa pun ke sumber daya di bawah URL kanonis tidak akan cocok HttpClientHandlerdengan aturan untuk PreAuthenticate. Namun, jika URL non-kanonis adalah pengalihan HTTP ke URL kanonis, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonmaka URL ini akan digunakan dalam HttpClientHandlercache kredensial . Dalam hal ini, setiap permintaan ke indeks layanan akan memiliki latensi tambahan, karena pengalihan.

Meskipun API V3 NuGet dirancang untuk bekerja pada server file statis, sumber daya pencarian adalah pengecualian yang selalu memerlukan layanan web dinamis untuk memproses permintaan. Jika Anda ingin menghosting pencarian, atau memang sumber daya NUGet API lainnya, di server yang berbeda, untuk mendapatkan manfaat dari HttpClientHandler, PreAuthenticateAnda harus menggunakan proksi terbalik untuk memastikan semua URL yang dihadapi pelanggan dalam indeks layanan memenuhi aturan "sama atau subdirektori".