Referensi .nuspec
File .nuspec
adalah manifes XML yang berisi metadata paket. Manifes ini digunakan baik untuk membangun paket maupun untuk memberikan informasi kepada konsumen. Manifes selalu disertakan dalam paket.
Dalam topik ini:
- Bentuk dan skema umum
- Token pengganti (saat digunakan dengan proyek Visual Studio)
- Dependensi
- Referensi rakitan eksplisit
- Referensi perakitan kerangka kerja
- Termasuk file assembly
- Menyertakan file konten
- Contoh file nuspec
Gunakan
.nuspec
dengannuget.exe pack
untuk proyek bergaya non-SDK yang menggunakanpackages.config
.File
.nuspec
tidak diperlukan untuk membuat paket untuk proyek gaya SDK (biasanya proyek .NET Core dan .NET Standard yang menggunakan atribut SDK). (Perhatikan bahwa dibuat.nuspec
saat Anda membuat paket.)Jika Anda membuat paket menggunakan
dotnet.exe pack
ataumsbuild pack target
, kami sarankan Anda menyertakan semua properti yang biasanya ada dalam.nuspec
file dalam file proyek sebagai gantinya. Namun, Anda dapat memilih untuk menggunakan file untuk dikemas menggunakandotnet.exe
ataumsbuild pack target
.nuspec
.Untuk proyek yang dimigrasikan dari
packages.config
ke PackageReference,.nuspec
file tidak diperlukan untuk membuat paket. Sebagai gantinya, gunakan msbuild -t:pack.
File nuspec.xsd
skema dapat ditemukan di repositori NuGet GitHub.
Perhatikan, bahwa file ini hanya mewakili skema terbaru untuk .nuspec
file.
Tidak ada versi yang diterbitkan secara resmi dan tidak ada versi file tersebut yang sesuai dengan versi NuGet tertentu.
Dalam skema ini, .nuspec
file memiliki formulir umum berikut:
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
<!-- Required elements-->
<id></id>
<version></version>
<description></description>
<authors></authors>
<!-- Optional elements -->
<!-- ... -->
</metadata>
<!-- Optional 'files' node -->
</package>
Untuk representasi visual yang jelas dari skema, buka file skema di Visual Studio dalam mode Desain dan klik tautan XML Schema Explorer . Secara bergantian, buka file sebagai kode, klik kanan di editor, dan pilih Tampilkan Penjelajah Skema XML. Bagaimanapun Anda mendapatkan tampilan seperti yang di bawah ini (ketika sebagian besar diperluas):
Semua nama elemen XML dalam file .nuspec peka huruf besar/kecil, seperti halnya XML secara umum. Misalnya, menggunakan elemen <description>
metadata sudah benar dan <Description>
tidak benar. Casing yang tepat untuk setiap nama elemen didokumenkan di bawah ini.
Penting
.nuspec
Meskipun file berisi referensi ke skema (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"
), NuGet-Team belum pernah menerbitkan file skema yang dapat digunakan untuk validasi skema otomatis.
Meskipun elemen berikut adalah persyaratan minimum untuk paket, Anda harus mempertimbangkan untuk menambahkan elemen metadata opsional untuk meningkatkan pengalaman keseluruhan yang dimiliki pengembang dengan paket Anda.
Elemen-elemen ini harus muncul dalam <metadata>
elemen .
Pengidentifikasi paket yang tidak peka huruf besar/kecil, yang harus unik di seluruh nuget.org atau galeri apa pun tempat paket berada. ID mungkin tidak berisi spasi atau karakter yang tidak valid untuk URL, dan umumnya mengikuti aturan namespace layanan .NET. Lihat Memilih pengidentifikasi paket unik untuk panduan.
Saat mengunggah paket ke nuget.org, bidang dibatasi id
hingga 128 karakter.
Versi paket, mengikuti pola major.minor.patch . Nomor versi dapat menyertakan akhiran pra-rilis seperti yang dijelaskan dalam Penerapan versi paket.
Saat mengunggah paket ke nuget.org, bidang dibatasi version
hingga 64 karakter.
Deskripsi paket untuk tampilan UI.
Saat mengunggah paket ke nuget.org, bidang dibatasi description
hingga 4000 karakter.
Daftar penulis paket yang dipisahkan koma.
authors
dan owners
dari nuspec diabaikan saat mengunggah paket ke nuget.org. Untuk mengatur kepemilikan paket pada nuget.org, lihat Mengelola pemilik paket di nuget.org.
Penting
pemilik tidak digunakan lagi. Gunakan penulis sebagai gantinya.
Daftar pemilik paket yang dipisahkan koma.
owners
Dari nuspec diabaikan saat mengunggah paket ke nuget.org. Untuk mengatur kepemilikan paket pada nuget.org, lihat Mengelola pemilik paket di nuget.org.
URL untuk beranda paket, sering ditampilkan di tampilan UI serta nuget.org.
Saat mengunggah paket ke nuget.org, bidang dibatasi projectUrl
hingga 4000 karakter.
Penting
licenseUrl tidak digunakan lagi. Gunakan lisensi sebagai gantinya.
URL untuk lisensi paket, sering ditampilkan di UI seperti nuget.org.
Saat mengunggah paket ke nuget.org, bidang dibatasi licenseUrl
hingga 4000 karakter.
Didukung dengan NuGet 4.9.0 ke atas
Ekspresi lisensi SPDX atau jalur ke file lisensi dalam paket, sering ditampilkan di UI seperti nuget.org. Jika Anda melisensikan paket di bawah lisensi umum, seperti MIT atau BSD-2-Clause, gunakan pengidentifikasi lisensi SPDX terkait. Contoh:
<license type="expression">MIT</license>
Catatan
NuGet.org hanya menerima ekspresi lisensi yang disetujui oleh Open Source Initiative atau Free Software Foundation.
Jika paket Anda dilisensikan di bawah beberapa lisensi umum, Anda dapat menentukan lisensi komposit menggunakan sintaks ekspresi SPDX versi 2.0. Contohnya:
<license type="expression">BSD-2-Clause OR MIT</license>
Jika Anda menggunakan lisensi kustom yang tidak didukung oleh ekspresi lisensi, Anda bisa mengemas .txt
file atau .md
dengan teks lisensi. Contohnya:
<package>
<metadata>
...
<license type="file">LICENSE.txt</license>
...
</metadata>
<files>
...
<file src="licenses\LICENSE.txt" target="" />
...
</files>
</package>
Untuk MSBuild yang setara, lihat Mengemas ekspresi lisensi atau file lisensi.
Sintaks yang tepat dari ekspresi lisensi NuGet dijelaskan di bawah ini dalam ABNF.
license-id = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>
license-exception-id = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>
simple-expression = license-id / license-id”+”
compound-expression = 1*1(simple-expression /
simple-expression "WITH" license-exception-id /
compound-expression "AND" compound-expression /
compound-expression "OR" compound-expression ) /
"(" compound-expression ")" )
license-expression = 1*1(simple-expression / compound-expression / UNLICENSED)
Penting
iconUrl tidak digunakan lagi. Gunakan ikon sebagai gantinya.
URL untuk gambar 128x128 dengan latar belakang transparansi untuk digunakan sebagai ikon untuk paket di tampilan UI. Pastikan elemen ini berisi URL gambar langsung dan bukan URL halaman web yang berisi gambar. Misalnya, untuk menggunakan gambar dari GitHub, gunakan URL file mentah seperti nama pengguna/<repositori>/mentah/<cabang>/<logo.png>.>https://github.com/<
Saat mengunggah paket ke nuget.org, bidang dibatasi iconUrl
hingga 4000 karakter.
Didukung dengan NuGet 5.3.0 ke atas
Ini adalah jalur ke file gambar dalam paket, sering ditampilkan di UI seperti nuget.org sebagai ikon paket. Ukuran file gambar dibatasi hingga 1 MB. Format file yang didukung mencakup JPEG dan PNG. Kami merekomendasikan resolusi gambar 128x128.
Misalnya, Anda akan menambahkan yang berikut ke nuspec Anda saat membuat paket menggunakan nuget.exe:
<package>
<metadata>
...
<icon>images\icon.png</icon>
...
</metadata>
<files>
...
<file src="..\icon.png" target="images\" />
...
</files>
</package>
Untuk MSBuild yang setara, lihat Mengemas file gambar ikon.
Tip
Untuk mempertahankan kompatibilitas mundur dengan klien dan sumber yang belum mendukung icon
, tentukan dan icon
iconUrl
. Visual Studio mendukung icon
paket yang berasal dari sumber berbasis folder.
Didukung dengan NuGet 5.10.0 pratinjau 2 ke atas
Saat mengemas file readme, Anda perlu menggunakan readme
elemen untuk menentukan jalur paket, relatif terhadap akar paket. Selain itu, Anda perlu memastikan bahwa file disertakan dalam paket. Format file yang didukung hanya menyertakan Markdown (.md).
Misalnya, Anda akan menambahkan yang berikut ke nuspec Anda untuk mengemas file readme dengan proyek Anda:
<package>
<metadata>
...
<readme>docs\readme.md</readme>
...
</metadata>
<files>
...
<file src="..\readme.md" target="docs\" />
...
</files>
</package>
Untuk MSBuild yang setara, lihat Mengemas file readme.
Nilai Boolean yang menentukan apakah klien harus meminta konsumen untuk menerima lisensi paket sebelum menginstal paket.
(2.8+) Nilai Boolean yang menentukan apakah paket ditandai sebagai dependensi khusus pengembangan, yang mencegah paket disertakan sebagai dependensi dalam paket lain. Dengan PackageReference (NuGet 4.8+), bendera ini juga berarti bahwa bendera ini akan mengecualikan aset waktu kompilasi dari kompilasi. Lihat Dukungan DevelopmentDependency untuk PackageReference
Penting
summary
tidak digunakan lagi. Gunakan description
sebagai gantinya.
Deskripsi singkat tentang paket untuk tampilan UI. Jika dihilangkan, versi terpotong akan description
digunakan.
Saat mengunggah paket ke nuget.org, bidang dibatasi summary
hingga 4000 karakter.
(1.5+) Deskripsi perubahan yang dilakukan dalam rilis paket ini, sering digunakan di UI seperti tab Pembaruan Manajer Paket Visual Studio sebagai pengganti deskripsi paket.
Saat mengunggah paket ke nuget.org, bidang dibatasi releaseNotes
hingga 35.000 karakter.
(1.5+) Detail hak cipta untuk paket.
Saat mengunggah paket ke nuget.org, bidang dibatasi copyright
hingga 4000 karakter.
ID lokal untuk paket. Lihat Membuat paket yang dilokalkan.
Daftar tag dan kata kunci yang dibatasi spasi yang menjelaskan paket dan membantu penemuan paket melalui pencarian dan pemfilteran.
Saat mengunggah paket ke nuget.org, bidang dibatasi tags
hingga 4000 karakter.
(3.3+) Hanya untuk penggunaan NuGet internal.
Metadata repositori, terdiri dari empat atribut opsional: type
dan url
(4.0+), dan branch
dan commit
(4.6+). Atribut ini memungkinkan Anda untuk memetakan .nupkg
ke repositori yang membuatnya, dengan potensi untuk mendapatkan sedetail nama cabang individu dan / atau menerapkan hash SHA-1 yang membangun paket. Ini harus menjadi url yang tersedia untuk umum yang dapat dipanggil langsung oleh perangkat lunak kontrol versi. Ini seharusnya bukan halaman html karena ini dimaksudkan untuk komputer. Untuk menautkan ke halaman proyek, gunakan bidang , sebagai gantinya projectUrl
.
Contohnya:
<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
...
<repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
...
</metadata>
</package>
Saat mengunggah paket ke nuget.org, atribut dibatasi type
hingga 100 karakter dan atribut dibatasi url
hingga 4000 karakter.
Judul paket yang ramah manusia yang dapat digunakan di beberapa tampilan UI. (nuget.org dan Manajer Paket di Visual Studio tidak menampilkan judul)
Saat mengunggah paket ke nuget.org, bidang dibatasi title
hingga 256 karakter tetapi tidak digunakan untuk tujuan tampilan apa pun.
(3.5+) Kumpulan elemen nol atau lebih <packageType>
yang menentukan jenis paket jika selain paket dependensi tradisional. Setiap packageType memiliki atribut nama dan versi. Lihat Mengatur jenis paket.
Kumpulan elemen nol atau lebih <dependency>
yang menentukan dependensi untuk paket. Setiap dependensi memiliki atribut id, versi, sertakan (3.x+), dan kecualikan (3.x+). Lihat Dependensi di bawah ini.
(1.2+) Kumpulan elemen nol atau lebih <frameworkAssembly>
yang mengidentifikasi perakitan .NET Framework yang diperlukan paket ini, yang memastikan bahwa referensi ditambahkan ke proyek yang menggunakan paket. Setiap frameworkAssembly memiliki atribut assemblyName dan targetFramework . Lihat Menentukan referensi rakitan kerangka kerja GAC di bawah ini.
(1.5+) Kumpulan nol atau lebih <reference>
elemen penamaan rakitan di folder paket lib
yang ditambahkan sebagai referensi proyek. Setiap referensi memiliki atribut file . <references>
juga dapat berisi <group>
elemen dengan atribut targetFramework , yang kemudian berisi <reference>
elemen. Jika dihilangkan, semua referensi disertakan lib
. Lihat Menentukan referensi rakitan eksplisit di bawah ini.
(3.3+) Kumpulan <files>
elemen yang mengidentifikasi file konten untuk disertakan dalam proyek yang mengkonsumsi. File-file ini ditentukan dengan sekumpulan atribut yang menjelaskan bagaimana file tersebut harus digunakan dalam sistem proyek. Lihat Menentukan file yang akan disertakan dalam paket di bawah ini.
Simpul <package>
mungkin berisi simpul <files>
sebagai saudara kandung <metadata>
, dan <contentFiles>
anak di bawah <metadata>
, untuk menentukan file rakitan dan konten mana yang akan disertakan dalam paket. Lihat Menyertakan file rakitan dan Menyertakan file konten nanti dalam topik ini untuk detailnya.
Menentukan versi minimum klien NuGet yang dapat menginstal paket ini, yang diberlakukan oleh nuget.exe dan Manajer Paket Visual Studio. Ini digunakan setiap kali paket tergantung pada fitur tertentu dari .nuspec
file yang ditambahkan dalam versi tertentu dari klien NuGet. Misalnya, paket yang menggunakan developmentDependency
atribut harus menentukan "2.8" untuk minClientVersion
. Demikian pula, paket yang menggunakan contentFiles
elemen (lihat bagian berikutnya) harus diatur minClientVersion
ke "3.3". Perhatikan juga bahwa karena klien NuGet sebelum 2.5 tidak mengenali bendera ini, mereka selalu menolak untuk menginstal paket apa pun isinya minClientVersion
.
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata minClientVersion="100.0.0.1">
<id>dasdas</id>
<version>2.0.0</version>
<title />
<authors>dsadas</authors>
<owners />
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>My package description.</description>
</metadata>
<files>
<file src="content\one.txt" target="content\one.txt" />
</files>
</package>
Saat membuat paket, perintah menggantikan token yang dibatasi $dalam .nuspec
file <metadata>
dan <files>
simpul dengan nilai yang berasal dari file proyek atau pack
sakelar perintah-properties
.nuget pack
Pada baris perintah, Anda menentukan nilai token dengan nuget pack -properties <name>=<value>;<name>=<value>
. Misalnya, Anda dapat menggunakan token seperti $owners$
dan $desc$
di .nuspec
dan memberikan nilai pada waktu pengemasan sebagai berikut:
nuget pack MyProject.csproj -properties
owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"
Untuk menggunakan nilai dari proyek, tentukan token yang dijelaskan dalam tabel di bawah ini (AssemblyInfo mengacu pada file di Properties
seperti AssemblyInfo.cs
atau AssemblyInfo.vb
).
Untuk menggunakan token ini, jalankan nuget pack
dengan file proyek daripada hanya .nuspec
. Misalnya, saat menggunakan perintah berikut, $id$
token dan $version$
dalam .nuspec
file diganti dengan nilai dan AssemblyVersion
proyekAssemblyName
:
nuget pack MyProject.csproj
Biasanya, ketika Anda memiliki proyek, Anda membuat .nuspec
awal menggunakan nuget spec MyProject.csproj
yang secara otomatis menyertakan beberapa token standar ini. Namun, jika proyek tidak memiliki nilai untuk elemen yang diperlukan .nuspec
, maka nuget pack
gagal. Selain itu, jika Anda mengubah nilai proyek, pastikan untuk membangun kembali sebelum membuat paket; ini dapat dilakukan dengan mudah dengan sakelar perintah build
paket.
Dengan pengecualian $configuration$
, nilai dalam proyek digunakan dalam preferensi untuk setiap yang ditetapkan ke token yang sama pada baris perintah.
Token | Sumber nilai | Nilai |
---|---|---|
$id$ | File proyek | AssemblyName (judul) dari file proyek |
$version$ | AssemblyInfo | AssemblyInformationalVersion jika ada, jika tidak, AssemblyVersion |
$author$ | AssemblyInfo | AssemblyCompany |
$title$ | AssemblyInfo | AssemblyTitle |
$description$ | AssemblyInfo | AssemblyDescription |
$copyright$ | AssemblyInfo | AssemblyCopyright |
$configuration$ | Assembly DLL | Konfigurasi yang digunakan untuk membangun rakitan, default ke Debug. Perhatikan bahwa untuk membuat paket menggunakan konfigurasi Rilis, Anda selalu menggunakan -properties Configuration=Release pada baris perintah. |
Token juga dapat digunakan untuk mengatasi jalur saat Anda menyertakan file rakitan dan file konten. Token memiliki nama yang sama dengan properti MSBuild, sehingga memungkinkan untuk memilih file yang akan disertakan tergantung pada konfigurasi build saat ini. Misalnya, jika Anda menggunakan token berikut dalam .nuspec
file:
<files>
<file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>
Dan Anda membangun rakitan yang AssemblyName
LoggingLibrary
dengan Release
konfigurasi di MSBuild, baris yang dihasilkan dalam .nuspec
file dalam paket adalah sebagai berikut:
<files>
<file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>
Elemen <dependencies>
dalam <metadata>
berisi sejumlah <dependency>
elemen yang mengidentifikasi paket lain di mana paket tingkat atas bergantung. Atribut untuk masing-masing <dependency>
adalah sebagai berikut:
Atribut | Deskripsi |
---|---|
id |
(Diperlukan) ID paket dependensi, seperti "EntityFramework" dan "NUnit", yang merupakan nama paket yang nuget.org tampilkan di halaman paket. |
version |
(Diperlukan) Rentang versi dapat diterima sebagai dependensi. Lihat Penerapan versi paket untuk sintaks yang tepat. Versi mengambang tidak didukung. |
termasuk | Daftar tag sertakan/kecualikan yang dibatasi koma (lihat di bawah) yang menunjukkan dependensi untuk disertakan dalam paket akhir. Nilai defaultnya adalah all . |
jangan sertakan | Daftar tag sertakan/kecualikan yang dibatasi koma (lihat di bawah) yang menunjukkan dependensi untuk dikecualikan dalam paket akhir. Nilai defaultnya adalah build,analyzers yang dapat ditulis secara berlebihan. Tetapi content/ ContentFiles juga secara implisit dikecualikan dalam paket akhir yang tidak dapat ditulis berlebihan. Tag yang ditentukan dengan exclude diutamakan daripada yang ditentukan dengan include . Misalnya, include="runtime, compile" exclude="compile" sama dengan include="runtime" . |
Saat mengunggah paket ke nuget.org, atribut setiap dependensi id
dibatasi hingga 128 karakter dan atribut dibatasi version
hingga 256 karakter.
Sertakan/Kecualikan tag | Folder yang terpengaruh dari target |
---|---|
contentFiles | Konten |
runtime | Runtime, Sumber Daya, dan FrameworkAssemblies |
bangun | Lib |
build | build (alat peraga dan target MSBuild) |
native | native |
tidak ada | Tidak ada folder |
all | Semua folder |
Misalnya, baris berikut menunjukkan dependensi pada PackageA
versi 1.1.0 atau yang lebih tinggi, dan PackageB
versi 1.x.
<dependencies>
<dependency id="PackageA" version="1.1.0" />
<dependency id="PackageB" version="[1,2)" />
</dependencies>
Baris berikut menunjukkan dependensi pada paket yang sama, tetapi tentukan untuk menyertakan contentFiles
folder dan build
dari PackageA
dan semuanya kecuali native
folder PackageB
dan compile
"
<dependencies>
<dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
<dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>
Penting
Saat membuat .nuspec
dari proyek menggunakan nuget spec
, dependensi yang ada dalam proyek tersebut tidak secara otomatis disertakan dalam file yang .nuspec
dihasilkan. Sebagai gantinya, gunakan nuget pack myproject.csproj
, dan dapatkan file .nuspec dari dalam file .nupkg yang dihasilkan. .nuspec ini berisi dependensi.
Versi 2.0+
Sebagai alternatif untuk daftar datar tunggal, dependensi dapat ditentukan sesuai dengan profil kerangka kerja proyek target menggunakan <group>
elemen dalam <dependencies>
.
Setiap grup memiliki atribut bernama targetFramework
dan berisi nol elemen atau lebih <dependency>
. Dependensi tersebut diinstal bersama-sama ketika kerangka kerja target kompatibel dengan profil kerangka kerja proyek.
Elemen <group>
tanpa targetFramework
atribut digunakan sebagai daftar default atau fallback dependensi. Lihat Kerangka kerja target untuk pengidentifikasi kerangka kerja yang tepat.
Penting
Format grup tidak dapat diintermiks dengan daftar datar.
Catatan
Format Target Framework Moniker (TFM) yang digunakan dalam lib/ref
folder berbeda jika dibandingkan dengan TFM yang digunakan dalam dependency groups
. Jika kerangka kerja target yang dideklarasikan di dependencies group
folder dan lib/ref
file .nuspec
tidak memiliki kecocokan yang tepat, pack
perintah akan menaikkan NuGet Warning NU5128.
Contoh berikut menunjukkan variasi elemen yang <group>
berbeda:
<dependencies>
<group>
<dependency id="RouteMagic" version="1.1.0" />
</group>
<group targetFramework=".NETFramework4.7.2">
<dependency id="jQuery" version="1.6.2" />
<dependency id="WebActivator" version="1.4.4" />
</group>
<group targetFramework="netcoreapp3.1">
</group>
</dependencies>
Elemen <references>
ini digunakan oleh proyek yang menggunakan packages.config
untuk secara eksplisit menentukan rakitan yang harus dirujuk oleh proyek target saat menggunakan paket. Referensi eksplisit biasanya digunakan untuk rakitan khusus waktu desain. Untuk informasi selengkapnya, lihat halaman tentang memilih rakitan yang dirujuk oleh proyek untuk informasi selengkapnya.
Misalnya, elemen berikut <references>
menginstruksikan NuGet untuk menambahkan referensi hanya xunit.dll
dan xunit.extensions.dll
bahkan jika ada rakitan tambahan dalam paket:
<references>
<reference file="xunit.dll" />
<reference file="xunit.extensions.dll" />
</references>
Sebagai alternatif untuk satu daftar datar, referensi dapat ditentukan sesuai dengan profil kerangka kerja proyek target menggunakan <group>
elemen dalam <references>
.
Setiap grup memiliki atribut bernama targetFramework
dan berisi nol elemen atau lebih <reference>
. Referensi tersebut ditambahkan ke proyek saat kerangka kerja target kompatibel dengan profil kerangka kerja proyek.
Elemen <group>
tanpa targetFramework
atribut digunakan sebagai daftar referensi default atau fallback. Lihat Kerangka kerja target untuk pengidentifikasi kerangka kerja yang tepat.
Penting
Format grup tidak dapat diintermiks dengan daftar datar.
Contoh berikut menunjukkan variasi elemen yang <group>
berbeda:
<references>
<group>
<reference file="a.dll" />
</group>
<group targetFramework="net45">
<reference file="b45.dll" />
</group>
<group targetFramework="netcore45">
<reference file="bcore45.dll" />
</group>
</references>
Rakitan kerangka kerja adalah yang merupakan bagian dari kerangka kerja .NET dan harus sudah berada di cache perakitan global (GAC) untuk komputer tertentu. Dengan mengidentifikasi rakitan tersebut dalam <frameworkAssemblies>
elemen , paket dapat memastikan bahwa referensi yang diperlukan ditambahkan ke proyek jika proyek belum memiliki referensi tersebut. Rakitan seperti itu, tentu saja, tidak termasuk dalam paket secara langsung.
Elemen <frameworkAssemblies>
berisi nol atau lebih <frameworkAssembly>
elemen, yang masing-masing menentukan atribut berikut:
Atribut | Deskripsi |
---|---|
assemblyName | (Diperlukan) Nama rakitan yang sepenuhnya memenuhi syarat. |
targetFramework | (Opsional) Menentukan kerangka kerja target tempat referensi ini berlaku. Jika dihilangkan, menunjukkan bahwa referensi berlaku untuk semua kerangka kerja. Lihat Kerangka kerja target untuk pengidentifikasi kerangka kerja yang tepat. |
Contoh berikut menunjukkan referensi ke System.Net
untuk semua kerangka kerja target, dan referensi untuk System.ServiceModel
.NET Framework 4.0 saja:
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.Net" />
<frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>
Jika Anda mengikuti konvensi yang dijelaskan dalam Membuat Paket, Anda tidak perlu secara eksplisit menentukan daftar file dalam .nuspec
file. Perintah nuget pack
secara otomatis mengambil file yang diperlukan.
Penting
Ketika paket diinstal ke dalam proyek, NuGet secara otomatis menambahkan referensi perakitan ke DLL paket, tidak termasuk yang dinamai .resources.dll
karena diasumsikan sebagai rakitan satelit yang dilokalkan. Untuk alasan ini, hindari penggunaan .resources.dll
untuk file yang berisi kode paket penting.
Untuk melewati perilaku otomatis ini dan secara eksplisit mengontrol file mana yang disertakan dalam paket, tempatkan <files>
elemen sebagai turunan <package>
(dan saudara kandung <metadata>
), mengidentifikasi setiap file dengan elemen terpisah <file>
. Contohnya:
<files>
<file src="bin\Debug\*.dll" target="lib" />
<file src="bin\Debug\*.pdb" target="lib" />
<file src="tools\**\*.*" exclude="**\*.log" />
</files>
Dengan NuGet 2.x dan yang lebih lama, dan proyek menggunakan packages.config
, <files>
elemen ini juga digunakan untuk menyertakan file konten yang tidak dapat diubah saat paket diinstal. Dengan NuGet 3.3+ dan proyek PackageReference, <contentFiles>
elemen digunakan sebagai gantinya. Lihat Menyertakan file konten di bawah ini untuk detailnya.
Setiap <file>
elemen menentukan atribut berikut:
Atribut | Deskripsi |
---|---|
src | Lokasi file atau file yang akan disertakan, tunduk pada pengecualian yang ditentukan oleh exclude atribut . Jalur relatif terhadap .nuspec file kecuali jalur absolut ditentukan. Karakter * kartubebas diizinkan, dan kartubebas ** ganda menyiratkan pencarian folder rekursif. |
target | Jalur relatif ke folder dalam paket tempat file sumber ditempatkan, yang harus dimulai dengan lib , , content build , atau tools . Lihat Membuat .nuspec dari direktori kerja berbasis konvensi. |
Mengecualikan | Daftar file atau pola file yang dibatasi titik koma untuk dikecualikan src dari lokasi. Karakter * kartubebas diizinkan, dan kartubebas ** ganda menyiratkan pencarian folder rekursif. |
Rakitan tunggal
Source file:
library.dll
.nuspec entry:
<file src="library.dll" target="lib" />
Packaged result:
lib\library.dll
Rakitan tunggal khusus untuk kerangka kerja target
Source file:
library.dll
.nuspec entry:
<file src="assemblies\net40\library.dll" target="lib\net40" />
Packaged result:
lib\net40\library.dll
Set DLL menggunakan kartubebas
Source files:
bin\release\libraryA.dll
bin\release\libraryB.dll
.nuspec entry:
<file src="bin\release\*.dll" target="lib" />
Packaged result:
lib\libraryA.dll
lib\libraryB.dll
DLL untuk kerangka kerja yang berbeda
Source files:
lib\net40\library.dll
lib\net20\library.dll
.nuspec entry (using ** recursive search):
<file src="lib\**" target="lib" />
Packaged result:
lib\net40\library.dll
lib\net20\library.dll
Mengecualikan file
Source files:
\tools\fileA.bak
\tools\fileB.bak
\tools\fileA.log
\tools\build\fileB.log
.nuspec entries:
<file src="tools\*.*" target="tools" exclude="tools\*.bak" />
<file src="tools\**\*.*" target="tools" exclude="**\*.log" />
Package result:
(no files)
File konten adalah file yang tidak dapat diubah yang perlu disertakan paket dalam proyek. Menjadi tidak dapat diubah, mereka tidak dimaksudkan untuk dimodifikasi oleh proyek yang mengonsumsi. Contoh file konten meliputi:
- Gambar yang disematkan sebagai sumber daya
- File sumber yang sudah dikompilasi
- Skrip yang perlu disertakan dengan output build proyek
- File konfigurasi untuk paket yang perlu disertakan dalam proyek tetapi tidak memerlukan perubahan khusus proyek
File konten disertakan dalam paket menggunakan <files>
elemen , menentukan content
folder dalam target
atribut . Namun, file tersebut diabaikan ketika paket diinstal dalam proyek menggunakan PackageReference, yang sebaliknya menggunakan <contentFiles>
elemen .
Untuk kompatibilitas maksimum dengan mengkonsumsi proyek, paket idealnya menentukan file konten di kedua elemen.
Untuk file konten, cukup gunakan format yang sama seperti untuk file rakitan, tetapi tentukan content
sebagai folder dasar dalam target
atribut seperti yang ditunjukkan dalam contoh berikut.
File konten dasar
Source files:
css\mobile\style1.css
css\mobile\style2.css
.nuspec entry:
<file src="css\mobile\*.css" target="content\css\mobile" />
Packaged result:
content\css\mobile\style1.css
content\css\mobile\style2.css
File konten dengan struktur direktori
Source files:
css\mobile\style.css
css\mobile\wp7\style.css
css\browser\style.css
.nuspec entry:
<file src="css\**\*.css" target="content\css" />
Packaged result:
content\css\mobile\style.css
content\css\mobile\wp7\style.css
content\css\browser\style.css
File konten khusus untuk kerangka kerja target
Source file:
css\cool\style.css
.nuspec entry
<file src="css\cool\style.css" target="Content" />
Packaged result:
content\style.css
File konten disalin ke folder dengan titik dalam nama
Dalam hal ini, NuGet melihat bahwa ekstensi di target
tidak cocok dengan ekstensi src
dan dengan demikian memperlakukan bagian nama tersebut sebagai target
folder:
Source file:
images\picture.png
.nuspec entry:
<file src="images\picture.png" target="Content\images\package.icons" />
Packaged result:
content\images\package.icons\picture.png
File konten tanpa ekstensi
Untuk menyertakan file tanpa ekstensi, gunakan *
kartubebas atau **
:
Source file:
flags\installed
.nuspec entry:
<file src="flags\**" target="flags" />
Packaged result:
flags\installed
File konten dengan jalur mendalam dan target mendalam
Dalam hal ini, karena ekstensi file dari kecocokan sumber dan target, NuGet mengasumsikan bahwa target adalah nama file dan bukan folder:
Source file:
css\cool\style.css
.nuspec entry:
<file src="css\cool\style.css" target="Content\css\cool" />
or:
<file src="css\cool\style.css" target="Content\css\cool\style.css" />
Packaged result:
content\css\cool\style.css
Mengganti nama file konten dalam paket
Source file:
ie\css\style.css
.nuspec entry:
<file src="ie\css\style.css" target="Content\css\ie.css" />
Packaged result:
content\css\ie.css
Mengecualikan file
Source file:
docs\*.txt (multiple files)
.nuspec entry:
<file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
or
<file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />
Packaged result:
All .txt files from docs except admin.txt (first example)
All .txt files from docs except admin.txt and log.txt (second example)
NuGet 4.0+ dengan PackageReference
Secara default, paket menempatkan konten dalam contentFiles
folder (lihat di bawah) dan nuget pack
menyertakan semua file dalam folder tersebut menggunakan atribut default. Dalam hal ini tidak perlu menyertakan node contentFiles
sama .nuspec
sekali.
Untuk mengontrol file mana yang disertakan, <contentFiles>
elemen yang ditentukan adalah kumpulan <files>
elemen yang mengidentifikasi file yang tepat termasuk.
File-file ini ditentukan dengan sekumpulan atribut yang menjelaskan bagaimana file tersebut harus digunakan dalam sistem proyek:
Atribut | Deskripsi |
---|---|
termasuk | (Diperlukan) Lokasi file atau file yang akan disertakan, tunduk pada pengecualian yang ditentukan oleh exclude atribut . Jalur relatif terhadap contentFiles folder kecuali jalur absolut ditentukan. Karakter * kartubebas diizinkan, dan kartubebas ** ganda menyiratkan pencarian folder rekursif. |
Mengecualikan | Daftar file atau pola file yang dibatasi titik koma untuk dikecualikan src dari lokasi. Karakter * kartubebas diizinkan, dan kartubebas ** ganda menyiratkan pencarian folder rekursif. |
buildAction | Tindakan build untuk menetapkan ke item konten untuk MSBuild, seperti Content , , None Embedded Resource , Compile , dll. Defaultnya adalah Compile . |
copyToOutput | Boolean yang menunjukkan apakah akan menyalin item konten ke folder output build (atau menerbitkan). Defaultnya adalah false. |
flatten | Boolean yang menunjukkan apakah akan menyalin item konten ke satu folder dalam output build (benar), atau untuk mempertahankan struktur folder dalam paket (false). Bendera ini hanya berfungsi ketika bendera copyToOutput diatur ke true. Defaultnya adalah false. |
Saat menginstal paket, NuGet menerapkan elemen anak dari <contentFiles>
atas ke bawah. Jika beberapa entri cocok dengan file yang sama, maka semua entri diterapkan. Entri paling atas mengambil alih entri yang lebih rendah jika ada konflik untuk atribut yang sama.
Proyek paket harus menyusun konten menggunakan pola berikut:
/contentFiles/{codeLanguage}/{TxM}/{any?}
codeLanguages
mungkincs
, ,vb
fs
,any
, atau huruf kecil yang setara dengan yang diberikan$(ProjectLanguage)
TxM
adalah moniker kerangka kerja target hukum apa pun yang didukung NuGet (lihat Kerangka kerja target).- Struktur folder apa pun dapat ditambahkan ke akhir sintaks ini.
Contohnya:
Language- and framework-agnostic:
/contentFiles/any/any/config.xml
net45 content for all languages
/contentFiles/any/net45/config.xml
C#-specific content for net45 and up
/contentFiles/cs/net45/sample.cs
Folder kosong dapat digunakan _._
untuk menolak penyediaan konten untuk kombinasi bahasa dan TxM tertentu, misalnya:
/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
...
<contentFiles>
<!-- Embed image resources -->
<files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
<files include="any/any/images/ui.png" buildAction="EmbeddedResource" />
<!-- Embed all image resources under contentFiles/cs/ -->
<files include="cs/**/*.png" buildAction="EmbeddedResource" />
<!-- Copy config.xml to the root of the output folder -->
<files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />
<!-- Copy run.cmd to the output folder and keep the directory structure -->
<files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />
<!-- Include everything in the scripts folder except exe files -->
<files include="cs/net45/scripts/*" exclude="**/*.exe" buildAction="None" copyToOutput="true" />
</contentFiles>
</metadata>
</package>
PackageReference versi 5.1+ wih saja
Referensi Kerangka Kerja adalah konsep .NET Core yang mewakili kerangka kerja bersama seperti WPF atau Formulir Windows. Dengan menentukan kerangka kerja bersama, paket memastikan bahwa semua dependensi kerangka kerjanya disertakan dalam proyek referensi.
Setiap <group>
elemen memerlukan targetFramework
atribut dan elemen nol atau lebih <frameworkReference>
.
Contoh berikut menunjukkan nuspec yang dihasilkan untuk proyek .NET Core WPF. Perhatikan bahwa nuspec penulisan tangan yang berisi referensi kerangka kerja tidak disarankan. Pertimbangkan untuk menggunakan paket target sebagai gantinya, yang akan secara otomatis menyimpulkannya dari proyek.
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
<metadata>
<dependencies>
<group targetFramework=".NETCoreApp3.1" />
</dependencies>
<frameworkReferences>
<group targetFramework=".NETCoreApp3.1">
<frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
</group>
</frameworkReferences>
</metadata>
</package>
Sederhana .nuspec
yang tidak menentukan dependensi atau file
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
<id>sample</id>
<version>1.2.3</version>
<authors>Kim Abercrombie, Franck Halmaert</authors>
<description>Sample exists only to show a sample .nuspec file.</description>
<language>en-US</language>
<projectUrl>http://xunit.codeplex.com/</projectUrl>
<license type="expression">MIT</license>
</metadata>
</package>
A .nuspec
dengan dependensi
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
<id>sample</id>
<version>1.0.0</version>
<authors>Microsoft</authors>
<dependencies>
<dependency id="another-package" version="3.0.0" />
<dependency id="yet-another-package" version="1.0.0" />
</dependencies>
</metadata>
</package>
A .nuspec
dengan file
<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
<id>routedebugger</id>
<version>1.0.0</version>
<authors>Jay Hamlin</authors>
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>Route Debugger is a little utility I wrote...</description>
</metadata>
<files>
<file src="bin\Debug\*.dll" target="lib" />
</files>
</package>
dengan .nuspec
rakitan kerangka kerja
<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
<id>PackageWithGacReferences</id>
<version>1.0</version>
<authors>Author here</authors>
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>
A package that has framework assemblyReferences depending
on the target framework.
</description>
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
<frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
<frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
<frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
</frameworkAssemblies>
</metadata>
</package>
Dalam contoh ini, berikut ini diinstal untuk target proyek tertentu:
- . NET4 ->
System.Web
,System.Net
- . Profil Klien NET4 ->
System.Net
- Silverlight 3 ->
System.Json
- WindowsPhone ->
Microsoft.Devices.Sensors