Pemetaan Sumber Paket

Pemetaan Sumber Paket adalah alat yang dapat digunakan untuk meningkatkan keamanan rantai pasokan Anda, terutama jika Anda menggunakan campuran sumber paket publik dan privat.

Secara default, NuGet akan mencari semua sumber paket yang dikonfigurasi ketika perlu mengunduh paket. Ketika paket ada di beberapa sumber, mungkin tidak deterministik sumber mana paket akan diunduh. Dengan Pemetaan Sumber Paket, Anda dapat memfilter, per paket, sumber mana yang akan dicari NuGet.

Kami juga memiliki saran untuk praktik terbaik lainnya untuk membantu Anda membentengi rantai pasokan Anda terhadap serangan.

Pemetaan Sumber Paket ditambahkan di NuGet 6.0. Dimulai dengan Visual Studio 17.5, Anda dapat menambahkan dan menghapus Pemetaan Sumber Paket dengan Dialog Opsi Visual Studio.

Dukungan Visual Studio

Visual Studio	Pemetaan Sumber Paket	Dukungan di Alat -> Opsi	Dukungan di antarmuka pengguna Manajer Paket
17.0 - 17.4	✅ Tersedia	❌ Tidak tersedia	❌ Tidak tersedia
17.5	✅ Tersedia	✅ Tersedia	❌ Tidak tersedia
17.7 Pratinjau 3	✅ Tersedia	✅ Tersedia	✅ Status ditampilkan

Fitur ini tersedia di semua alat terintegrasi NuGet.

• Visual Studio 2022 dan yang lebih baru
• .NET SDK 6.0.100 dan yang lebih baru
• nuget.exe 6.0.0 dan yang lebih baru

Alat yang lebih lama akan mengabaikan konfigurasi Pemetaan Sumber Paket. Untuk menggunakan fitur ini, pastikan semua lingkungan build Anda menggunakan versi alat yang kompatibel.

Pemetaan Sumber Paket akan berlaku untuk semua jenis proyek – termasuk .NET Framework – selama alat yang kompatibel digunakan.

Panduan video

Untuk gambaran umum berbasis video tentang fitur Pemetaan Sumber Paket, pertimbangkan untuk menonton video Mengamankan paket NuGet Anda dengan Pemetaan Sumber Paket di YouTube.

Mengaktifkan Pemetaan Sumber Paket

Untuk memilih fitur ini, Anda harus memiliki nuget.config file. Memiliki satu nuget.config di akar repositori Anda dianggap sebagai praktik terbaik. Lihat dokumentasi nuget.config untuk mempelajari lebih lanjut.

Aktifkan dengan menggunakan Dialog Opsi Visual Studio

1. Buka solusi Anda di Visual Studio.
2. Navigasi ke Package Source Mappings Dialog Opsi.

Dari antarmuka pengguna Manajer Paket

• Pilih paket dari daftar untuk memperlihatkannya di Panel Detail.
• Tekan tombol Configure untuk membuka halaman opsi Pemetaan Sumber Paket.

Dari Dialog Opsi Visual Studio

• Tools Buka menu di toolbar Visual Studio utama, dan pilih NuGet Package Manager ->Package Manager Settings.
• Navigasi ke Package Source Mappings halaman.

3. Tekan tombol Add di Package Source Mappings halaman untuk membuka Add Package Source Mappings dialog.

4. Masukkan ID Paket atau Pola Paket, dan pilih satu atau beberapa sumber paket dengan mengalihkan kotak centang untuk sumber yang Anda inginkan.

5. Halaman Package Source Mapping opsi akan menampilkan pemetaan sumber yang baru dibuat.

6. Tekan OK Dialog Opsi untuk menyimpan perubahan ke yang berlaku nuget.config.
7. Jendela Pengelola Paket NuGet akan menyegarkan dan mencerminkan status baru dari pemetaan sumber paket yang dipilih.

Aktifkan dengan mengedit secara manual nuget.config

• Nyatakan sumber paket yang Anda inginkan dalam file Anda nuget.config .
• Setelah deklarasi sumber Anda, tambahkan <packageSourceMapping> elemen yang menentukan pemetaan yang diinginkan untuk setiap sumber.
• Deklarasikan persis satu packageSource elemen untuk setiap sumber yang digunakan.
  • Tambahkan pola sebanyak yang Anda anggap perlu.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Pengaturan Pemetaan Sumber Paket diterapkan mengikuti aturan prioritas nuget.config saat beberapa nuget.config file di berbagai tingkat (tingkat komputer, tingkat pengguna, tingkat repo) ada.

Aturan Pemetaan Sumber Paket

Untuk fleksibilitas dan kontrol maksimum, NuGet mengharuskan semua paket cocok dengan pola paket melalui prioritas yang ditentukan dengan baik.

Persyaratan Pola Paket

Semua paket yang diminta harus dipetakan ke satu atau beberapa sumber dengan mencocokkan pola paket yang ditentukan. Dengan kata lain, setelah Anda menentukan packageSourceMapping elemen, Anda harus secara eksplisit menentukan sumber mana setiap paket - termasuk paket transitif - akan dipulihkan.

• Paket tingkat atas dan transitif harus cocok dengan pola yang ditentukan. Tidak ada persyaratan bahwa paket tingkat atas dan dependensinya berasal dari sumber yang sama.
• Pola ID yang sama dapat ditentukan pada beberapa sumber, memungkinkan ID paket yang cocok dipulihkan dari salah satu umpan yang menentukan pola. Namun, ini tidak disarankan karena dampak pada prediksi pemulihan (paket tertentu dapat berasal dari beberapa sumber). Ini mungkin konfigurasi yang valid jika Anda mempercayai semua sumber masing-masing.

Sintaks Pola Paket

Pola	Contoh sintaks	Deskripsi
Pola awalan paket	*, NuGet.*	Harus diakhir *dengan , di mana * cocok dengan 0 karakter atau lebih. * adalah pola awalan terpendek yang diizinkan dan cocok dengan semua id paket.
Pola ID paket	NuGet.Common, Contoso.Contracts	ID paket yang tepat.

Prioritas Pola Paket

Ketika beberapa pola unik cocok dengan ID paket, pola yang paling spesifik akan lebih disukai. Pola ID paket selalu memiliki prioritas tertinggi sementara generik * selalu memiliki prioritas terendah. Untuk pola awalan paket, yang terpanjang memiliki prioritas.

Mengatur sumber default

Pola * dapat digunakan untuk membuat deklarasikan sumber default de-facto - yang berarti paket apa pun yang tidak cocok dengan pola tertentu lainnya akan dipulihkan dari sumber tersebut tanpa melempar kesalahan. Konfigurasi ini menguntungkan jika Anda terutama menggunakan paket dari katakanlah, nuget.org, dan hanya memiliki beberapa paket internal, atau menggunakan awalan standar untuk semua paket internal seperti Contoso.*.

Jika tim Anda tidak menggunakan awalan standar untuk ID paket internal atau paket pemeriksaan nuget.org sebelum penginstalan, maka membuat sumber privat default akan sesuai dengan kebutuhan Anda dengan lebih baik.

Catatan

Ketika paket yang diminta sudah ada di folder paket global, tidak ada pencarian sumber yang akan terjadi dan pemetaan akan diabaikan. Pertimbangkan untuk mendeklarasikan folder paket global untuk repositori Anda untuk mendapatkan manfaat keamanan penuh dari fitur ini. Bekerja untuk meningkatkan pengalaman dengan folder paket global default yang direncanakan untuk iterasi berikutnya. Untuk mempelajari selengkapnya tentang cara kerja penginstalan paket, lihat dokumen konseptual.

Memulai

Ada 2 cara Anda dapat sepenuhnya onboarding repositori Anda, secara manual atau menggunakan alat NuGet.PackageSourceMapper.

Onboarding manual

Untuk onboarding manual, Anda dapat mengambil langkah-langkah berikut:

1. Deklarasikan folder paket global baru untuk repositori Anda.
2. Jalankan pemulihan dotnet untuk memulihkan dependensi.
3. Jalankan dotnet list package --include-transitive untuk melihat semua paket tingkat atas dan transitif dalam solusi Anda.
   • Untuk proyek kerangka kerja .NET menggunakan packages.config, packages.config file akan memiliki daftar datar semua paket langsung dan transitif.
4. Tentukan pemetaan singgah sehingga setiap ID paket dalam solusi Anda - termasuk paket transitif - cocok dengan pola untuk sumber target.
5. Jalankan dotnet nuget locals global-packages -c untuk menghapus direktori paket global.
6. Jalankan pemulihan untuk memvalidasi bahwa Anda telah mengonfigurasi pemetaan dengan benar. Jika pemetaan Anda tidak sepenuhnya mencakup setiap ID paket dalam solusi Anda, pesan kesalahan akan membantu Anda mengidentifikasi masalah.
7. Ketika pemulihan berhasil, Anda selesai! Secara opsional pertimbangkan:
   • Menyederhanakan konfigurasi menjadi lebih sedikit deklarasi dengan menggunakan awalan ID paket yang lebih luas atau mengatur sumber default jika memungkinkan.
   • Memverifikasi sumber tempat setiap paket dipulihkan dengan memeriksa file metadata di folder paket global atau meninjau log pemulihan.

Onboarding otomatis menggunakan alat

Banyak repositori memiliki sejumlah besar paket dan melakukan pekerjaan secara manual dapat memakan waktu. Alat NuGet.PackageSourceMapper dapat secara otomatis menghasilkan NuGet.config untuk Anda, berdasarkan paket dan sumber proyek Anda yang diketahui.

Alat pemeta sumber paket mengharuskan Anda untuk menyelesaikan pemulihan paket yang berhasil di mana ia akan membaca setiap file masing-masing .nupkg.metadata yang dihasilkan sebagai bagian dari build Anda untuk paling memahami bagaimana Anda memetakan paket dan sumber Anda masing-masing. Alat tidak hanya mencakup dependensi teratas, alat ini juga mempertimbangkan semua dependensi transitif saat menghasilkan pemetaan.

Alat ini memiliki beberapa opsi cara menghasilkan pola pemetaan tergantung pada kebutuhan Anda, silakan periksa posting blog dan instruksi readme alat untuk detail selengkapnya.

Untuk gambaran tentang bagaimana pemetaan sumber Anda mungkin terlihat, lihat repositori sampel kami.

Catatan

• Tidak ada perintah nuget.exe atau dotnet.exe untuk mengelola konfigurasi pemetaan sumber paket, lihat NuGet/Home#10735.
• Tidak ada cara untuk memetakan paket pada waktu penginstalan paket, lihat NuGet/Home#10730.
• Ada batasan saat menggunakan DotNetCoreCLI@2 tugas Azure Pipelines yang dapat dikerjakan dengan menggunakan feed- awalan dalam konfigurasi pemetaan sumber Anda. Namun disarankan untuk digunakan NuGetAuthenticate untuk kebutuhan autentikasi Anda dan memanggil cli dotnet langsung dari tugas skrip. Lihat microsoft/azure-pipelines-tasks#15542.