Pulihkan paket dengan Pemulihan Paket NuGet

  • Artikel

Pemulihan Paket NuGet memulihkan semua dependensi proyek yang tercantum dalam file proyek atau file packages.config . Anda dapat memulihkan paket secara manual dengan nuget restore, , dotnet restoremsbuild -t:restore, atau melalui Visual Studio. Perintah dotnet build dan dotnet run secara otomatis memulihkan paket, dan Anda dapat mengonfigurasi Visual Studio untuk memulihkan paket secara otomatis saat membangun proyek.

Untuk mempromosikan lingkungan pengembangan yang lebih bersih dan untuk mengurangi ukuran repositori, Pemulihan Paket membuat semua dependensi proyek tersedia tanpa harus menyimpannya dalam kontrol sumber. Untuk mengonfigurasi repositori kontrol sumber Anda untuk mengecualikan biner paket, lihat Paket dan kontrol sumber.

Perilaku Pemulihan Paket

Pemulihan Paket mencoba menginstal semua dependensi paket ke status yang cocok <PackageReference>dengan s dalam file proyek, seperti .csproj, atau <package>s dalam file packages.config . Pemulihan Paket terlebih dahulu menginstal dependensi langsung proyek sesuai kebutuhan, lalu menginstal dependensi apa pun dari paket tersebut di seluruh grafik dependensi.

Jika paket yang diperlukan belum diinstal, NuGet terlebih dahulu mencoba mengambilnya dari paket global lokal atau folder cache HTTP. Jika paket tidak berada di folder lokal, NuGet mencoba mengunduhnya dari semua sumber yang dikonfigurasi di Visual Studio di Alat>Opsi>Sumber Paket Manajer>Paket NuGet.

Selama pemulihan, NuGet mengabaikan urutan sumber paket, dan menggunakan paket dari sumber pertama yang merespons permintaan. Jika pemulihan gagal, NuGet tidak menunjukkan kegagalan sampai setelah memeriksa semua sumber. NuGet kemudian melaporkan kegagalan hanya untuk sumber terakhir dalam daftar. Kesalahan menyiratkan bahwa paket tidak ada di salah satu sumber, meskipun tidak mencantumkan kegagalan lain satu per satu.

Untuk informasi selengkapnya tentang perilaku NuGet, lihat Konfigurasi NuGet Umum.

Memulihkan paket

Jika referensi paket dalam file proyek atau file packages.config Anda sudah benar, gunakan alat pilihan Anda untuk memulihkan paket:

Setelah pemulihan berhasil:

  • Untuk proyek yang menggunakan <PackageReference>, paket ada di folder paket global lokal, dan file obj/project.assets.json proyek dibuat ulang.
  • Untuk proyek yang menggunakan packages.config, paket muncul di folder paket proyek.
  • Proyek sekarang harus berhasil dibangun.

Jika paket mereferensikan dalam file proyek Anda atau file packages.config Anda salah dan tidak cocok dengan status yang Anda inginkan, instal atau perbarui paket yang benar alih-alih menggunakan Pemulihan Paket.

Jika Anda kehilangan paket atau kesalahan terkait paket setelah menjalankan Pemulihan Paket, seperti ikon kesalahan di Penjelajah Solusi, ikuti instruksi dalam Memecahkan Masalah kesalahan Pemulihan Paket, atau instal ulang atau perbarui paket. Di Visual Studio, Package Manager Console menyediakan beberapa opsi untuk menginstal ulang paket. Untuk informasi selengkapnya, lihat Menggunakan Package-Update.

Memulihkan paket di Visual Studio

Di Visual Studio di Windows, Anda dapat memulihkan paket secara otomatis atau manual. Pertama, konfigurasikan Pemulihan Paket melalui Opsi>Alat>Pengelola Paket NuGet.

Mengonfigurasi opsi Pemulihan Paket Visual Studio

Konfigurasikan opsi Pemulihan Paket berikut di Opsi>Alat>NuGet Package Manager>General.

Screenshot that shows the NuGet Package Manager options.

Perbolehkan NuGet mengunduh paket yang hilang

Pilih Izinkan NuGet mengunduh paket yang hilang untuk mengaktifkan pemulihan paket dan perintah Pulihkan Paket NuGet. Pilihan ini mengatur packageRestore/enabled pengaturan ke True di bagian packageRestore dari file NuGet.Config global, di %AppData%\Roaming\NuGet di Windows atau ~/.nuget/NuGet/ di Mac atau Linux.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Catatan

Untuk mengganti packageRestore/enabled pengaturan secara global, Anda dapat mengatur variabel lingkungan EnableNuGetPackageRestore ke True atau False sebelum membuka Visual Studio atau memulai build.

Untuk mengaktifkan atau menonaktifkan Pemulihan Paket untuk semua pengguna di komputer, Anda dapat menambahkan pengaturan konfigurasi ke file NuGet.Config global di Windows di %ProgramData%\NuGet\Config, terkadang di bawah folder IDE>\<Version>\<SKU> Visual Studio tertentu<, atau di Mac/Linux di ~/.local/share. Pengguna individual kemudian dapat secara selektif mengaktifkan pemulihan sesuai kebutuhan pada tingkat proyek. Untuk detail selengkapnya tentang cara NuGet memprioritaskan beberapa file konfigurasi, lihat Konfigurasi NuGet umum.

Penting

Jika Anda mengedit packageRestore pengaturan di NuGet.Config secara langsung, mulai ulang Visual Studio sehingga Opsi menampilkan nilai saat ini.

Secara otomatis memeriksa paket yang hilang selama build

Pilih Periksa paket yang hilang secara otomatis selama build di Visual Studio untuk memulihkan paket yang hilang secara otomatis saat Anda menjalankan build dari Visual Studio. Pengaturan ini tidak memengaruhi build yang dijalankan dari baris perintah MSBuild. Pilihan ini mengatur pengaturan ke True di bagian packageRestorefile NuGet.Config.packageRestore/automatic

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

Untuk proyek bergaya non-SDK, Anda harus memilih Izinkan NuGet mengunduh paket yang hilang serta Secara otomatis memeriksa paket yang hilang selama build di Visual Studio di Opsi untuk mengaktifkan pemulihan otomatis.

Pilih format manajemen paket default

NuGet memiliki dua format manajemen paket, PackageReference dan packages.config. Pilih format yang ingin Anda gunakan dari daftar dropdown di bawah Manajemen Paket. Anda juga dapat memilih apakah akan mengizinkan pemilihan format pada penginstalan paket pertama.

Catatan

  • Jika proyek tidak mendukung kedua format manajemen paket, NuGet menggunakan format manajemen paket yang kompatibel dengan proyek, yang mungkin bukan default yang Anda tetapkan dalam opsi. NuGet kemudian tidak akan meminta pilihan pada penginstalan pertama, bahkan jika Anda memilih opsi tersebut.

  • Jika Anda menggunakan Package Manager Console untuk menginstal paket pertama dalam proyek, NuGet tidak meminta pemilihan format, meskipun opsi tersebut dipilih di Opsi.

Memulihkan paket secara manual atau otomatis

Setelah mengaktifkan pemulihan paket di Opsi, Anda dapat mengklik kanan solusi di Penjelajah Solusi dan memilih Pulihkan Paket NuGet untuk memulihkan paket kapan saja.

Jika Anda mengaktifkan pemulihan otomatis di Opsi, Pemulihan Paket terjadi secara otomatis saat Anda membuat proyek dari templat atau membangun proyek. Untuk NuGet 4.0+, pemulihan juga terjadi secara otomatis saat Anda membuat perubahan pada proyek bergaya SDK.

Untuk proyek yang menggunakan <PackageReference>, Anda dapat melihat referensi paket di Visual Studio Penjelajah Solusi di bawah Paket Dependensi>. Paket yang tidak diinstal dengan benar saat Anda memulihkan atau menjalankan ikon kesalahan tampilan build secara manual di Penjelajah Solusi. Klik kanan proyek, pilih Kelola Paket NuGet, dan gunakan Manajer Paket NuGet untuk menghapus instalasi dan menginstal ulang paket yang terpengaruh. Untuk informasi selengkapnya, lihat Menginstal ulang dan memperbarui paket.

Jika Anda melihat kesalahan Proyek ini mereferensikan paket NuGet yang hilang di komputer ini, atau Satu atau beberapa paket NuGet perlu dipulihkan tetapi tidak bisa karena persetujuan belum diberikan, pastikan Anda mengaktifkan pemulihan otomatis. Untuk proyek lama, lihat Migrasi ke pemulihan paket otomatis. Lihat juga Pemecahan masalah kesalahan pemulihan paket.

Memulihkan dengan menggunakan dotnet CLI

Perintah pemulihan dotnet memulihkan paket yang dicantumkan file proyek dengan <PackageReference>. Untuk informasi selengkapnya, lihat PackageReference dalam file proyek.

.NET Core 2.0 dan yang lebih baru dotnet build dan dotnet run perintah memulihkan paket secara otomatis. Pada NuGet 4.0, dotnet restore menjalankan kode yang sama dengan nuget restore.

Untuk memulihkan paket dengan dotnet restore:

  1. Buka baris perintah dan beralih ke direktori yang memuat file proyek Anda.
  2. Jalankan dotnet restore.

Penting

Untuk menambahkan referensi paket yang hilang ke file proyek, gunakan paket penambahan dotnet, yang juga menjalankan restore.

Memulihkan dengan menggunakan NuGet CLI

Perintah pemulihan NuGet CLI mengunduh dan menginstal paket yang hilang. Perintah ini berfungsi pada proyek yang menggunakan PackageReference atau packages.config untuk referensi paket.

Seperti install, restore perintah hanya menambahkan paket ke disk, tetapi tidak mengubah file proyek atau packages.config. Untuk menambahkan dependensi proyek, gunakan UI atau Konsol Manajer Paket Visual Studio.

Untuk memulihkan paket, jalankan perintah berikut:

nuget restore <projectPath>

Perintah restore menggunakan file solusi atau file package.config di jalur proyek yang ditentukan.

Misalnya, untuk memulihkan semua paket untuk MySolution.sln di direktori saat ini, jalankan:

nuget restore MySolution.sln

Catatan

Untuk proyek gaya non-SDK yang menggunakan PackageReference, gunakan msbuild -t:restore untuk memulihkan paket sebagai gantinya.

Memulihkan dengan menggunakan MSBuild

Anda dapat menggunakan msbuild -t:restore untuk memulihkan paket di NuGet 4.x+ dan MSBuild 15.1+, yang disertakan dengan Visual Studio 2017 dan yang lebih tinggi.

Perintah ini memulihkan paket dalam proyek yang menggunakan PackageReference untuk referensi paket. Dimulai dengan MSBuild 16.5+, perintah juga mendukung referensi paket packages.config , ketika digunakan dengan -p:RestorePackagesConfig=true.

Untuk menggunakan pemulihan MSBuild:

  1. Buka Perintah Pengembang dengan mencari perintah pengembang dan memulai perintah dari menu Mulai Windows, yang mengonfigurasi semua jalur yang diperlukan untuk MSBuild.

  2. Beralih ke folder proyek, dan masukkan msbuild -t:restore.

  3. Setelah pemulihan selesai, masukkan msbuild untuk membangun kembali proyek. Pastikan output MSBuild menunjukkan bahwa build berhasil diselesaikan.

Catatan

Anda dapat menggunakan msbuild -restore untuk menjalankan restore, memuat ulang proyek, dan membangun, karena build adalah target default. Untuk informasi selengkapnya, lihat Memulihkan dan membangun dengan satu perintah MSBuild.

Memulihkan dengan Azure Pipelines atau Azure DevOps Server

Saat membuat definisi build di Azure Pipelines, Anda dapat menyertakan tugas pemulihan CLI NuGet atau pemulihan CLI dotnet dalam definisi sebelum tugas build apa pun. Beberapa templat build menyertakan tugas pemulihan secara default.

Azure DevOps Server dan TFS 2013 dan yang lebih baru secara otomatis memulihkan paket selama build, jika Anda menggunakan templat Team Build TFS 2013 atau yang lebih baru. Anda juga dapat menyertakan langkah build untuk menjalankan opsi pemulihan baris perintah, atau secara opsional memigrasikan templat build ke versi yang lebih baru. Untuk informasi selengkapnya, lihat Menyiapkan pemulihan paket dengan Team Foundation Build.

Membatasi versi paket

Pemulihan NuGet melalui metode apa pun mematuhi batasan versi apa pun yang Anda tentukan dalam packages.config atau file proyek.

  • Dalam packages.config, Anda dapat menentukan allowedVersions rentang dalam dependensi. Untuk informasi selengkapnya, lihat Batasan pada versi peningkatan. Contohnya:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • Dalam file proyek, Anda dapat menentukan rentang versi di Version properti dependensi. Contohnya:

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

Dalam kedua kasus, gunakan notasi yang dijelaskan dalam Penerapan versi paket.

Memaksa pemulihan dari sumber paket jarak jauh

Secara default, operasi pemulihan NuGet menggunakan paket dari paket global lokal dan folder http-cache, seperti yang dijelaskan dalam Mengelola paket global dan folder cache. Untuk menghindari penggunaan paket lokal ini, gunakan opsi berikut.

Untuk menghapus semua cache lokal:

  • Di Visual Studio, pilih tombol Hapus Semua Singgahan NuGet di Opsi Alat>NuGet>Package Manager>General.
  • Di CLI dotnet, gunakan dotnet nuget locals all --clear.
  • Di NuGet CLI, gunakan nuget locals all -clear.

Untuk menghindari penggunaan paket di folder paket global:

  • Hapus folder dengan menggunakan nuget locals global-packages -clear atau dotnet nuget locals global-packages --clear.
  • Atur variabel lingkungan NUGET_PACKAGES untuk sementara ke folder lain.
  • Buat file NuGet.Config yang diatur globalPackagesFolder untuk PackageReference, atau repositoryPath untuk packages.config, ke folder lain. Untuk informasi selengkapnya, lihat pengaturan konfigurasi.
  • Hanya untuk MSBuild, tentukan folder lain dengan RestorePackagesPath properti .

Untuk menghindari penggunaan paket di cache HTTP:

  • Hapus cache dengan menggunakan nuget locals http-cache -clear atau dotnet nuget locals http-cache --clear.
  • Atur variabel lingkungan NUGET_HTTP_CACHE_PATH untuk sementara ke folder lain.
  • Untuk nuget restore, gunakan -NoHttpCache opsi , atau untuk dotnet restore, gunakan --no-http-cache opsi . Opsi ini tidak memengaruhi operasi pemulihan melalui Manajer Paket Visual Studio atau Konsol.

Migrasi ke pemulihan paket otomatis

Versi NuGet yang lebih lama mendukung pemulihan paket terintegrasi MSBuild. Proyek yang menggunakan pemulihan paket terintegrasi MSBuild yang tidak digunakan lagi harus bermigrasi ke pemulihan paket otomatis.

Proyek-proyek ini biasanya berisi folder .nuget dengan tiga file: NuGet.config, nuget.exe, dan NuGet.targets. File NuGet.targets menyebabkan NuGet menggunakan pendekatan terintegrasi MSBuild, sehingga harus dihapus.

Untuk bermigrasi ke pemulihan paket otomatis:

  1. Aktifkan pemulihan paket otomatis.
  2. Tutup Visual Studio.
  3. Hapus .nuget/nuget.exe dan .nuget/NuGet.targets.
  4. Untuk setiap file proyek, hapus <RestorePackages> elemen , dan hapus referensi apa pun ke NuGet.targets.

Untuk menguji pemulihan paket otomatis:

  1. Hapus folder paket dari solusi.
  2. Buka solusi di Visual Studio dan mulai build. Pemulihan paket otomatis harus mengunduh dan menginstal setiap paket dependensi, tanpa menambahkannya ke kontrol sumber.

Langkah berikutnya