Membuat paket NuGet menggunakan MSBuild

Saat membuat paket NuGet dari kode, Anda mengemas fungsionalitas tersebut ke dalam komponen yang dapat dibagikan dengan dan digunakan oleh sejumlah pengembang lain. Artikel ini menjelaskan cara membuat paket menggunakan MSBuild. MSBuild telah diinstal sebelumnya dengan setiap beban kerja Visual Studio yang berisi NuGet. Selain itu Anda juga dapat menggunakan MSBuild melalui dotnet CLI dengan dotnet msbuild.

Untuk proyek .NET Core dan .NET Standard yang menggunakan format gaya SDK, dan proyek gaya SDK lainnya, NuGet menggunakan informasi dalam file proyek secara langsung untuk membuat paket. Untuk proyek gaya non-SDK yang menggunakan <PackageReference>, NuGet juga menggunakan file proyek untuk membuat paket.

Proyek bergaya SDK memiliki fungsionalitas paket yang tersedia secara default. Untuk proyek PackageReference gaya non-SDK, ini juga tersedia secara default mulai dari Visual Studio 2026. Di versi Visual Studio sebelumnya, Anda perlu menambahkan paket NuGet.Build.Tasks.Pack ke dependensi proyek dan sebaiknya hapus referensi paket ini saat meningkatkan ke Visual Studio 2026. Untuk informasi terperinci tentang target paket MSBuild, lihat Paket NuGet dan pemulihan sebagai target MSBuild.

Untuk proyek bergaya SDK, msbuild -t:pack secara fungsional setara dengan dotnet pack.

Penting

Topik ini berlaku untuk proyek bergaya SDK , biasanya proyek .NET Core dan .NET Standard, dan untuk proyek bergaya non-SDK yang menggunakan PackageReference.

Atur properti

Atribut berikut diperlukan untuk membuat paket.

PackageId, identifikasi paket, yang harus unik di seluruh galeri yang menyediakan paket. Jika tidak ditentukan, nilai defaultnya adalah AssemblyName.
Version, nomor versi tertentu dalam format Major.Minor.Patch[-akhiran] di mana -akhiran mengidentifikasi versi pra-rilis. Jika tidak ditentukan, nilai defaultnya adalah 1.0.0.
Judul paket seperti yang akan muncul di host (seperti nuget.org)
Authors, informasi penulis dan pemilik. Jika tidak ditentukan, nilai defaultnya adalah AssemblyName.
Company, nama perusahaan Anda. Jika tidak ditentukan, nilai defaultnya adalah AssemblyName.

Selain itu jika Anda mengemas proyek bergaya non-SDK yang menggunakan PackageReference, berikut ini diperlukan:

PackageOutputPath, folder output untuk paket yang dihasilkan saat memanggil paket.

Di Visual Studio, Anda dapat mengatur nilai-nilai ini di properti proyek (klik kanan proyek di Penjelajah Solusi, pilih Properti, dan pilih tab Paket ). Anda juga dapat mengatur properti ini langsung dalam file proyek (.csproj).

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Penting

Berikan paket pengidentifikasi yang unik di seluruh nuget.org atau sumber paket apa pun yang Anda gunakan.

Contoh berikut menunjukkan file proyek sederhana dan lengkap dengan properti ini disertakan.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Anda juga dapat mengatur properti opsional, seperti Title, , PackageDescriptiondan PackageTags, seperti yang dijelaskan dalam target paket MSBuild, Mengontrol aset dependensi, dan properti metadata NuGet.

Nota

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

Untuk detail tentang mendeklarasikan dependensi dan menentukan nomor versi, lihat Referensi paket dalam file proyek dan Penerapan versi paket. Dimungkinkan juga untuk memunculkan aset dari dependensi langsung dalam paket dengan menggunakan atribut <IncludeAssets> dan <ExcludeAssets>. Untuk informasi selengkapnya, lihat Mengontrol aset dependensi.

Menambahkan bidang deskripsi opsional

Deskripsi opsional paket muncul pada tab README dari halaman nuget.org paket. Deskripsi mengambil dari <Description> di dalam file proyek atau dari $description di 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>

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 pada namespace .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 nilai contentFiles. 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 menjadi sederhana ketika Anda membatasi paket ke satu komponen. 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 sesuai dengan Semantic Versioning 2.0.0.

Nota

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:

Mengonfigurasi proyek untuk paket

Proyek bergaya SDK tidak memerlukan konfigurasi tambahan apa pun.

Proyek bergaya non-SDK memerlukan setidaknya satu paket yang diinstal (melalui PackageReference, bukan packages.config), atau proyek secara eksplisit perlu menginstruksikan NuGet untuk memperlakukan proyek sebagai proyek PackageReference melalui RestoreProjectStyle properti .

Visual Studio 2022 dan yang lebih lama tidak memiliki paket bawaan, jadi Anda juga perlu menginstal paket NuGet.Build.Tasks.Pack. Saat meningkatkan ke Visual Studio 2026 atau yang lebih baru, sebaiknya hapus instalan paket, sehingga Anda mendapat manfaat dari fitur baru dan perbaikan bug.

Edit file proyek.

Jika Anda ingin secara eksplisit menginstruksikan NuGet untuk memperlakukan proyek sebagai PackageReference (proyek tidak memiliki paket apa pun yang terinstal), temukan atau tambahkan <PropertyGroup> yang tidak memiliki pernyataan apa pun Condition , dan tambahkan:
```
<PropertyGroup>
  
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  
</PropertyGroup>
```
Jika Anda menggunakan Visual Studio 2022 atau yang lebih lama, tambahkan hal berikut setelah <PropertyGroup> elemen :
```
<ItemGroup>
  
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.14.0" PrivateAssets="all" />
  
</ItemGroup>
```
Nota

Pertimbangkan untuk menggunakan versi terbaru paket ini yang tersedia.
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.
Beralih ke folder yang berisi file proyek dan ketik perintah berikut untuk memulihkan paket NuGet.Build.Tasks.Pack.
```
# Uses the project file in the current folder by default
msbuild -t:restore
```
Pastikan bahwa output MSBuild menunjukkan bahwa build berhasil diselesaikan.

Jalankan perintah msbuild -t:pack

Untuk membangun paket NuGet ( .nupkg file) dari proyek, jalankan msbuild -t:pack perintah , yang juga membangun proyek secara otomatis:

Di perintah Pengembang untuk Visual Studio, ketik perintah berikut:

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

Output menunjukkan jalur ke berkas .nupkg.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

Membuat paket secara otomatis pada build

Untuk menjalankan msbuild -t:pack secara otomatis saat Anda membangun atau memulihkan proyek, tambahkan baris berikut ke file proyek Anda dalam <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Ketika Anda menjalankan msbuild -t:pack pada solusi, ini memaketkan semua proyek dalam solusi yang dapat dipaketkan (properti <IsPackable> diatur ke true).

Nota

Ketika Anda secara otomatis membuat paket, waktu yang dibutuhkan untuk mengemas meningkatkan waktu build untuk proyek Anda.

Penginstalan paket pengujian

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

Anda dapat menguji penginstalan secara manual di Visual Studio atau di baris perintah menggunakan langkah-langkah penginstalan paket normal.

Penting

Paket tidak dapat diubah. Jika Anda memperbaiki masalah, ubah konten paket dan paket lagi, ketika Anda mencoba kembali, Anda masih akan menggunakan versi lama paket sampai Anda menghapus folder paket global Anda . Ini sangat relevan ketika menguji paket yang tidak menggunakan label prarilis unik pada setiap build.

Langkah Selanjutnya

Setelah membuat paket, yang merupakan .nupkg file, Anda dapat menerbitkannya ke galeri pilihan Anda seperti yang dijelaskan di Menerbitkan Paket.

Anda mungkin juga ingin memperluas kemampuan paket Anda atau mendukung skenario lain seperti yang dijelaskan dalam topik berikut:

Terakhir, ada jenis paket tambahan yang perlu diperhatikan:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-15

Bagikan melalui

Membuat paket NuGet menggunakan MSBuild

Atur properti

Menambahkan bidang deskripsi opsional

Pilih pengidentifikasi paket unik dan atur nomor versi

Mengonfigurasi proyek untuk paket

Jalankan perintah msbuild -t:pack

Membuat paket secara otomatis pada build

Penginstalan paket pengujian

Langkah Selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: