Bagikan melalui

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

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

Panduan memulai cepat hanya untuk pengguna Windows. Jika Anda menggunakan Mac, gunakan .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 versi yang lebih baru secara otomatis menyertakan fitur NuGet saat Anda menginstal beban kerja yang terkait dengan .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. Sebaliknya, 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 bergaya 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).

  • Daftar untuk 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 >Proyek Baru>.

  2. Di jendela Membuat 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 Mengonfigurasi proyek baru Anda, masukkan AppLogger untuk Nama Proyek , kemudian pilih Berikutnya.

  5. Di jendela Informasi Tambahan, pilih kerangka kerjayang 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 panduan memulai cepat ini, Anda tidak perlu menulis kode tambahan apa pun untuk paket NuGet karena pustaka kelas templat sudah 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 nama proyek Project><> Properti, di mana nama proyek <> adalah nama proyek Anda.

  2. Perluas simpul 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), memigrasikan proyek, atau lihat Membuat dan menerbitkan paket .NET Framework untuk instruksi langkah demi langkah.

    Cuplikan layar memperlihatkan properti paket NuGet dalam proyek Visual Studio.

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

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

    Penting

    Anda harus memberikan identifikasi yang unik untuk paket di seluruh nuget.org atau host lain yang Anda gunakan. Jika tidak, kesalahan terjadi. Untuk mulai cepat ini, sebaiknya masukkan Sampel atau Uji dalam nama karena langkah penerbitan membuat paket terlihat secara publik.

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

    Tab AppLogger.csproj sedang 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 Active ke Release.

  2. Pilih proyek AppLogger di Solution Explorer, lalu pilih Pack.

    Visual Studio membangun proyek dan membuat file .nupkg.

  3. Periksa jendela Output untuk detailnya, yang berisi jalur ke file paket. Dalam contoh ini, rakitan yang dibangun berada di bin\Release\net6.0, sesuai dengan 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 Pack pada menu, proyek Anda mungkin bukan proyek bergaya SDK, dan Anda perlu menggunakan NuGet CLI. Anda dapat memigrasikan proyek dan menggunakan .NET CLI, atau lihat Membuat dan menerbitkan paket .NET Framework untuk petunjuk 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 nama proyek Project><> Properti, di mana nama proyek <> adalah nama proyek Anda (AppLogger dalam hal ini).

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

    Cuplikan layar memperlihatkan properti paket dengan Buat paket NuGet pada build dipilih.

Nota

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 target pack saat proyek berisi data paket yang diperlukan:

  1. Dengan proyek Anda terbuka di Solution Explorer, buka prompt perintah dengan memilih Tools>Command Line>Developer Command Prompt.

    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.

Nota

  • 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 jika Anda menghapusnya dari daftar. Untuk menghosting paket secara privat, lihat Hosting umpan NuGet Anda sendiri.

Memperoleh kunci API Anda

Sebelum Anda menerbitkan paket NuGet, buat kunci API:

  1. Masuk ke akun nuget.org Anda atau membuat 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 Pilih Paket>Pola Glob, masukkan *.

  6. Pilih Buat.

  7. Pilih Salin untuk menyalin kunci baru.

    Cuplikan layar yang menampilkan kunci API baru dengan tautan Salin.

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 mengunggah paket.

Scoping memungkinkan Anda membuat kunci API terpisah untuk berbagai tujuan. Setiap kunci memiliki jangka waktu kedaluwarsa, dan Anda dapat membatasi kunci ke paket tertentu atau pola glob. Anda juga membatasi setiap kunci ke operasi tertentu: Mengunggah paket dan versi paket baru, hanya mengunggah versi paket baru, atau menghapus dari 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 cakupan kunci API .

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.

Nota

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

Kesalahan penerbitan

Kesalahan dari perintah push biasanya menunjukkan masalah. 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. Misalkan, misalnya, pengidentifikasi AppLogger-test sudah ada di nuget.org. Jika Anda mencoba menerbitkan paket dengan pengidentifikasi tersebut, perintah push 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 mengalami kesalahan, itu menunjukkan bahwa pengidentifikasi paket sudah ada di host. Untuk memperbaiki kesalahan, ubah pengidentifikasi paket menjadi unik, bangun kembali proyek, buat ulang file .nupkg, dan coba lagi perintah push.

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.

Nota

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:

Cuplikan layar memperlihatkan pesan penerbitan yang ditampilkan saat Anda mengunggah paket ke 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 ini yang dibuat dengan pustaka kelas kosong), atau Anda memutuskan tidak ingin paket tersebut terlihat, Anda dapat menghapus dari daftar paket untuk menyembunyikannya dari hasil pencarian.

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

    Cuplikan layar yang memperlihatkan ikon Edit untuk daftar paket di nuget.org.

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

    Cuplikan layar yang memperlihatkan menghapus centang pada kotak Daftar untuk paket di nuget.org.

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

Nota

Untuk menghindari paket pengujian Anda ditayangkan di nuget.org, Anda dapat mengunggahnya ke situs pengujian nuget.org di https://int.nugettest.org. Perlu diperhatikan bahwa paket yang diunggah ke int.nugettest.org mungkin tidak disimpan secara permanen.

Menambahkan readme atau file lain

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

<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

Nota

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

Temukan video NuGet 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: