Membuat paket NuGet dengan dotnet CLI

Paket NuGet berisi kode yang dapat digunakan kembali pengembang dalam proyek mereka. Tidak peduli apa yang dilakukan atau berisi kode Anda, Anda menggunakan alat baris perintah, baik nuget.exe atau dotnet.exe, untuk membuat paket NuGet.

Artikel ini menjelaskan cara membuat paket dengan menggunakan CLI dotnet. Mulai visual Studio 2017, CLI dotnet disertakan dengan semua beban kerja .NET dan .NET Core. Jika Anda perlu menginstal CLI dotnet atau alat klien NuGet lainnya, lihat Menginstal alat klien NuGet.

Topik ini hanya berlaku untuk .NET dan proyek lain yang menggunakan format gaya SDK. Untuk proyek-proyek ini, NuGet menggunakan informasi dari file proyek untuk membuat paket. Untuk tutorial mulai cepat, lihat Membuat paket dengan CLI dotnet atau Membuat paket dengan Visual Studio.

Perintah MSBuild msbuild -t:pack secara fungsional setara dengan paket dotnet. Untuk informasi selengkapnya tentang membuat paket dengan MSBuild, lihat Membuat paket NuGet menggunakan MSBuild.

Catatan

• Untuk membuat dan menerbitkan paket untuk proyek gaya non-SDK, biasanya proyek .NET Framework, lihat Membuat paket menggunakan nuget.exe CLI atau Membuat dan menerbitkan paket menggunakan Visual Studio (.NET Framework).

• Untuk proyek yang dimigrasikan dari packages.config ke PackageReference, gunakan msbuild -t:pack. Untuk informasi selengkapnya, lihat Membuat paket setelah migrasi.

Mengatur properti

Anda dapat membuat contoh proyek pustaka kelas dengan menggunakan dotnet new classlib perintah , dan mengemas proyek dengan menggunakan dotnet pack. Perintah dotnet pack menggunakan properti berikut. Jika Anda tidak menentukan nilai dalam file proyek, perintah menggunakan nilai default.

• PackageId, pengidentifikasi paket, harus unik di seluruh nuget.org dan target lain yang menghosting paket. Jika Anda tidak menentukan nilai, perintah menggunakan AssemblyName.
• Version adalah nomor versi tertentu dalam formulir Major.Minor.Patch[-Suffix], di mana -Suffix mengidentifikasi versi prarilis. Jika tidak ditentukan, nilai defaultnya adalah 1.0.0.
• Authors adalah penulis paket. Jika tidak ditentukan, nilai defaultnya adalah AssemblyName.
• Company adalah informasi perusahaan. Jika tidak ditentukan, nilai defaultnya adalah Authors nilainya.
• Product adalah informasi produk. Jika tidak ditentukan, nilai defaultnya adalah AssemblyName.

Di Visual Studio, Anda dapat mengatur nilai-nilai ini di properti proyek. Klik kanan proyek di Penjelajah Solusi, pilih Properti, lalu pilih bagian Paket. Anda juga dapat menambahkan properti langsung ke .csproj atau file proyek lainnya.

Contoh berikut menunjukkan file proyek dengan properti paket ditambahkan.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Anda dapat menambahkan properti opsional lainnya, seperti Title, , PackageDescriptiondan PackageTags.

Catatan

Untuk paket yang Anda bangun untuk konsumsi publik, beri perhatian khusus pada PackageTags properti. Tag membantu orang lain menemukan paket Anda dan memahami apa yang dilakukannya.

Perintah dotnet pack secara otomatis mengonversi PackageReferences dalam file proyek Anda menjadi dependensi dalam paket yang dibuat. Anda dapat mengontrol aset mana yang akan disertakan IncludeAssetsmelalui tag , ExcludeAssets dan PrivateAssets . Untuk informasi selengkapnya, lihat Mengontrol aset dependensi.

Untuk informasi selengkapnya tentang dependensi, properti opsional, dan penerapan versi, lihat:

• Referensi paket dalam file proyek
• Penerapan versi paket
• Properti metadata NuGet
• Target paket MSBuild

Pilih pengidentifikasi paket unik dan atur nomor versi

Pengidentifikasi paket dan nomor versi secara unik mengidentifikasi kode yang tepat yang terkandung dalam paket.

Ikuti praktik terbaik ini untuk membuat pengidentifikasi paket:

• Pengidentifikasi harus unik di seluruh nuget.org dan semua lokasi lain yang menghosting paket. Untuk menghindari konflik, pola yang baik adalah menggunakan nama perusahaan Anda sebagai bagian pertama dari pengidentifikasi.

• Ikuti konvensi penamaan seperti namespace layanan .NET, menggunakan notasi titik. Misalnya, gunakan Contoso.Utility.UsefulStuff daripada Contoso-Utility-UsefulStuff atau Contoso_Utility_UsefulStuff. Ini juga berguna bagi konsumen jika Anda mencocokkan pengidentifikasi paket dengan namespace yang digunakan kode.

• Jika Anda menghasilkan paket kode sampel yang menunjukkan cara menggunakan paket lain, tambahkan .Sample ke pengidentifikasi, seperti dalam Contoso.Utility.UsefulStuff.Sample.

  Paket sampel memiliki dependensi pada paket asli. Saat Anda membuat paket sampel, tambahkan <IncludeAssets> dengan contentFiles nilai . Di folder konten, atur kode sampel dalam folder bernama \Samples\<identifier>, seperti \Samples\Contoso.Utility.UsefulStuff.Sample.

Ikuti praktik terbaik ini untuk mengatur versi paket:

• Secara umum, atur versi paket agar sesuai dengan versi proyek atau rakitan, meskipun ini tidak benar-benar diperlukan. Mencocokkan versinya sederhana ketika Anda membatasi paket ke satu rakitan. NuGet sendiri berurusan dengan versi paket saat menyelesaikan dependensi, bukan versi perakitan.

• Jika Anda menggunakan skema versi non-standar, pastikan untuk mempertimbangkan aturan penerapan versi NuGet seperti yang dijelaskan dalam Penerapan versi paket. NuGet sebagian besar mematuhi Penerapan Versi Semantik 2.0.0.

Catatan

Untuk informasi selengkapnya tentang resolusi dependensi, lihat Resolusi dependensi dengan PackageReference. Untuk informasi yang mungkin membantu Anda memahami penerapan versi, lihat rangkaian posting blog ini:

• Bagian 1: Mengambil DLL Hell
• Bagian 2: Algoritma inti
• Bagian 3: Unifikasi melalui pengalihan pengikatan

Menambahkan bidang deskripsi opsional

Deskripsi opsional paket muncul pada tab README dari halaman nuget.org paket. Deskripsi menarik dari <Description> dalam file proyek atau $description dalam file .nuspec.

Contoh berikut menunjukkan Description dalam file .csproj untuk paket .NET:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Jalankan perintah paket

Untuk membangun paket NuGet atau file .nupkg , jalankan perintah dotnet pack dari folder proyek, yang juga membangun proyek secara otomatis.

dotnet pack

Output menunjukkan jalur ke file .nupkg :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Membuat paket secara otomatis pada build

Untuk menjalankan dotnet pack secara otomatis setiap kali Anda menjalankan dotnet build, tambahkan baris berikut ke file proyek Anda di <PropertyGroup> tag:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Catatan

Ketika Anda secara otomatis membuat paket, pengemasan meningkatkan waktu build untuk proyek Anda.

Berjalan dotnet pack pada solusi mengemas semua proyek dalam solusi yang dapat dikemas, yaitu, memiliki properti yang IsPackable diatur ke true.

Penginstalan paket pengujian

Sebelum menerbitkan paket, Anda harus menguji penginstalan paket ke dalam proyek. Pengujian memastikan bahwa file yang diperlukan berakhir di tempat yang benar dalam proyek.

Uji penginstalan secara manual di Visual Studio atau pada baris perintah dengan menggunakan proses penginstalan paket normal.

Penting

• Anda tidak dapat mengubah paket setelah dibuat. Jika Anda memperbaiki masalah, ubah konten paket dan kemas ulang.

• Setelah Anda membuat ulang paket, pengulangan masih menggunakan versi lama paket hingga Anda menghapus folder paket global Anda. Menghapus folder sangat penting untuk paket yang tidak menggunakan label prarilis unik pada setiap build.

Langkah berikutnya

Setelah membuat paket, Anda dapat menerbitkan file .nupkg ke host pilihan Anda.

Menerbitkan paket

Lihat artikel berikut untuk cara memperluas kemampuan paket Anda atau mendukung skenario lain:

• Penerapan versi paket
• Mendukung beberapa kerangka kerja target
• Tambahkan ikon paket
• Transformasi file sumber dan konfigurasi
• Pelokalan
• Versi prarilis
• Atur jenis paket
• Alat peraga dan target MSBuild
• Membuat paket dengan rakitan interop COM
• Membuat paket asli
• Membuat paket simbol (.snupkg)