Memulihkan paket menggunakan Pemulihan Paket

  • Artikel
  • 10 menit untuk membaca

Untuk mempromosikan lingkungan pengembangan yang lebih bersih dan untuk mengurangi ukuran repositori, Pemulihan Paket NuGet menginstal semua dependensi proyek yang tercantum dalam file proyek atau packages.config. .NET Core 2.0+ dotnet build dan dotnet run perintah melakukan pemulihan paket otomatis. Visual Studio dapat memulihkan paket secara otomatis saat membangun proyek, dan Anda dapat memulihkan paket kapan saja melalui Visual Studio, nuget restore, dotnet restore, dan xbuild pada Mono.

Pemulihan Paket memastikan bahwa semua dependensi proyek tersedia, tanpa harus menyimpannya di kontrol sumber. Untuk mengonfigurasi repositori kontrol sumber Anda untuk mengecualikan biner paket, lihat Paket dan kontrol sumber.

Gambaran umum Pemulihan Paket

Pemulihan Paket terlebih dahulu menginstal dependensi langsung proyek sesuai kebutuhan, lalu menginstal dependensi apa pun dari paket tersebut di seluruh grafik dependensi.

Jika paket belum diinstal, NuGet terlebih dahulu mencoba mengambilnya dari cache. Jika paket tidak ada dalam cache, NuGet mencoba mengunduh paket dari semua sumber yang diaktifkan dalam daftar di Opsi Alat>Sumber>PaketNuGet Package Manager> di Visual Studio. Selama pemulihan, NuGet mengabaikan urutan sumber paket, dan menggunakan paket dari sumber mana pun yang pertama kali merespons permintaan. Untuk informasi selengkapnya tentang perilaku NuGet, lihat Konfigurasi NuGet umum.

Catatan

NuGet tidak menunjukkan kegagalan untuk memulihkan paket hingga semua sumber telah diperiksa. Pada saat itu, NuGet melaporkan kegagalan hanya untuk sumber terakhir dalam daftar. Kesalahan menyiratkan bahwa paket tidak ada di salah satu sumber lain, meskipun kesalahan tidak ditampilkan untuk masing-masing sumber tersebut satu per satu.

Pulihkan paket

Pemulihan Paket mencoba menginstal semua dependensi paket ke status yang benar yang cocok dengan referensi paket dalam file proyek Anda (.csproj) atau file packages.config Anda. (Dalam Visual Studio, referensi muncul di Penjelajah Solusi di bawah dependensi \ NuGet atau node Referensi.)

  1. Jika referensi paket dalam file proyek Anda benar, gunakan alat pilihan Anda untuk memulihkan paket.

    Jika paket mereferensikan dalam file proyek Anda (.csproj) atau file packages.config Anda salah (tidak cocok dengan status yang Anda inginkan setelah Pemulihan Paket), maka Anda perlu menginstal atau memperbarui paket sebagai gantinya.

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

  2. Setelah menjalankan Pemulihan Paket, jika Anda masih mengalami paket yang hilang atau kesalahan terkait paket (seperti ikon kesalahan di Penjelajah Solusi di Visual Studio), Anda mungkin perlu mengikuti instruksi yang dijelaskan dalam Memecahkan Masalah kesalahan Pemulihan Paket atau, atau, menginstal ulang dan memperbarui paket.

    Dalam Visual Studio, Package Manager Console menyediakan beberapa opsi fleksibel untuk menginstal ulang paket. Lihat Menggunakan Pembaruan Paket.

Memulihkan menggunakan Visual Studio

Dalam Visual Studio di Windows, baik:

  • Pulihkan paket secara otomatis, atau

  • Memulihkan paket secara manual

Memulihkan paket secara otomatis menggunakan Visual Studio

Pemulihan Paket terjadi secara otomatis saat Anda membuat proyek dari templat atau membangun proyek, tunduk pada opsi di Mengaktifkan dan menonaktifkan pemulihan paket. Di NuGet 4.0+, pemulihan juga terjadi secara otomatis ketika Anda membuat perubahan pada proyek gaya SDK (biasanya proyek .NET Core atau .NET Standard).

  1. Aktifkan pemulihan paket otomatis dengan memilihOpsi>Alat>Pengelola Paket NuGet, lalu pilih Periksa paket yang hilang secara otomatis selama build di Visual Studio di bawah Pemulihan Paket.

    Untuk proyek gaya non-SDK, Pertama-tama Anda harus memilih Izinkan NuGet mengunduh paket yang hilang untuk mengaktifkan opsi pemulihan otomatis.

  2. Bangun proyek.

    Jika satu atau beberapa paket individual masih belum diinstal dengan benar, Penjelajah Solusi menampilkan ikon kesalahan. Klik kanan dan pilih Kelola Paket NuGet, dan gunakan Pengelola Paket untuk menghapus instalan 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," aktifkan pemulihan otomatis. Untuk proyek yang lebih lama, lihat Juga Migrasi ke pemulihan paket otomatis. Lihat juga pemecahan masalah Pemulihan Paket.

Memulihkan paket secara manual menggunakan Visual Studio

  1. Aktifkan pemulihan paket dengan memilihOpsi>Alat>Pengelola Paket NuGet. Di bawah Opsi Pemulihan Paket , pilih Izinkan NuGet mengunduh paket yang hilang.

  2. Di Penjelajah Solusi, klik kanan solusi dan pilih Pulihkan Paket NuGet.

    Jika satu atau beberapa paket individual masih belum diinstal dengan benar, Penjelajah Solusi menampilkan ikon kesalahan. Klik kanan dan pilih Kelola Paket NuGet, lalu gunakan Pengelola Paket untuk menghapus instalan 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," aktifkan pemulihan otomatis. Untuk proyek yang lebih lama, lihat Juga Migrasi ke pemulihan paket otomatis. Lihat juga pemecahan masalah Pemulihan Paket.

Mengaktifkan dan menonaktifkan pemulihan paket di Visual Studio

Dalam Visual Studio, Anda mengontrol Pemulihan Paket terutama melaluiOpsi>Alat>Manajer Paket NuGet:

Control Package Restore through NuGet Package Manager options

  • Izinkan NuGet mengunduh paket yang hilang mengontrol semua bentuk pemulihan paket dengan mengubah packageRestore/enabled pengaturan di bagianNuGet.Config packageRestore file, di %AppData%\NuGet\ Windows, atau ~/.nuget/NuGet/ di Mac/Linux. Pengaturan ini juga memungkinkan perintah Pulihkan Paket NuGet pada menu konteks solusi di Visual Studio, .

    <configuration>
    <packageRestore>
        <!-- The 'enabled' key is True when the "Allow NuGet to download missing packages" checkbox is set.
             Clearing the box sets this to False, disabling command-line, automatic, and MSBuild-integrated restore. -->
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

    Catatan

    Untuk mengganti packageRestore/enabled pengaturan secara global, atur variabel lingkungan EnableNuGetPackageRestore dengan nilai True atau False sebelum meluncurkan Visual Studio atau memulai build.

  • Periksa paket yang hilang secara otomatis selama build di Visual Studio mengontrol pemulihan otomatis dengan mengubah packageRestore/automatic pengaturan di bagian packageRestore fileNuGet.Config. Ketika opsi ini diatur ke True, menjalankan build dari Visual Studio secara otomatis memulihkan paket yang hilang. Pengaturan ini tidak memengaruhi build yang dijalankan dari baris perintah MSBuild.

    ...
<configuration>
    <packageRestore>
        <!-- The 'automatic' key is set to True when the "Automatically check for missing packages during
             build in Visual Studio" checkbox is set. Clearing the box sets this to False and disables
             automatic restore. -->
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

Untuk mengaktifkan atau menonaktifkan Pemulihan Paket untuk semua pengguna di komputer, pengembang atau perusahaan dapat menambahkan pengaturan konfigurasi ke file global nuget.config . Global nuget.config berada dalam Windows di %ProgramData%\NuGet\Config, kadang-kadang di bawah folder Visual Studio tertentu \{IDE}\{Version}\{SKU}\ , 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 secara langsung di nuget.config, mulai ulang Visual Studio, sehingga kotak dialog Opsi memperlihatkan nilai saat ini.

Pilih format manajemen paket default

Control default package management format though NuGet Package Manager options

NuGet memiliki dua format di mana proyek dapat menggunakan paket: PackageReference dan packages.config. Format default dapat dipilih dari menu drop-down di bawah judul Manajemen Paket . Opsi untuk diminta ketika paket pertama diinstal dalam proyek juga tersedia.

Catatan

Jika proyek tidak mendukung kedua format manajemen paket, format manajemen paket yang digunakan akan menjadi yang kompatibel dengan proyek, dan oleh karena itu mungkin bukan default yang diatur dalam opsi. Selain itu, NuGet tidak akan meminta pemilihan pada penginstalan paket pertama, bahkan jika opsi dipilih di jendela opsi.

Jika Package Manager Console digunakan untuk menginstal paket pertama dalam proyek, NuGet tidak akan meminta pemilihan format, bahkan jika opsi dipilih di jendela opsi.

Memulihkan menggunakan CLI dotnet

Gunakan perintah pemulihan dotnet , yang memulihkan paket yang tercantum dalam file proyek (lihat PackageReference). Dengan .NET Core 2.0 dan yang lebih baru, pemulihan dilakukan secara otomatis dengan dotnet build dan dotnet run. Pada NuGet 4.0, ini menjalankan kode yang sama dengan nuget restore.

Seperti halnya perintah CLI lainnya dotnet , pertama-tama buka baris perintah dan beralih ke direktori yang berisi file proyek Anda.

Untuk memulihkan paket menggunakan dotnet restore:

dotnet restore

Penting

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

Memulihkan menggunakan CLI nuget.exe

Gunakan perintah pemulihan , yang mengunduh dan menginstal paket apa pun yang hilang dari folder paket .

Untuk proyek yang dimigrasikan ke PackageReference, gunakan msbuild -t:restore untuk memulihkan paket sebagai gantinya.

restore hanya menambahkan paket ke disk tetapi tidak mengubah dependensi proyek. Untuk memulihkan dependensi proyek, ubah packages.config, lalu gunakan restore perintah .

Seperti halnya perintah CLI lainnya nuget.exe , pertama-tama buka baris perintah dan beralih ke direktori yang berisi file proyek Anda.

Untuk memulihkan paket menggunakan restore:

nuget restore MySolution.sln

Penting

Perintah restore tidak mengubah file proyek atau packages.config. Untuk menambahkan dependensi, tambahkan paket melalui UI Pengelola Paket atau Konsol di Visual Studio, atau ubah packages.config lalu jalankan atau installrestore.

Memulihkan menggunakan MSBuild

Gunakan perintah msbuild -t:restore untuk memulihkan paket yang tercantum dalam file proyek (lihat PackageReference) dan dimulai dengan proyek MSBuild 16.5+. packages.config

Perintah ini hanya tersedia di NuGet 4.x+ dan MSBuild 15.1+, yang disertakan dengan Visual Studio 2017 dan versi yang lebih tinggi. Dimulai dengan MSBuild 16.5+, perintah ini juga dapat memulihkan packages.config proyek berbasis saat dijalankan dengan -p:RestorePackagesConfig=true.

  1. Buka perintah Pengembang (Di kotak Pencarian , ketik perintah Pengembang).

    Anda biasanya ingin memulai Perintah Pengembang untuk Visual Studio dari menu Mulai, karena akan dikonfigurasi dengan semua jalur yang diperlukan untuk MSBuild.

  2. Beralih ke folder yang berisi file proyek dan ketik perintah berikut.

    # Uses the project file in the current folder by default
msbuild -t:restore

  3. Ketik perintah berikut untuk membangun kembali proyek.

    msbuild

    Pastikan bahwa output MSBuild menunjukkan bahwa build berhasil diselesaikan.

Catatan

msbuild memiliki -restore sakelar yang akan menjalankan Restore, memuat ulang proyek, lalu membangun. Lihat Memulihkan dan membangun dengan satu perintah MSBuild.

# Will restore the project, then build, since build is the default target.
msbuild -restore

Memulihkan menggunakan Azure Pipelines

Saat Anda membuat definisi build di Azure Pipelines, sertakan tugas pemulihan NuGet atau pemulihan .NET Core dalam definisi sebelum tugas build apa pun. Beberapa templat build menyertakan tugas pemulihan secara default.

Memulihkan menggunakan Azure DevOps Server

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. Untuk versi TFS sebelumnya, Anda 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 dengan pemulihan

Ketika NuGet memulihkan paket melalui metode apa pun, NuGet mematuhi batasan apa pun yang Anda tentukan dalam packages.config atau file proyek:

  • Di packages.config, Anda dapat menentukan rentang versi di allowedVersion properti dependensi. Lihat Membatasi versi peningkatan untuk informasi selengkapnya. Contohnya:

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

  • Dalam file proyek, Anda dapat menggunakan PackageReference untuk menentukan rentang dependensi secara langsung. Contohnya:

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

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

Memaksa pemulihan dari sumber paket

Secara default, operasi pemulihan NuGet menggunakan paket dari folder paket global dan http-cache , yang dijelaskan dalam Mengelola paket global dan folder cache.

Untuk menghindari penggunaan folder paket global , lakukan salah satu hal berikut ini:

  • Hapus folder menggunakan nuget locals global-packages -clear atau dotnet nuget locals global-packages --clear.
  • Ubah sementara lokasi folder paket global sebelum operasi pemulihan, menggunakan salah satu metode berikut:
    • Atur variabel lingkungan NUGET_PACKAGES ke folder lain.
    • Buat NuGet.Config file yang mengatur globalPackagesFolder (jika menggunakan PackageReference) atau repositoryPath (jika menggunakan packages.config) ke folder lain. Untuk informasi selengkapnya, lihat pengaturan konfigurasi.
    • Hanya MSBuild: Tentukan folder lain dengan RestorePackagesPath properti .

Untuk menghindari penggunaan cache untuk sumber HTTP, lakukan salah satu hal berikut ini:

  • -NoCache Gunakan opsi dengan nuget restore, atau --no-cache opsi dengan dotnet restore. Opsi ini tidak memengaruhi operasi pemulihan melalui Pengelola Paket atau konsol Visual Studio.
  • Hapus cache 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.

Migrasi ke pemulihan paket otomatis (Visual Studio)

Untuk NuGet 2.6 dan yang lebih lama, pemulihan paket terintegrasi MSBuild sebelumnya didukung tetapi itu tidak lagi benar. (Biasanya diaktifkan dengan mengklik kanan solusi di Visual Studio dan memilih Aktifkan Pemulihan Paket NuGet). Jika proyek Anda menggunakan pemulihan paket terintegrasi MSBuild yang tidak digunakan lagi, silakan migrasikan ke pemulihan paket otomatis.

Proyek yang menggunakan pemulihan paket MSBuild-Integrated biasanya berisi folder .nuget dengan tiga file: NuGet.config, nuget.exe, dan NuGet.targets. Kehadiran file NuGet.targets menentukan apakah NuGet akan terus menggunakan pendekatan terintegrasi MSBuild, sehingga file ini harus dihapus selama migrasi.

Untuk bermigrasi ke pemulihan paket otomatis:

  1. Tutup Visual Studio.
  2. Hapus .nuget/nuget.exe dan .nuget/NuGet.targets.
  3. 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.

Pemecahan Masalah

Lihat Memecahkan masalah pemulihan paket.