Mulai cepat: Membuat dan menerbitkan paket menggunakan Visual Studio (.NET Framework, Windows)

  • Artikel

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

Mulai cepat hanya untuk pengguna Windows. Jika Anda menggunakan Visual Studio untuk Mac, lihat alat CLI dotnet sebagai gantinya.

Prasyarat

  • Instal Visual Studio 2022 untuk Windows dengan apa pun . Beban kerja terkait NET.

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

    Visual Studio 2017 dan yang lebih tinggi secara otomatis menyertakan kemampuan NuGet saat beban kerja .NET diinstal.

  • 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

Untuk membuat proyek pustaka kelas, ikuti langkah-langkah 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 (.NET Framework), lalu pilih Berikutnya.

  4. Di jendela Konfigurasikan proyek baru Anda, masukkan AppLogger untuk nama Proyek, lalu pilih Buat.

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

  6. (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 sampel ini, sertakan kode berikut:

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

    Dalam paket NuGet dunia nyata, Anda mungkin akan mengimplementasikan banyak fitur berguna yang dapat digunakan orang lain untuk membangun aplikasi. Anda juga dapat mengatur kerangka kerja target. Misalnya, lihat UWP dan Xamarin.

Mengonfigurasi properti proyek untuk paket

Paket NuGet menyertakan manifes ( .nuspec file), yang berisi metadata yang relevan seperti pengidentifikasi paket, nomor versi, deskripsi, dan lainnya. Beberapa metadata ini dapat diambil dari properti proyek secara langsung, yang menghindari harus memperbaruinya secara terpisah dalam proyek dan manifes. Langkah-langkah berikut menjelaskan cara mengatur properti yang berlaku:

  1. Pilih Properti Proyek>, lalu pilih tab Aplikasi.

  2. Untuk Nama assembly, beri paket Anda pengidentifikasi unik. Jika Anda mencoba menerbitkan paket dengan nama yang sudah ada, Anda akan melihat kesalahan.

    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.

  3. Pilih Informasi Rakitan, yang menampilkan kotak dialog tempat Anda bisa memasukkan properti lain yang dibawa ke dalam manifes (lihat Token pengganti). Bidang yang paling umum digunakan adalah versi Judul, Deskripsi, Perusahaan, Hak Cipta, dan Rakitan. Karena properti ini muncul dengan paket Anda di host seperti nuget.org setelah Anda menerbitkannya, pastikan properti tersebut sepenuhnya deskriptif.

    Screenshot showing the Assembly Information page in a .NET Framework project in Visual Studio.

  4. (Opsional) Untuk melihat dan mengedit properti secara langsung, buka file Properti/AssemblyInfo.cs dalam proyek dengan memilih Pilih Proyek>Edit File Proyek.

  5. Setelah Anda mengatur properti ini, atur konfigurasi solusi Aktif di Build>Configuration Manager ke Rilis dan bangun kembali proyek untuk menghasilkan DLL yang diperbarui.

Hasilkan manifes awal

Setelah Anda mengatur properti proyek dan membuat DLL, Anda sekarang dapat membuat file .nuspec awal dari proyek. Langkah ini mencakup token pengganti yang relevan untuk menarik informasi dari file proyek.

Jalankan nuget spec hanya sekali untuk menghasilkan manifes awal. Jika Anda memperbarui paket, ubah nilai dalam proyek Anda, atau edit manifes secara langsung:

  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 Tempat AppLogger.csproj file berada.

  2. Jalankan perintah berikut: nuget spec AppLogger.csproj.

    NuGet membuat manifes yang cocok dengan nama proyek, dalam hal AppLogger.nuspecini . Ini juga mencakup token penggantian dalam manifes.

  3. Buka AppLogger.nuspec di editor teks untuk memeriksa kontennya, yang akan mirip dengan kode berikut:

    <?xml version="1.0"?>
<package >
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>Your username</authors>
    <owners>Your username</owners>
    <license type="expression">MIT</license>
    <!-- <icon>icon.png</icon> -->
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2022</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

Mengedit manifes

  1. Edit properti berikut sebelum melanjutkan. Jika tidak, jika Anda mencoba membuat paket NuGet dengan nilai default dalam file Anda .nuspec , kesalahan terjadi. Untuk informasi tentang properti ini, lihat Elemen metadata opsional:

    • licenseUrl
    • projectUrl
    • releaseNotes
    • tag

  2. 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.

  3. Anda juga dapat menambahkan elemen lain ke manifes saat ini, seperti yang dijelaskan dalam referensi file .nuspec.

  4. Simpan file sebelum melanjutkan.

Jalankan perintah paket

  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: nuget pack.

    NuGet menghasilkan file .nupkg dalam bentuk identifier.version.nupkg di folder saat ini.

Menerbitkan paket

Setelah Anda membuat file .nupkg , terbitkan ke nuget.org dengan menggunakan NuGet CLI dengan kunci API yang diperoleh dari nuget.org. Untuk nuget.org, Anda harus menggunakan nuget.exe 4.1.0 atau yang lebih tinggi.

Jika Anda ingin menguji dan memvalidasi paket sebelum menerbitkannya galeri publik, Anda dapat mengunggahnya ke lingkungan pengujian seperti int.nugettest.org alih-alih nuget.org. Perhatikan bahwa paket yang diunggah ke int.nugettest.org mungkin tidak dipertahankan.

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

  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.

Menerbitkan dengan NuGet CLI

Menggunakan NuGet CLI (nuget.exe) adalah alternatif untuk menggunakan .NET CLI:

  1. Buka perintah dan ubah ke folder yang berisi file .nupkg .

  2. Jalankan perintah berikut. Ganti <nama> file paket dengan nama file paket Anda dan ganti <nilai> kunci api dengan kunci API Anda. Nama file paket adalah perangkaian ID paket dan nomor versi Anda dengan ekstensi .nupkg . Misalnya, AppLogger.1.0.0.nupkg:

    nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json

    Hasil proses penerbitan ditampilkan sebagai berikut:

    Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
    PUT https://www.nuget.org/api/v2/package/
    Created https://www.nuget.org/api/v2/package/ 6829ms
Your package was pushed.

Untuk informasi selengkapnya, lihat dorongan nuget.

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.

Langkah berikutnya

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

Membuat paket menggunakan NuGet CLI

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