Mendukung beberapa versi .NET

  • Artikel

Banyak pustaka menargetkan versi tertentu dari .NET Framework. Misalnya, Anda mungkin memiliki satu versi pustaka yang khusus untuk UWP, dan versi lain yang memanfaatkan fitur di .NET Framework 4.6. Untuk mengakomodasi hal ini, NuGet mendukung menempatkan beberapa versi pustaka yang sama dalam satu paket.

Artikel ini menjelaskan tata letak paket NuGet, terlepas dari bagaimana paket atau rakitan dibangun (artinya, tata letaknya sama baik menggunakan beberapa file .csproj gaya non-SDK dan file .nuspec kustom, atau satu file .csproj gaya SDK multi-target). Untuk proyek gaya SDK, target paket NuGet tahu bagaimana paket harus ditata dan mengotomatiskan menempatkan rakitan di folder lib yang benar dan membuat grup dependensi untuk setiap kerangka kerja target (TFM). Untuk instruksi mendetail, lihat Mendukung beberapa versi .NET Framework dalam file proyek Anda.

Anda harus secara manual menjabarkan paket seperti yang dijelaskan dalam artikel ini saat menggunakan metode direktori kerja berbasis konvensi yang dijelaskan dalam Membuat paket. Untuk proyek gaya SDK, metode otomatis disarankan, tetapi Anda juga dapat memilih untuk menjabarkan paket secara manual seperti yang dijelaskan dalam artikel ini.

Struktur folder versi kerangka kerja

Saat membuat paket yang hanya berisi satu versi pustaka atau menargetkan beberapa kerangka kerja, Anda selalu membuat subfolder di bawah lib menggunakan nama kerangka kerja peka huruf besar/kecil yang berbeda dengan konvensi berikut:

lib\{framework name}[{version}]

Untuk daftar lengkap nama yang didukung, lihat referensi Kerangka Kerja Target.

Anda tidak boleh memiliki versi pustaka yang tidak spesifik untuk kerangka kerja dan ditempatkan langsung di folder akar lib . (Kemampuan ini hanya didukung dengan packages.config). Melakukannya akan membuat pustaka kompatibel dengan kerangka kerja target apa pun dan memungkinkannya diinstal di mana saja, kemungkinan mengakibatkan kesalahan runtime yang tidak terduga. Menambahkan rakitan di folder akar (seperti lib\abc.dll) atau subfolder (seperti lib\abc\abc.dll) telah tidak digunakan lagi dan diabaikan saat menggunakan format PackagesReference.

Misalnya, struktur folder berikut mendukung empat versi rakitan yang khusus untuk kerangka kerja:

\lib
    \net46
        \MyAssembly.dll
    \net461
        \MyAssembly.dll
    \uap
        \MyAssembly.dll
    \netcore
        \MyAssembly.dll

Untuk menyertakan semua file ini dengan mudah saat membuat paket, gunakan wildcard rekursif ** di bagian <files> Anda .nuspec:

<files>
    <file src="lib\**" target="lib/{framework name}[{version}]" />
</files>

Folder khusus arsitektur

Jika Anda memiliki rakitan khusus arsitektur, yaitu, rakitan terpisah yang menargetkan ARM, x86, dan x64, Anda harus menempatkannya di folder bernama runtimes dalam sub-folder bernama {platform}-{architecture}\lib\{framework} atau {platform}-{architecture}\native. Misalnya, struktur folder berikut akan mengakomodasi DLL asli dan terkelola yang menargetkan Windows 10 dan uap10.0 kerangka kerja:

\runtimes
    \win10-arm
        \native
        \lib\uap10.0
    \win10-x86
        \native
        \lib\uap10.0
    \win10-x64
        \native
        \lib\uap10.0

Rakitan ini hanya akan tersedia pada runtime, jadi jika Anda ingin menyediakan rakitan waktu kompilasi yang sesuai juga maka memiliki AnyCPU perakitan dalam /ref/{tfm} folder.

Harap dicatat, NuGet selalu memilih aset kompilasi atau runtime ini dari satu folder sehingga jika ada beberapa aset yang kompatibel dari /ref itu akan /lib diabaikan untuk menambahkan rakitan waktu kompilasi. Demikian pula, jika ada beberapa aset yang kompatibel dari /runtimes saat itu juga /lib akan diabaikan untuk runtime.

Lihat Membuat Paket UWP untuk contoh mereferensikan file-file ini dalam .nuspec manifes.

Selain itu, lihat Mengemas komponen aplikasi toko Windows dengan NuGet

Mencocokkan versi rakitan dan kerangka kerja target dalam proyek

Ketika NuGet menginstal paket yang memiliki beberapa versi rakitan, NuGet mencoba mencocokkan nama kerangka kerja rakitan dengan kerangka kerja target proyek.

Jika kecocokan tidak ditemukan, NuGet menyalin rakitan untuk versi tertinggi yang kurang dari atau sama dengan kerangka kerja target proyek, jika tersedia. Jika tidak ada rakitan yang kompatibel yang ditemukan, NuGet mengembalikan pesan kesalahan yang sesuai.

Misalnya, pertimbangkan struktur folder berikut dalam paket:

\lib
    \net45
        \MyAssembly.dll
    \net461
        \MyAssembly.dll

Saat menginstal paket ini dalam proyek yang menargetkan .NET Framework 4.6, NuGet menginstal rakitan di net45 folder, karena itu adalah versi tertinggi yang tersedia yang kurang dari atau sama dengan 4.6.

Jika proyek menargetkan .NET Framework 4.6.1, di sisi lain, NuGet menginstal rakitan di net461 folder .

Jika proyek menargetkan .NET framework 4.0 dan yang lebih lama, NuGet melempar pesan kesalahan yang sesuai untuk tidak menemukan rakitan yang kompatibel.

Mengelompokkan rakitan menurut versi kerangka kerja

NuGet menyalin rakitan hanya dari satu folder pustaka dalam paket. Misalnya, misalkan paket memiliki struktur folder berikut:

\lib
    \net40
        \MyAssembly.dll (v1.0)
        \MyAssembly.Core.dll (v1.0)
    \net45
        \MyAssembly.dll (v2.0)

Ketika paket diinstal dalam proyek yang menargetkan .NET Framework 4.5, MyAssembly.dll (v2.0) adalah satu-satunya rakitan yang diinstal. MyAssembly.Core.dll (v1.0) tidak diinstal karena tidak tercantum dalam net45 folder. NuGet berulah dengan cara ini karena MyAssembly.Core.dll mungkin telah digabungkan ke dalam versi 2.0 dari MyAssembly.dll.

Jika Anda ingin MyAssembly.Core.dll diinstal untuk .NET Framework 4.5, tempatkan salinan di net45 folder .

Mengelompokkan rakitan menurut profil kerangka kerja

NuGet juga mendukung penargetan profil kerangka kerja tertentu dengan menambahkan tanda hubung dan nama profil ke akhir folder.

lib{framework name}-{profile}

Profil yang didukung adalah sebagai berikut:

  • client: Profil Klien
  • full: Profil Lengkap
  • wp: Windows Telepon
  • cf: Kerangka Kerja Ringkas

Mendeklarasikan dependensi (Tingkat Lanjut)

Saat mengemas file proyek, NuGet mencoba membuat dependensi dari proyek secara otomatis. Informasi di bagian ini tentang menggunakan file .nuspec untuk menyatakan dependensi biasanya diperlukan untuk skenario tingkat lanjut saja.

(Versi 2.0+) Anda dapat mendeklarasikan dependensi paket dalam .nuspec yang sesuai dengan kerangka kerja target proyek target menggunakan <group> elemen dalam <dependencies> elemen . Untuk informasi selengkapnya, lihat elemen dependensi.

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. Lihat Kerangka kerja target untuk pengidentifikasi kerangka kerja yang tepat.

Sebaiknya gunakan satu grup per Target Framework Moniker (TFM) untuk file di folder lib/ dan ref/ .

Contoh berikut menunjukkan variasi elemen yang <group> berbeda:

<dependencies>

    <group targetFramework="net472">
        <dependency id="jQuery" version="1.10.2" />
        <dependency id="WebActivatorEx" version="2.2.0" />
    </group>

    <group targetFramework="net20">
    </group>

</dependencies>

Menentukan target NuGet mana yang akan digunakan

Ketika pustaka pengemasan yang menargetkan Pustaka Kelas Portabel, mungkin sulit untuk menentukan target NuGet mana yang harus Anda gunakan dalam nama dan .nuspec file folder Anda, terutama jika hanya menargetkan subset PCL. Sumber daya eksternal berikut akan membantu Anda dengan ini:

  • Profil kerangka kerja di .NET (stephencleary.com)
  • Profil Pustaka Kelas Portabel (plnkr.co): Tabel yang menghitung profil PCL dan target NuGet yang setara
  • Alat profil Pustaka Kelas Portabel (github.com): alat baris perintah untuk menentukan profil PCL yang tersedia di sistem Anda

File konten dan skrip PowerShell

Peringatan

File konten yang dapat diubah dan eksekusi skrip hanya tersedia dengan packages.config format; file tersebut tidak digunakan lagi dengan semua format lain dan tidak boleh digunakan untuk paket baru apa pun.

Dengan packages.config, file konten dan skrip PowerShell dapat dikelompokkan menurut kerangka kerja target menggunakan konvensi folder yang sama di dalam content folder dan tools . Contohnya:

\content
    \net46
        \MyContent.txt
    \net461
        \MyContent461.txt
    \uap
        \MyUWPContent.html
    \netcore
\tools
    init.ps1
    \net46
        install.ps1
        uninstall.ps1
    \uap
        install.ps1
        uninstall.ps1

Jika folder kerangka kerja dibiarkan kosong, NuGet tidak menambahkan referensi perakitan atau file konten atau menjalankan skrip PowerShell untuk kerangka kerja tersebut.

Catatan

Karena init.ps1 dijalankan pada tingkat solusi dan tidak tergantung pada proyek, itu harus ditempatkan langsung di tools bawah folder. Ini diabaikan jika ditempatkan di bawah folder kerangka kerja.