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 non-gaya SDK, Anda perlu menambahkan paket NuGet.Build.Tasks.Pack ke dependensi proyek. Untuk informasi terperinci tentang target paket MSBuild, lihat Paket NuGet dan pemulihan sebagai target MSBuild.
Perintah yang membuat paket, 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.
Mengatur properti
Properti berikut diperlukan untuk membuat paket.
PackageId
, pengidentifikasi paket, yang harus unik di seluruh galeri yang menghosting paket. Jika tidak ditentukan, nilai defaultnya adalahAssemblyName
.Version
, nomor versi tertentu dalam formulir Major.Minor.Patch[-Suffix] 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 adalahAssemblyName
.Company
, nama perusahaan Anda. Jika tidak ditentukan, nilai defaultnya adalahAssemblyName
.
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
, , PackageDescription
dan PackageTags
, seperti yang dijelaskan dalam target paket MSBuild, Mengontrol aset dependensi, dan properti metadata NuGet.
Catatan
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 <IncludeAssets>
atribut 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 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>
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
daripadaContoso-Utility-UsefulStuff
atauContoso_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 dalamContoso.Utility.UsefulStuff.Sample
.Paket sampel memiliki dependensi pada paket asli. Saat Anda membuat paket sampel, tambahkan
<IncludeAssets>
dengancontentFiles
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:
Menambahkan paket NuGet.Build.Tasks.Pack
Jika Anda menggunakan MSBuild dengan proyek gaya non-SDK dan PackageReference, tambahkan paket NuGet.Build.Tasks.Pack ke proyek Anda.
Buka file proyek dan tambahkan yang berikut ini setelah
<PropertyGroup>
elemen :<ItemGroup> <!-- ... --> <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.7.0" PrivateAssets="all" /> <!-- ... --> </ItemGroup>
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 menginstal 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 .nupkg
file.
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
solusi, ini mengemas semua proyek dalam solusi yang dapat dikemas (<IsPackable>
properti diatur ke true
).
Catatan
Ketika Anda secara otomatis membuat paket, waktu 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 berikutnya
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:
- Paket dan pemulihan NuGet sebagai target MSBuild
- Penerapan versi paket
- Mendukung beberapa kerangka kerja target
- Transformasi file sumber dan konfigurasi
- Pelokalan
- Versi pra-rilis
- Atur jenis paket
- Alat peraga dan target MSBuild
- Membuat paket dengan rakitan interop COM
Terakhir, ada jenis paket tambahan yang perlu diperhatikan: