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

Kompatibilitas jenis proyek

• Gunakan .nuspec dengan nuget.exe pack untuk proyek bergaya non-SDK yang menggunakan packages.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 atau msbuild 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 menggunakan dotnet.exe atau msbuild 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.

Bentuk dan skema umum

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.

Elemen metadata yang diperlukan

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 .

id

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

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.

description

Deskripsi paket untuk tampilan UI.

Saat mengunggah paket ke nuget.org, bidang dibatasi description hingga 4000 karakter.

penulis

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.

Elemen metadata opsional

Pemilik

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.

projectUrl

URL untuk beranda paket, sering ditampilkan di tampilan UI serta nuget.org.

Saat mengunggah paket ke nuget.org, bidang dibatasi projectUrl hingga 4000 karakter.

licenseUrl

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.

lisensi

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)

iconUrl

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.

ikon

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>

Sampel nuspec Ikon Paket.

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.

readme

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.

requireLicenseAcceptance

Nilai Boolean yang menentukan apakah klien harus meminta konsumen untuk menerima lisensi paket sebelum menginstal paket.

developmentDependency

(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

ringkasan

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.

releaseNotes

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

hak cipta

(1.5+) Detail hak cipta untuk paket.

Saat mengunggah paket ke nuget.org, bidang dibatasi copyright hingga 4000 karakter.

bahasa

ID lokal untuk paket. Lihat Membuat paket yang dilokalkan.

tag

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.

berguna

(3.3+) Hanya untuk penggunaan NuGet internal.

repositori

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.

title

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.

Elemen koleksi

packageTypes

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

dependensi

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.

frameworkAssemblies

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

referensi

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

contentFiles

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

file

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.

atribut metadata

minClientVersion

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>

Token pengganti

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 Dependensi

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

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

Referensi rakitan eksplisit

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>

Grup referensi

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>

Referensi perakitan kerangka kerja

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>

Termasuk file assembly

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.

Atribut elemen file

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, , contentbuild, 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.

Contoh

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)

Menyertakan file konten

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.

Menggunakan elemen file untuk file konten

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)

Menggunakan elemen contentFiles untuk file konten

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, , NoneEmbedded 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.

Struktur folder paket

Proyek paket harus menyusun konten menggunakan pola berikut:

/contentFiles/{codeLanguage}/{TxM}/{any?}

• codeLanguagesmungkin cs, , vbfs, 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/.

Contoh bagian contentFiles

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

Grup referensi kerangka kerja

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>

Contoh file nuspec

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