許多程式庫都以特定版本的 .NET Framework 為目標。 例如,您可能有一個特定於 UWP 的程式庫版本,以及另一個利用 .NET Framework 4.6 中功能的版本。 為了因應這一點,NuGet 支援將相同程式庫的多個版本放在單一套件中。
本文說明 NuGet 套件的版面配置,不論套件或元件的建置方式為何 (也就是說,無論是使用多個非 SDK 樣式 的 .csproj 檔案和自訂 .nuspec 檔案,還是單一多目標 SDK 樣式 的 .csproj,版面配置都是相同的)。 針對 SDK 樣式專案,NuGet 套件目標 會知道如何配置套件,並自動將元件放在正確的 lib 資料夾中,並為每個目標架構 (TFM) 建立相依性群組。 如需詳細指示,請參閱 在專案檔中支援多個 .NET Framework 版本。
使用 建立套件中所述的慣例型工作目錄方法時,您必須按照本文所述手動配置套件。 對於 SDK 樣式專案,建議使用自動化方法,但您也可以選擇手動配置套件,如本文所述。
框架版本資料夾結構
建置僅包含一個程式庫版本或以多個架構為目標的套件時,您應在lib 下建立子資料夾,並採用不同區分大小寫的架構名稱來命名,遵循下列慣例:
lib\{framework name}[{version}]
如需支援名稱的完整清單,請參閱 目標架構參考。
您永遠不應使用不專屬於特定架構且直接放置於根目錄的程式庫版本。 (此功能的支援僅限於 packages.config)。 這樣做會讓程式庫與任何目標架構相容,並允許它安裝在任何地方,這可能會導致非預期的執行階段錯誤。 在根資料夾(例如 lib\abc.dll)或子資料夾(例如 lib\abc\abc.dll)中新增元件已被不建議使用,且在使用 PackagesReference 格式時會被忽略。
例如,下列資料夾結構支援四個針對特定框架的元件版本:
\lib
\net46
\MyAssembly.dll
\net461
\MyAssembly.dll
\uap
\MyAssembly.dll
\netcore
\MyAssembly.dll
若要在建置套件時輕鬆包括所有這些檔案,請在**部分的<files>中使用遞迴萬用字元.nuspec。
<files>
<file src="lib\**" target="lib/{framework name}[{version}]" />
</files>
架構特定的資料夾
如果您有架構特定的元件,也就是以 ARM、x86 和 x64 為目標的個別元件,您必須將它們放在名為 runtimes 或 {platform}-{architecture}\lib\{framework}的子資料夾內名為{platform}-{architecture}\native的資料夾中。 例如,下列資料夾結構會同時容納以 Windows 10 和 uap10.0 架構為目標的原生和受控 DLL:
\runtimes
\win10-arm
\native
\lib\uap10.0
\win10-x86
\native
\lib\uap10.0
\win10-x64
\native
\lib\uap10.0
**
這些組件只會在執行階段提供,因此如果您也想要提供相應的編譯時期組件,請確保在/ref/{tfm}資料夾中包含AnyCPU組件。
請注意,NuGet 總是從一個資料夾中選擇這些編譯或執行階段資產,如果有一些來自/ref的相容資產,那麼來自/lib的資產將會被忽略,以便選擇編譯階段的元件。 同樣地,如果/runtimes中的某些資產是相容的,則/lib在執行階段會被忽略。
如需在資訊清單中參考這些檔案的範例,請參閱建立 UWP 套件。
另請參閱 使用 NuGet 封裝 Windows 市集應用程式元件
專案中組件版本與目標架構的匹配
當 NuGet 安裝具有多個元件版本的套件時,它會嘗試將元件的架構名稱與專案的目標架構相符。
如果找不到匹配的版本,NuGet 會複製小於或等於專案目標框架的可用最高版本的元件(如果有的話)。 如果找不到相容的元件,NuGet 會傳回適當的錯誤訊息。
例如,請考慮套件中的下列資料夾結構:
\lib
\net45
\MyAssembly.dll
\net461
\MyAssembly.dll
在以 .NET Framework 4.6 為目標的專案中安裝此套件時,NuGet 會在資料夾中 net45 安裝元件,因為這是小於或等於 4.6 的最高可用版本。
另一方面,如果專案以 .NET Framework 4.6.1 為目標,NuGet 會在 net461 資料夾中安裝組件。
如果專案以 .NET Framework 4.0 和更早版本為目標,NuGet 會擲回找不到相容元件的適當錯誤訊息。
依架構版本將元件分組
NuGet 只會從套件中的單一程式庫資料夾複製元件。 例如,假設套件具有下列資料夾結構:
\lib
\net40
\MyAssembly.dll (v1.0)
\MyAssembly.Core.dll (v1.0)
\net45
\MyAssembly.dll (v2.0)
當套件安裝在以 .NET Framework 4.5 為目標的專案中時, MyAssembly.dll (v2.0) 是唯一安裝的元件。
MyAssembly.Core.dll (v1.0)未安裝,因為它未列在net45資料夾中。 NuGet 會以這種方式行事,因為 MyAssembly.Core.dll 可能已合併到 2.0 版的 MyAssembly.dll.
如果您要 MyAssembly.Core.dll 在 .NET Framework 4.5 上安裝,請在 net45 資料夾中放置一個複本。
依架構設定檔將元件分組
NuGet 也支援透過在資料夾結尾附加破折號和設定檔名稱來指定特定框架設定檔為目標。
lib{框架名稱}-{設定檔}
支援的設定檔如下:
-
client: 客戶簡介 -
full:完整個人資料 -
wp:Windows 手機 -
cf:緊湊的框架
宣告相依性 (進階)
封裝專案檔案時,NuGet 會嘗試自動從專案產生相依性。 本節中有關使用 .nuspec 檔案宣告相依性的資訊通常僅適用於進階案例。
(版本 2.0+)您可以在與目標專案的目標架構對應的 <dependencies> 裡,使用<group>元素內的元素來宣告套件相依性。 如需詳細資訊,請參閱 相依性元素。
每個群組都有一個名為 targetFramework 的屬性,並包含零個或多個 <dependency> 元素。 當目標架構與專案的架構設定檔相容時,這些相依性會一起安裝。 如需確切的架構識別碼,請參閱 Target 架構。
建議您對於 lib/ 和 ref/ 資料夾中的檔案,每個目標架構名稱(TFM)使用一個群組。
下列範例顯示不同的 <group> 元素變化:
<dependencies>
<group targetFramework="net472">
<dependency id="jQuery" version="1.10.2" />
<dependency id="WebActivatorEx" version="2.2.0" />
</group>
<group targetFramework="net20">
</group>
</dependencies>
判斷要使用的 NuGet 目標
封裝以可攜式類別程式庫為目標的程式庫時,判斷您應該在資料夾名稱和 .nuspec 檔案中使用哪個 NuGet 目標可能會很棘手,特別是如果只以 PCL 的子集為目標。 以下外部資源將幫助您解決此問題:
- .NET 中的架構設定檔 (stephencleary.com)
- 可攜式類別程式庫設定檔 (plnkr.co):列舉 PCL 設定檔及其對等 NuGet 目標的資料表
- 可攜式類別庫設定檔工具 (github.com):用於判斷系統上可用的 PCL 設定檔的指令行工具
內容檔案和 PowerShell 指令碼
警告
可變內容檔案和指令碼執行僅適用於該 packages.config 格式;它們已與所有其他格式一起被取代,並且不應用於任何新套件。
使用 packages.config,內容檔案和 PowerShell 腳本可以依照 content 和 tools 資料夾內的相同資料夾慣例,依目標架構分組。 例如:
\content
\net46
\MyContent.txt
\net461
\MyContent461.txt
\uap
\MyUWPContent.html
\netcore
\tools
init.ps1
\net46
install.ps1
uninstall.ps1
\uap
install.ps1
uninstall.ps1
如果架構資料夾保留空白,NuGet 不會新增元件參考或內容檔案,或執行該架構的 PowerShell 腳本。
備註
因為 init.ps1 在解決方案層級執行,並且不依賴於專案,所以必須直接放在 tools 資料夾下。 如果將其放置在框架資料夾下,則會忽略它。