Membuat paket NuGet menggunakan MSBuild

  • Artikel

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 adalah AssemblyName.
  • 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 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.

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 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:

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.

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

    Catatan

    Pertimbangkan untuk menggunakan versi terbaru paket ini yang tersedia.

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

  3. 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:

Terakhir, ada jenis paket tambahan yang perlu diperhatikan: