Bagikan melalui

Mulai cepat: Membuat dan menerbitkan paket NuGet menggunakan Visual Studio (hanya Windows)

  • Artikel

Dengan Microsoft Visual Studio, Anda dapat membuat paket NuGet dari pustaka kelas .NET, lalu menerbitkannya ke nuget.org menggunakan alat CLI.

Mulai cepat hanya untuk pengguna Windows. Jika Anda menggunakan Visual Studio untuk Mac, lihat Membuat paket NuGet dari proyek pustaka yang ada atau menggunakan .NET CLI.

Prasyarat

  • Instal Visual Studio 2022 untuk Windows dengan beban kerja terkait .NET Core.

    Anda dapat menginstal edisi Komunitas 2022 secara gratis dari visualstudio.microsoft.com, atau menggunakan edisi Profesional atau Perusahaan.

    Visual Studio 2017 dan yang lebih baru secara otomatis menyertakan kemampuan NuGet saat Anda menginstal . Beban kerja terkait NET.

  • Instal .NET CLI, jika belum diinstal.

    Untuk Visual Studio 2017 dan yang lebih baru, .NET CLI secara otomatis diinstal dengan beban kerja terkait .NET Core. Jika tidak, instal .NET Core SDK untuk mendapatkan .NET CLI. .NET CLI diperlukan untuk proyek .NET yang menggunakan format gaya SDK (atribut SDK). Templat pustaka kelas .NET default di Visual Studio 2017 dan yang lebih baru menggunakan atribut SDK.

    Penting

    Jika Anda bekerja dengan proyek gaya non-SDK, ikuti prosedur di Membuat dan menerbitkan paket .NET Framework (Visual Studio) sebagai gantinya untuk membuat dan menerbitkan paket. Untuk artikel ini, .NET CLI disarankan. Meskipun Anda dapat menerbitkan paket NuGet apa pun menggunakan NuGet CLI, beberapa langkah dalam artikel ini khusus untuk proyek bergaya SDK dan .NET CLI. NuGet CLI digunakan untuk proyek gaya non-SDK (biasanya .NET Framework).

  • Daftarkan akun gratis di nuget.org jika Anda belum memilikinya. Anda harus mendaftar dan mengonfirmasi akun sebelum dapat mengunggah paket NuGet.

  • Instal NuGet CLI dengan mengunduhnya dari nuget.org. Tambahkan file nuget.exe ke folder yang sesuai, dan tambahkan folder tersebut ke variabel lingkungan PATH Anda.

Membuat proyek pustaka kelas

Anda dapat menggunakan proyek Pustaka Kelas .NET yang sudah ada untuk kode yang ingin Anda paketkan, atau membuatnya sebagai berikut:

  1. Di Visual Studio, pilih File>Baru>Proyek.

  2. Di jendela Buat proyek baru, pilih C#, Windows, dan Pustaka di daftar dropdown.

  3. Dalam daftar templat proyek yang dihasilkan, pilih Pustaka Kelas (dengan deskripsi, Proyek untuk membuat pustaka kelas yang menargetkan .NET atau .NET Standard), lalu pilih Berikutnya.

  4. Di jendela Konfigurasikan proyek baru Anda, masukkan AppLogger untuk Nama proyek, lalu pilih Berikutnya.

  5. Di jendela Informasi tambahan, pilih Kerangka Kerja yang sesuai, lalu pilih Buat.

    Jika Anda tidak yakin kerangka kerja mana yang akan dipilih, yang terbaru adalah pilihan yang baik, dan dapat dengan mudah diubah nanti. Untuk informasi tentang kerangka kerja mana yang akan digunakan, lihat Kapan harus menargetkan .NET 5.0 atau .NET 6.0 vs. .NET Standard.

  6. Untuk memastikan proyek dibuat dengan benar, pilih Build>Build Solution. DLL ditemukan dalam folder Debug (atau Rilis jika Anda membangun konfigurasi tersebut sebagai gantinya).

  7. (Opsional) Untuk mulai cepat ini, Anda tidak perlu menulis kode tambahan apa pun untuk paket NuGet karena pustaka kelas templat cukup untuk membuat paket. Namun, jika Anda ingin beberapa kode fungsi untuk paket tersebut, sertakan kode berikut:

    namespace AppLogger
{
    public class Logger
    {
        public void Log(string text)
        {
            Console.WriteLine(text);
        }
    }
}

Mengonfigurasi properti paket

Setelah membuat proyek, Anda dapat mengonfigurasi properti paket NuGet dengan mengikuti langkah-langkah berikut:

  1. Pilih proyek Anda di Penjelajah Solusi, lalu pilih Properti nama> proyek proyek><, di mana <nama> proyek adalah nama proyek Anda.

  2. Perluas node Paket , lalu pilih Umum.

    Simpul Paket hanya muncul untuk proyek bergaya SDK di Visual Studio. Jika Anda menargetkan proyek gaya non-SDK (biasanya .NET Framework), migrasikan proyek, atau lihat Membuat dan menerbitkan paket .NET Framework untuk instruksi langkah demi langkah.

    Screenshot showing NuGet package properties in a Visual Studio project.

  3. Untuk paket yang dibangun untuk konsumsi publik, beri perhatian khusus pada properti Tag , karena tag membantu orang lain menemukan paket Anda dan memahami apa yang dilakukannya.

  4. Berikan PAKET Anda ID Paket unik dan isi properti lain yang diinginkan. Untuk tabel yang memperlihatkan bagaimana properti MSBuild (proyek bergaya SDK) memetakan ke properti file .nuspec , lihat target paket. Untuk deskripsi properti file .nuspec , lihat referensi file .nuspec. Semua properti ini masuk ke .nuspec manifes yang dibuat Visual Studio untuk proyek.

    Penting

    Anda harus memberi paket pengidentifikasi yang unik di seluruh nuget.org atau host apa pun yang Anda gunakan. Jika tidak, akan terjadi kesalahan. Untuk mulai cepat ini, sebaiknya masukkan Sampel atau Uji dalam nama karena langkah penerbitan membuat paket terlihat secara publik.

  5. (Opsional) Untuk melihat properti langsung di file proyek AppLogger.csproj, pilih File Proyek Edit Proyek>.

    Tab AppLogger.csproj dimuat.

    Opsi ini tersedia mulai dari Visual Studio 2017 untuk proyek yang menggunakan atribut gaya SDK. Untuk versi Visual Studio sebelumnya, Anda harus memilih Project>Unload Project sebelum dapat mengedit file proyek.

Jalankan perintah paket

Untuk membuat paket NuGet dari proyek Anda, ikuti langkah-langkah berikut:

  1. Pilih Build>Configuration Manager, lalu atur konfigurasi solusi Aktif ke Rilis.

  2. Pilih proyek AppLogger di Penjelajah Solusi, lalu pilih Kemas.

    Visual Studio membangun proyek dan membuat file .nupkg .

  3. Periksa jendela Output untuk detailnya, yang berisi jalur ke file paket. Dalam contoh ini, rakitan bawaan berada di bin\Release\net6.0 sebagai befits target .NET 6.0:

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

  4. Jika Anda tidak melihat perintah Kemas pada menu, proyek Anda mungkin bukan proyek bergaya SDK, dan Anda perlu menggunakan NuGet CLI. Migrasikan proyek dan gunakan .NET CLI, atau lihat Membuat dan menerbitkan paket .NET Framework untuk instruksi langkah demi langkah.

(Opsional) Hasilkan paket pada build

Anda dapat mengonfigurasi Visual Studio untuk membuat paket NuGet secara otomatis saat membuat proyek:

  1. Pilih proyek Anda di Penjelajah Solusi, lalu pilih Properti nama> proyek proyek><, di mana <nama> proyek adalah nama proyek Anda (AppLogger dalam hal ini).

  2. Perluas node Paket , pilih Umum, lalu pilih Hasilkan paket NuGet pada build.

    Screenshot showing package properties with Generate NuGet package on build selected.

Catatan

Ketika Anda secara otomatis menghasilkan paket, waktu tambahan untuk mengemas meningkatkan waktu build keseluruhan untuk proyek Anda.

(Opsional) Paket dengan MSBuild

Sebagai alternatif untuk menggunakan perintah menu Paket , NuGet 4.x+ dan MSBuild 15.1+ mendukung pack target ketika proyek berisi data paket yang diperlukan:

  1. Dengan proyek Anda terbuka di Penjelajah Solusi, buka prompt perintah dengan memilih Prompt Perintah Pengembang Baris>Perintah Alat.>

    Prompt perintah terbuka di direktori proyek Anda.

  2. Jalankan perintah berikut: msbuild -t:pack.

Untuk informasi selengkapnya, lihat Membuat paket menggunakan MSBuild.

Menerbitkan paket

Setelah Anda membuat file .nupkg , terbitkan ke nuget.org dengan menggunakan .NET CLI atau NuGet CLI, bersama dengan kunci API yang diperoleh dari nuget.org.

Catatan

  • Nuget.org memindai semua paket yang diunggah untuk virus dan menolak paket jika menemukan virus. Nuget.org juga memindai semua paket terdaftar yang ada secara berkala.

  • Paket yang Anda terbitkan ke nuget.org dapat dilihat secara publik oleh pengembang lain kecuali Anda membatalkannya. Untuk menghosting paket secara privat, lihat Menghosting umpan NuGet Anda sendiri.

Memperoleh kunci API Anda

Sebelum Anda menerbitkan paket NuGet, buat kunci API:

  1. Masuk ke akun nuget.org Anda atau buat akun jika Anda belum memilikinya.

  2. Pilih nama pengguna Anda di kanan atas, lalu pilih Kunci API.

  3. Pilih Buat, dan berikan nama untuk kunci Anda.

  4. Di bawah Pilih Cakupan, pilih Dorong.

  5. Di bawah Pilih Pola Glob Paket>, masukkan *.

  6. Pilih Buat.

  7. Pilih Salin untuk menyalin kunci baru.

    Screenshot that shows the new API key with the Copy link.

Penting

  • Selalu rahasiakan kunci API Anda. Kunci API seperti kata sandi yang memungkinkan siapa pun mengelola paket atas nama Anda. Hapus atau regenerasi kunci API Anda jika tidak sengaja terungkap.
  • Simpan kunci Anda di lokasi yang aman, karena Anda tidak dapat menyalin kunci lagi nanti. Jika Anda kembali ke halaman kunci API, Anda perlu meregenerasi kunci untuk menyalinnya. Anda juga dapat menghapus kunci API jika Anda tidak ingin lagi mendorong paket.

Cakupan memungkinkan Anda membuat kunci API terpisah untuk tujuan yang berbeda. Setiap kunci memiliki jangka waktu kedaluwarsa, dan Anda dapat mencakup kunci ke paket atau pola glob tertentu. Anda juga mencakup setiap kunci ke operasi tertentu: Mendorong paket dan versi paket baru, hanya mendorong versi paket baru, atau membatalkan daftar.

Melalui cakupan, Anda dapat membuat kunci API untuk orang yang berbeda yang mengelola paket untuk organisasi Anda sehingga mereka hanya memiliki izin yang mereka butuhkan.

Untuk informasi selengkapnya, lihat kunci API cakupan.

Terbitkan dengan CLI .NET atau NuGet CLI

Setiap alat CLI berikut memungkinkan Anda untuk mendorong paket ke server dan menerbitkannya. Pilih tab untuk alat CLI Anda, baik .NET CLI atau NuGet CLI.

Menggunakan .NET CLI (dotnet.exe) adalah alternatif yang direkomendasikan untuk menggunakan NuGet CLI.

Dari folder yang berisi file .nupkg , jalankan perintah berikut. Tentukan nama file .nupkg Anda, dan ganti nilai kunci dengan kunci API Anda.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

Output menunjukkan hasil proses penerbitan:

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Untuk informasi selengkapnya, lihat dotnet nuget push.

Catatan

Jika Anda ingin menghindari paket pengujian Anda ditayangkan di nuget.org, Anda dapat mendorong ke situs pengujian nuget.org di https://int.nugettest.org. Perhatikan bahwa paket yang diunggah ke int.nugettest.org mungkin tidak dipertahankan.

Kesalahan penerbitan

Kesalahan dari push perintah biasanya menunjukkan masalahnya. Misalnya, Anda mungkin lupa memperbarui nomor versi di proyek Anda, jadi Anda mencoba menerbitkan paket yang sudah ada.

Anda juga melihat kesalahan jika kunci API Anda tidak valid atau kedaluwarsa, atau jika Anda mencoba menerbitkan paket menggunakan pengidentifikasi yang sudah ada di host. Misalnya, misalnya, pengidentifikasi AppLogger-test sudah ada di nuget.org. Jika Anda mencoba menerbitkan paket dengan pengidentifikasi tersebut push , perintah memberikan kesalahan berikut:

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

Jika Anda mendapatkan kesalahan ini, periksa apakah Anda menggunakan kunci API yang valid yang belum kedaluwarsa. Jika anda, kesalahan menunjukkan pengidentifikasi paket sudah ada di host. Untuk memperbaiki kesalahan, ubah pengidentifikasi paket menjadi unik, bangun kembali proyek, buat ulang file .nupkg , dan coba push lagi perintah .

Mengelola paket yang diterbitkan

Ketika paket Anda berhasil diterbitkan, Anda menerima email konfirmasi. Untuk melihat paket yang baru saja Anda terbitkan, pada nuget.org, pilih nama pengguna Anda di kanan atas, lalu pilih Kelola Paket.

Catatan

Mungkin perlu beberapa saat agar paket Anda diindeks dan muncul di hasil pencarian di mana orang lain dapat menemukannya. Selama waktu tersebut, paket Anda muncul di bawah Paket Tidak Tercantum, dan halaman paket memperlihatkan pesan berikut:

Screenshot showing the publishing message that's displayed when you upload a package to nuget.org.

Anda sekarang telah menerbitkan paket NuGet untuk nuget.org yang dapat digunakan pengembang lain dalam proyek mereka.

Jika Anda telah membuat paket yang tidak berguna (seperti paket sampel yang dibuat dengan pustaka kelas kosong), atau Anda memutuskan tidak ingin paket terlihat, Anda dapat membatalkan daftar paket untuk menyembunyikannya dari hasil pencarian:

  1. Setelah paket muncul di bawah Paket yang Diterbitkan pada halaman Kelola Paket, pilih ikon pensil di samping daftar paket.

    Screenshot that shows the Edit icon for a package listing on nuget.org.

  2. Pada halaman berikutnya, pilih Daftar, batal pilih kotak centang Daftar di hasil pencarian, lalu pilih Simpan.

    Screenshot that shows clearing the List checkbox for a package on nuget.org.

Paket sekarang muncul di bawah Paket Tidak Tercantum di Kelola Paket dan tidak lagi muncul di hasil pencarian.

Catatan

Untuk menghindari paket pengujian Anda ditayangkan di nuget.org, Anda dapat mendorong ke situs pengujian nuget.org di https://int.nugettest.org. Perhatikan bahwa paket yang diunggah ke int.nugettest.org mungkin tidak dipertahankan.

Menambahkan readme atau file lain

Untuk menentukan file secara langsung yang akan disertakan dalam paket, edit file proyek dan tambahkan content properti :

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

Dalam contoh ini, properti menentukan file bernama readme.txt di akar proyek. Visual Studio menampilkan konten file tersebut sebagai teks biasa segera setelah menginstal paket. File Readme tidak ditampilkan untuk paket yang diinstal sebagai dependensi. Misalnya, berikut adalah readme untuk paket HtmlAgilityPack:

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. 
7 This is normally found at 
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client 
9 or 
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. 
14 This is normally found at 
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client 
16 or 
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Catatan

Jika Anda hanya menambahkan readme.txt di akar proyek tanpa menyertakannya di content properti file proyek, itu tidak akan disertakan dalam paket.

Temukan video NuGet lainnya di Channel 9 dan YouTube.

Selamat membuat paket NuGet dengan menggunakan pustaka kelas Visual Studio .NET. Lanjutkan ke artikel berikutnya untuk mempelajari cara membuat paket NuGet dengan Visual Studio .NET Framework.

Membuat paket menggunakan NuGet CLI

Untuk menjelajahi selengkapnya yang ditawarkan NuGet, lihat artikel berikut ini: