NuGet 套件和還原為 MSBuild 目標
NuGet 4.0+
使用 PackageReference 格式, NuGet 4.0+ 可以直接將所有指令清單元數據儲存在專案檔內,而不是使用不同的.nuspec
檔案。
MSBuild 15.1+ 也是具有 和 restore
目標的一流MSBuild公民pack
,NuGet如下所述。 這些目標可讓您像處理任何其他MSBuild工作或目標一樣使用NuGet。 如需使用 建立NuGet封裝的指示,請參閱使用 MSBuild建立NuGetMSBuild套件。 (針對NuGet3.x 和更早版本,您可以改為透過 NuGet CLI 使用套件和還原命令。
由於 pack
和 restore
是 MSBuild 目標,因此您可以存取它們來增強您的工作流程。 例如,假設您想要在封裝套件之後將套件複製到網路共用。 做法是在專案檔中新增下列項目:
<Target Name="CopyPackage" AfterTargets="Pack">
<Copy
SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
DestinationFolder="\\myshare\packageshare\"
/>
</Target>
同樣地,您可以撰寫工作MSBuild、撰寫自己的目標,並在工作中取用NuGetMSBuild屬性。
注意
$(OutputPath)
是相對的,而且預期您正在從專案根目錄執行命令。
針對使用 格式的 PackageReference
.NET 專案,使用 msbuild -t:pack
從專案檔繪製輸入,以用於建立 NuGet 套件。
下表描述 MSBuild 可新增至第一 <PropertyGroup>
個節點內項目檔的屬性。 以滑鼠右鍵按一下專案,然後選取操作功能表上的 [編輯 {project_name}],即可在 Visual Studio 2017 和更新版本中輕鬆地進行這些編輯。 為了方便起見,數據表是由檔案中的.nuspec
對等屬性所組織。
注意
Owners
不支援 來自 .nuspec
MSBuild的和 Summary
屬性。
屬性/nuspec 值 | MSBuild 屬性 | 預設 | 備註 |
---|---|---|---|
Id |
PackageId |
$(AssemblyName) |
MSBuild 中的 $(AssemblyName) |
Version |
PackageVersion |
版本 | 這與 semver 相容,例如 1.0.0 、 1.0.0-beta 或 1.0.0-beta-00345 。 如果未設定,則預設為 Version 。 |
VersionPrefix |
VersionPrefix |
empty | 設定 PackageVersion 覆寫 VersionPrefix |
VersionSuffix |
VersionSuffix |
empty | 設定 PackageVersion 覆寫 VersionSuffix |
Authors |
Authors |
目前使用者的使用者名稱 | 以分號分隔的套件作者清單,符合 .org 上的nuget配置檔名稱。這些會顯示在 .org 上的NuGetnuget資源庫中,並用來由相同的作者交叉參考套件。 |
Owners |
N/A | 不存在於 nuspec | |
Title |
Title |
$(PackageId) |
套件的易記標題,通常會在UI中顯示為 .org和nugetVisual Studio中的 封裝管理員。 |
Description |
Description |
"Package Description" | 組件的完整描述。 如果未 PackageDescription 指定,則這個屬性也會當做封裝的描述使用。 |
Copyright |
Copyright |
empty | 套件的著作權詳細資料。 |
RequireLicenseAcceptance |
PackageRequireLicenseAcceptance |
false |
布林值,指定在安裝套件時,用戶端是否必須提示取用者接受套件授權。 |
license |
PackageLicenseExpression |
empty | 對應至 <license type="expression"> 。 請參閱 封裝授權表達式或授權檔。 |
license |
PackageLicenseFile |
empty | 如果您使用自定義授權或尚未指派 SPDX 識別碼的授權,則套件內授權檔案的路徑。 您必須明確封裝參考的授權檔案。 對應至 <license type="file"> 。 請參閱 封裝授權表達式或授權檔。 |
LicenseUrl |
PackageLicenseUrl |
empty | PackageLicenseUrl 已被取代。 請改用 PackageLicenseExpression 或 PackageLicenseFile 。 |
ProjectUrl |
PackageProjectUrl |
empty | |
Icon |
PackageIcon |
empty | 封裝中要做為封裝圖示的影像路徑。 您必須明確地封裝參考的圖示圖像檔。 如需詳細資訊,請參閱 封裝圖示圖像檔 案和 icon 元數據。 |
IconUrl |
PackageIconUrl |
empty | 已淘汰 PackageIconUrl 而改用 PackageIcon 。 不過,為了獲得最佳的下層體驗,除了 之外,您也應該指定 PackageIconUrl PackageIcon 。 |
Readme |
PackageReadmeFile |
empty | 您必須明確地封裝參考的自述檔。 |
Tags |
PackageTags |
empty | 以分號分隔的標記清單,用以指定套件。 |
ReleaseNotes |
PackageReleaseNotes |
empty | 套件的版本資訊。 |
Repository/Url |
RepositoryUrl |
empty | 用來複製或擷取原始程式碼的存放庫 URL。 範例: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git。 |
Repository/Type |
RepositoryType |
empty | 存放庫類型。 範例: git (預設值), tfs 。 |
Repository/Branch |
RepositoryBranch |
empty | 選擇性存放庫分支資訊。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: master (NuGet 4.7.0+)。 |
Repository/Commit |
RepositoryCommit |
empty | 選擇性的存放庫認可或變更集,表示要針對哪個來源建置套件。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+)。 |
PackageType |
<PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> |
指出套件的預期用途。 封裝類型使用與套件識別碼相同的格式,並以 分隔 ; 。 封裝類型可以藉由附加 , 和 Version 字串來建立版本。 請參閱 設定 NuGet 套件類型 (NuGet 3.5.0+)。 |
|
Summary |
不支援 |
屬性 | 說明 |
---|---|
IsPackable |
布林值,指定是否可封裝專案。 預設值是 true 。 |
SuppressDependenciesWhenPacking |
設定為 , true 以隱藏所 NuGet 產生封裝的套件相依性。 |
PackageVersion |
指定所產生之套件的版本。 接受所有形式的 NuGet 版本字串。 預設為 $(Version) 的值,也就是專案中的屬性 Version 。 |
PackageId |
指定所產生之套件的名稱。 如果未指定,pack 作業會預設為使用 AssemblyName 或目錄名稱作為套件的名稱。 |
PackageDescription |
UI 顯示中的套件詳細描述。 |
Authors |
以分號分隔的套件作者清單,符合 .org 上的nuget配置檔名稱。這些會顯示在 .org 上的NuGetnuget資源庫中,並用來由相同的作者交叉參考套件。 |
Description |
組件的完整描述。 如果未 PackageDescription 指定,則這個屬性也會當做封裝的描述使用。 |
Copyright |
套件的著作權詳細資料。 |
PackageRequireLicenseAcceptance |
布林值,指定在安裝套件時,用戶端是否必須提示取用者接受套件授權。 預設值為 false 。 |
DevelopmentDependency |
布爾值,指定封裝是否標示為僅限開發相依性,這可防止封裝在其他套件中包含為相依性。 使用 PackageReference (NuGet 4.8+),此旗標也表示編譯時間資產會排除在編譯之外。 如需詳細資訊,請參閱 PackageReference 的 DevelopmentDependency 支援 \(英文\)。 |
PackageLicenseExpression |
SPDX 授權識別碼或表示式,例如 Apache-2.0 。 如需詳細資訊,請參閱 封裝授權表達式或許可證檔。 |
PackageLicenseFile |
如果您使用自定義授權或尚未指派 SPDX 識別碼的授權,則套件內授權檔案的路徑。 |
PackageLicenseUrl |
PackageLicenseUrl 已被取代。 請改用 PackageLicenseExpression 或 PackageLicenseFile 。 |
PackageProjectUrl |
|
PackageIcon |
指定套件圖示路徑,相對於封裝的根目錄。 如需詳細資訊,請參閱 封裝圖示圖像檔。 |
PackageReleaseNotes |
套件的版本資訊。 |
PackageReadmeFile |
封裝的自述檔。 |
PackageTags |
以分號分隔的標記清單,用以指定套件。 |
PackageOutputPath |
決定要置放所封裝之套件的輸出路徑。 預設值為 $(OutputPath) 。 |
IncludeSymbols |
此布林值會指出在封裝專案時,套件是否應該建立額外的符號套件。 符號套件的格式由 SymbolPackageFormat 屬性控制。 如需詳細資訊,請參閱 IncludeSymbols。 |
IncludeSource |
此布林值會指出封裝處理序是否應該建立來源套件。 來源套件包含程式庫的原始程式碼及 PDB 檔案。 原始程式檔會放在所產生之套件檔案中的 src/ProjectName 目錄底下。 如需詳細資訊,請參閱 IncludeSource。 |
PackageType |
|
IsTool |
指定是否要將所有輸出檔複製到 tools 資料夾,而不是 lib 資料夾。 如需詳細資訊,請參閱 IsTool。 |
RepositoryUrl |
用來複製或擷取原始程式碼的存放庫 URL。 範例: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git。 |
RepositoryType |
存放庫類型。 範例: git (預設值), tfs 。 |
RepositoryBranch |
選擇性存放庫分支資訊。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: master (NuGet 4.7.0+)。 |
RepositoryCommit |
選擇性的存放庫認可或變更集,表示要針對哪個來源建置套件。 RepositoryUrl 也必須指定這個屬性才能包含。 範例: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+)。 |
SymbolPackageFormat |
指定符號套件的格式。 如果為 「symbols.nupkg」,則會使用 包含 PDB、DLL 和其他輸出檔案的 .symbols.nupkg 擴展名來建立舊版符號套件。 如果為 「snupkg」,則會建立包含可攜式 PDB 的 snupkg 符號套件。 默認值為 「symbols.nupkg」。。 |
NoPackageAnalysis |
指定 pack 在建置封裝之後,不應執行封裝分析。 |
MinClientVersion |
指定可安裝此套件的NuGet用戶端最低版本,.exenuget和 Visual Studio 封裝管理員 強制執行。 |
IncludeBuildOutput |
這個布爾值會指定組建輸出元件是否應該封裝到 .nupkg 檔案中。 |
IncludeContentInPack |
這個布爾值會指定是否將具有 型 Content 別的任何項目自動包含在產生的封裝中。 預設值為 true 。 |
BuildOutputTargetFolder |
指定要放置輸出組件的資料夾。 輸出組件 (及其他輸出檔) 會複製到其相關的架構資料夾中。 如需詳細資訊,請參閱 輸出元件。 |
ContentTargetFolders |
指定如果未為其指定所有內容檔案 PackagePath 的預設位置。 預設值為 "content;contentFiles"。 如需詳細資訊,請參閱 Including content in a package (在套件中包含內容)。 |
NuspecFile |
用於封裝之檔案的 .nuspec 相對或絕對路徑。 如果指定,則會專門用於封裝資訊,而且不會使用專案中的任何資訊。 如需詳細資訊,請參閱 使用 .nuspec封裝。 |
NuspecBasePath |
檔案的 .nuspec 基底路徑。 如需詳細資訊,請參閱 使用 .nuspec封裝。 |
NuspecProperties |
以分號分隔的索引鍵=值組清單。 如需詳細資訊,請參閱 使用 .nuspec封裝。 |
若要隱藏所 NuGet 產生套件的套件相依性,請將 設定 SuppressDependenciesWhenPacking
為 true
,以允許略過產生的 nupkg 檔案中的所有相依性。
PackageIconUrl
已被取代,有利於 PackageIcon
屬性。 從 NuGet 5.3 和 Visual Studio 2019 16.3 版開始,如果套件元數據只指定 PackageIconUrl
,pack
就會引發 NU5048 警告。
提示
若要維持與尚未支援 PackageIcon
之用戶端和來源的回溯相容性,請同時指定 PackageIcon
和 PackageIconUrl
。 Visual Studio 支援 PackageIcon
來自資料夾型來源的套件。
封裝圖示圖像檔案時,請使用 PackageIcon
屬性來指定圖示檔案路徑,相對於封裝的根目錄。 此外,請確定檔案包含在套件中。 圖像檔案大小限制為 1 MB。 支援的檔案格式包括 JPEG 和 PNG。 我們建議影像解析度為128x128。
例如:
<PropertyGroup>
...
<PackageIcon>icon.png</PackageIcon>
...
</PropertyGroup>
<ItemGroup>
...
<None Include="images\icon.png" Pack="true" PackagePath="\"/>
...
</ItemGroup>
針對對等專案 nuspec ,請查看 nuspec 圖示的參考。
NuGet支援 5.10.0 Preview 2.NET / SDK 5.0.300 和更新版本
封裝自述檔時,您必須使用 PackageReadmeFile
屬性來指定套件路徑,相對於封裝的根目錄。 除此之外,您必須確定檔案已包含在套件中。 支援的檔案格式只包含 Markdown (.md)。
例如:
<PropertyGroup>
...
<PackageReadmeFile>readme.md</PackageReadmeFile>
...
</PropertyGroup>
<ItemGroup>
...
<None Include="docs\readme.md" Pack="true" PackagePath="\"/>
...
</ItemGroup>
針對對等專案 nuspec ,請查看 nuspec 自述文件參考。
nuget pack
會複製副檔名為 .exe
、.dll
、.xml
、.winmd
、.json
和 .pri
的輸出檔案。 複製的輸出檔案取決於目標所提供的BuiltOutputProjectGroup
內容MSBuild。
您可以在項目檔或命令列中使用兩 MSBuild 個屬性來控制輸出元件的位置:
IncludeBuildOutput
:布林值,決定是否應該在套件中包含組建輸出組件。BuildOutputTargetFolder
:指定應該在其中放置輸出組件的資料夾。 輸出組件 (及其他輸出檔) 會複製到其相關的架構資料夾中。
請參閱專案檔中的套件參考。
專案對專案參考預設 NuGet 會視為套件參考。 例如:
<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>
您也可以將下列中繼資料新增至您的專案參考:
<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>
若要包含內容,請將額外的中繼資料新增至現有的 <Content>
項目。 除非您覆寫為下列這類項目,否則 "Content" 類型的所有項目預設都會包含在套件中:
<Content Include="..\win7-x64\libuv.txt">
<Pack>false</Pack>
</Content>
除非您指定套件路徑,否則所有項目預設都會新增至套件內的 content
和 contentFiles\any\<target_framework>
資料夾根目錄,並保留相對資料夾結構:
<Content Include="..\win7-x64\libuv.txt">
<Pack>true</Pack>
<PackagePath>content\myfiles\</PackagePath>
</Content>
如果您想要只將所有內容複製到特定的根資料夾(而不是 content
和 contentFiles
兩者),您可以使用 MSBuild 屬性 ContentTargetFolders
,其預設為「內容」;contentFiles“ 但可以設定為任何其他資料夾名稱。 請注意,根據 buildAction
,只在 ContentTargetFolders
中指定 "contentFiles" 會將檔案放在 contentFiles\any\<target_framework>
或 contentFiles\<language>\<target_framework>
下方。
PackagePath
可以是以分號分隔的一組目標路徑。 指定空的套件路徑會將檔案新增至套件的根目錄。 例如,下列會將 libuv.txt
新增至 content\myfiles
、content\samples
和套件根目錄:
<Content Include="..\win7-x64\libuv.txt">
<Pack>true</Pack>
<PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>
也有屬性 MSBuild $(IncludeContentInPack)
,預設為 true
。 如果這會在任何項目上設定為 false
,則來自該專案的內容不會包含在封裝中 nuget 。
您可以在上述任何項目上設定的其他套件特定元數據包括 <PackageCopyToOutput>
,以及<PackageFlatten>
輸出 nuspec中專案上的contentFiles
設定CopyToOutput
和Flatten
值。
注意
除了 Content 項目之外,還可以在建置動作為 Compile、EmbeddedResource、ApplicationDefinition、Page、Resource、SplashScreen、DesignData、DesignDataWithDesignTimeCreateableTypes、CodeAnalysisDictionary、AndroidAsset、AndroidResource、BundleResource 或 None 的檔案上設定 <Pack>
和 <PackagePath>
中繼資料。
針對封裝,若要在使用萬用字元模式時將檔案名稱附加至套件路徑,您套件路徑的結尾必須是資料夾分隔符號字元,否則會將套件路徑視為包含檔案名稱的完整路徑。
使用 MSBuild -t:pack -p:IncludeSymbols=true
時,會複製對應的 .pdb
檔案與其他輸出檔案 (.dll
、.exe
、.winmd
、.xml
、.json
、.pri
)。 請注意,設定 IncludeSymbols=true
時會建立一般套件「和」符號套件。
這與 IncludeSymbols
相同,差異在於它也會複製原始程式檔和 .pdb
檔案。 所有 Compile
類型的檔案都會覆寫 src\<ProjectName>\
,並保留所產生套件中的相對路徑資料夾結構。 這也適用於任何 ProjectReference
的原始程式檔,而這些原始程式檔將 TreatAsPackageReference
設定為 false
。
若類型為 Compile 的檔案位於專案資料夾之外,就只會將其新增至 src\<ProjectName>\
。
使用授權表達式時,請使用 PackageLicenseExpression
屬性。 如需範例,請參閱 授權表達式範例。
<PropertyGroup>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>
若要深入瞭解 .org 所接受 NuGet的授權表達式和授權,請參閱 授權元數據。
封裝授權檔案時,請使用 PackageLicenseFile
屬性來指定套件路徑,相對於套件的根目錄。 此外,請確定檔案包含在套件中。 例如:
<PropertyGroup>
<PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>
<ItemGroup>
<None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>
如需範例,請參閱 授權檔案範例。
注意
一次只能指定、 和 PackageLicenseUrl
的PackageLicenseExpression
PackageLicenseFile
其中一個。
在某些情況下,例如封裝授權檔時,您可能會想要包含沒有擴展名的檔案。 基於歷史原因, NuGet 請將 MSBuild 沒有延伸模組的路徑視為目錄。
<PropertyGroup>
<TargetFrameworks>netstandard2.0</TargetFrameworks>
<PackageLicenseFile>LICENSE</PackageLicenseFile>
</PropertyGroup>
<ItemGroup>
<None Include="LICENSE" Pack="true" PackagePath=""/>
</ItemGroup>
沒有延伸模組範例的檔案。
使用 MSBuild -t:pack -p:IsTool=true
時,會將輸出組件案例中所指定的所有輸出檔案都複製至 tools
資料夾,而非 lib
資料夾。 請注意,這與 DotNetCliTool
不同,該項目是在 .csproj
檔案中設定 PackageType
所指定。
雖然建議您改為將通常.nuspec
包含在專案檔中檔案中的所有屬性,但您可以選擇使用.nuspec
檔案來封裝專案。 對於使用 PackageReference
的非 SDK 樣式專案,您必須匯 NuGet.Build.Tasks.Pack.targets
入 ,才能執行套件工作。 您仍然需要還原專案,才能封裝 nuspec 檔案。 (SDK 樣式項目預設包含套件目標。
項目檔的目標架構無關緊要,在封裝 nuspec時不會使用。 下列三 MSBuild 個 .nuspec
屬性與使用 封裝有關:
NuspecFile
:將用於封裝之.nuspec
檔案的相對或絕對路徑。NuspecProperties
:以分號分隔的索引鍵=值組清單。 由於命令行剖析的運作方式 MSBuild ,必須指定多個屬性,如下所示:-p:NuspecProperties="key1=value1;key2=value2"
。NuspecBasePath
:.nuspec
檔案的基底路徑。
如果使用 dotnet.exe
來封裝您的專案,則請使用下列這類命令:
dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>
如果使用 MSBuild 來封裝您的專案,則請使用下列這類命令:
msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>
請注意,使用 dotnet.exe 封裝 nuspec ,或 msbuild 也會導致預設建置專案。 您可以藉由將 --no-build
屬性傳遞至 dotnet.exe,這相當於專案檔中的設定 <NoBuild>true</NoBuild>
,以及專案檔中的設定 <IncludeBuildOutput>false</IncludeBuildOutput>
,來避免這種情況。
封裝檔案的 .csproj 檔案nuspec範例如下:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<NoBuild>true</NoBuild>
<IncludeBuildOutput>false</IncludeBuildOutput>
<NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
<NuspecProperties>add nuspec properties here</NuspecProperties>
<NuspecBasePath>optional to provide</NuspecBasePath>
</PropertyGroup>
</Project>
目標 pack
提供兩個延伸點,可在內部目標架構特定組建中執行。 擴充點支援將目標架構特定內容和元件納入套件:
TargetsForTfmSpecificBuildOutput
目標:用於資料夾內的lib
檔案,或使用 指定的BuildOutputTargetFolder
資料夾。TargetsForTfmSpecificContentInPackage
目標:用於外部的BuildOutputTargetFolder
檔案。
撰寫自定義目標,並將它指定為 屬性的值 $(TargetsForTfmSpecificBuildOutput)
。 針對任何需要進入 BuildOutputTargetFolder
的檔案 (預設為 lib),目標應該將這些檔案寫入 ItemGroup BuildOutputInPackage
,並設定下列兩個元數據值:
FinalOutputPath
:檔案的絕對路徑;如果未提供,則會使用身分識別來評估來源路徑。TargetPath
:(選擇性) 設定檔案何時需要進入 內的lib\<TargetFramework>
子資料夾,例如位於其個別文化資料夾下的附屬元件。 預設為檔名。
範例:
<PropertyGroup>
<TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>
<Target Name="GetMyPackageFiles">
<ItemGroup>
<BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
<TargetPath>cs</TargetPath>
</BuildOutputInPackage>
</ItemGroup>
</Target>
撰寫自定義目標,並將它指定為 屬性的值 $(TargetsForTfmSpecificContentInPackage)
。 針對要包含在封裝中的任何檔案,目標應該將這些檔案寫入 ItemGroup TfmSpecificPackageFile
,並設定下列選擇性元數據:
PackagePath
:檔案應在封裝中輸出的路徑。 NuGet 如果將多個檔案新增至相同的套件路徑,就會發出警告。BuildAction
:要指派給檔案的建置動作,只有在封裝路徑位於contentFiles
資料夾中時才需要。 預設為 「None」。。
範例:
<PropertyGroup>
<TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>
<Target Name="CustomContentTarget">
<ItemGroup>
<TfmSpecificPackageFile Include="abc.txt">
<PackagePath>mycontent/$(TargetFramework)</PackagePath>
</TfmSpecificPackageFile>
<TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
<PackagePath>net46content</PackagePath>
</TfmSpecificPackageFile>
</ItemGroup>
</Target>
MSBuild -t:restore
(nuget restore
和 dotnet restore
與 .NET Core 專案搭配使用) 會還原專案檔中所參考的套件,如下所示:
- 讀取所有專案對專案參考
- 讀取專案屬性來尋找中繼資料夾和目標架構
- 將資料傳遞 MSBuild 至 NuGet。Build.Tasks.dll
- 執行還原
- 下載套件
- 撰寫資產檔案、目標和屬性
目標 restore
適用於使用 PackageReference 格式的專案。
MSBuild 16.5+
也支援packages.config
格式。
注意
目標restore
不應與build
目標結合執行。
其他還原設定可能來自 MSBuild 項目檔中的屬性。 您也可以從命令列,使用 -p:
參數設定值 (請參閱下列<範例>)。
屬性 | 說明 |
---|---|
RestoreSources |
以分號分隔的套件來源清單。 |
RestorePackagesPath |
使用者套件資料夾路徑。 |
RestoreDisableParallel |
限制逐一進行下載。 |
RestoreConfigFile |
要套用之 Nuget.Config 檔案的路徑。 |
RestoreNoHttpCache |
如果為 true,請避免使用 HTTP 快取套件。 請參閱 管理全域套件和快取資料夾。 |
RestoreIgnoreFailedSources |
如果為 true,請忽略失敗或遺漏的套件來源。 |
RestoreFallbackFolders |
後援資料夾,與使用者套件資料夾使用的方式相同。 |
RestoreAdditionalProjectSources |
還原期間要使用的其他來源。 |
RestoreAdditionalProjectFallbackFolders |
還原期間要使用的其他後援資料夾。 |
RestoreAdditionalProjectFallbackFoldersExcludes |
排除 中指定的後援資料夾 RestoreAdditionalProjectFallbackFolders |
RestoreTaskAssemblyFile |
NuGet.Build.Tasks.dll 的路徑。 |
RestoreGraphProjectInput |
要還原的專案清單 (以分號分隔),其中應包含絕對路徑。 |
RestoreUseSkipNonexistentTargets |
透過收集 MSBuild 專案時,會決定是否使用 SkipNonexistentTargets 優化收集這些專案。 未設定時,預設為 true 。 當無法匯入項目的目標時,後果是失敗的行為。 |
MSBuildProjectExtensionsPath |
輸出資料夾,預設為 BaseIntermediateOutputPath 和 obj 資料夾。 |
RestoreForce |
在 PackageReference 型專案中,強制解析所有相依性,即使上次還原成功也一樣。 指定此旗標類似於刪除 project.assets.json 檔案。 這不會略過 HTTP-cache。 |
RestorePackagesWithLockFile |
選擇使用鎖定檔案。 |
RestoreLockedMode |
以鎖定模式執行還原。 這表示還原不會重新評估相依性。 |
NuGetLockFilePath |
鎖定檔案的自定義位置。 預設位置位於項目旁邊,並命名為 packages.lock.json 。 |
RestoreForceEvaluate |
強制還原以重新計算相依性,並更新鎖定檔案,而不會有任何警告。 |
RestorePackagesConfig |
選擇加入參數,可還原具有 packages.config 的專案。只支援 MSBuild -t:restore 。 |
RestoreRepositoryPath |
僅限 packages.config。 指定要還原封裝的套件目錄。 SolutionDirectory 如果未指定,將會使用 。 |
RestoreUseStaticGraphEvaluation |
選擇加入參數,以使用靜態圖形 MSBuild 評估,而不是標準評估。 靜態圖表評估是大型存放庫和解決方案的實驗性功能。 |
RestoreUseLegacyDependencyResolver |
退出退出以使用舊版相依性解析程式。 NuGet的相依性解析程序實作已在 6.12 版本中重寫。 這個參數會強制使用先前的演算法。 |
屬性 ExcludeRestorePackageImports
是所使用的 NuGet內部屬性。
它不應該在任何檔案中 MSBuild 修改或設定。
命令列:
msbuild -t:restore -p:RestoreConfigFile=<path>
專案檔:
<PropertyGroup>
<RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>
還原會在組建 obj
資料夾中建立下列檔案:
檔案 | 說明 |
---|---|
project.assets.json |
包含所有套件參考的相依性圖形。 |
{projectName}.projectFileExtension.nuget.g.props |
MSBuild套件中包含的屬性參考 |
{projectName}.projectFileExtension.nuget.g.targets |
MSBuild套件中包含的目標參考 |
NuGet由於可以還原關閉MSBuild目標和屬性的套件,還原和建置評估會使用不同的全域屬性執行。 這表示下列專案會有無法預測且通常不正確的行為。
msbuild -t:restore,build
相反地,建議的方法是:
msbuild -t:build -restore
相同的邏輯會套用至類似 build
的其他目標。
使用 MSBuild 16.5+ 時,也支援 packages.config。msbuild -t:restore
msbuild -t:restore -p:RestorePackagesConfig=true
注意
packages.config
還原僅適用於 MSBuild 16.5+
,而非使用 dotnet.exe
注意
使用 MSBuild 16.6+ 時, NuGet 已新增實驗性功能,以從命令行使用靜態圖形評估,大幅改善大型存放庫的還原時間。
msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true
或者,您可以在 Directory.Build.Props 中設定 屬性來啟用它。
<Project>
<PropertyGroup>
<RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
</PropertyGroup>
</Project>
注意
自 Visual Studio 2019.x 和 NuGet 5.x 起,這項功能會被視為實驗性且加入宣告。 請遵循 NuGet/Home#9803 以取得此功能默認啟用時的詳細數據。
靜態圖形還原會 msbuild 變更還原的部分、專案讀取和評估,但不會變更還原演算法! 還原演算法在所有 NuGet 工具中都相同(NuGet.exe、 MSBuild.exe、dotnet.exe和 Visual Studio)。
在極少數的情況下,靜態圖形還原的行為可能會與目前的還原不同,而且某些宣告的 PackageReferences 或 ProjectReferences 可能遺失。
若要簡化您的心意,在移轉至靜態圖形還原時,請考慮執行:
msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore
NuGet不應報告任何變更。 如果您看到差異,請在 /Home 提出問題。NuGet
如果還原內含錯誤的組件,您可以排除該套件預設選項,並將其取代為您自己的選項。 首先,會有最上層 PackageReference
,但排除所有資產:
<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
<ExcludeAssets>All</ExcludeAssets>
</PackageReference>
接下來,新增您自己對 DLL 之適當本機複本的參考:
<Reference Include="Newtonsoft.Json.dll" />