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
PackageIconUrl 已被取代，有利於 PackageIcon 屬性。 從 NuGet 5.3 和 Visual Studio 2019 16.3 版開始，如果套件元數據只指定 PackageIconUrl，pack就會引發 NU5048 警告。
PackageIcon
提示
若要維持與尚未支援 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 圖示的參考。
PackageReadmeFile
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> 中繼資料。
針對封裝，若要在使用萬用字元模式時將檔案名稱附加至套件路徑，您套件路徑的結尾必須是資料夾分隔符號字元，否則會將套件路徑視為包含檔案名稱的完整路徑。
IncludeSymbols
使用 MSBuild -t:pack -p:IncludeSymbols=true 時，會複製對應的 .pdb 檔案與其他輸出檔案 (.dll、.exe、.winmd、.xml、.json、.pri)。 請注意，設定 IncludeSymbols=true 時會建立一般套件「和」符號套件。
IncludeSource
這與 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 的PackageLicenseExpressionPackageLicenseFile其中一個。
封裝沒有擴展名的檔案
在某些情況下，例如封裝授權檔時，您可能會想要包含沒有擴展名的檔案。 基於歷史原因， NuGet 請將 MSBuild 沒有延伸模組的路徑視為目錄。
<PropertyGroup>
<TargetFrameworks>netstandard2.0</TargetFrameworks>
<PackageLicenseFile>LICENSE</PackageLicenseFile>
</PropertyGroup>
<ItemGroup>
<None Include="LICENSE" Pack="true" PackagePath=""/>
</ItemGroup>
沒有延伸模組範例的檔案。
IsTool
使用 MSBuild -t:pack -p:IsTool=true 時，會將輸出組件案例中所指定的所有輸出檔案都複製至 tools 資料夾，而非 lib 資料夾。 請注意，這與 DotNetCliTool 不同，該項目是在 .csproj 檔案中設定 PackageType 所指定。
使用檔案封裝.nuspec
雖然建議您改為將通常.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
撰寫自定義目標，並將它指定為 屬性的值 $(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
撰寫自定義目標，並將它指定為 屬性的值 $(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>
Restore outputs
還原會在組建 obj 資料夾中建立下列檔案：
| 檔案 | 說明 |
|---|---|
project.assets.json |
包含所有套件參考的相依性圖形。 |
{projectName}.projectFileExtension.nuget.g.props |
MSBuild套件中包含的屬性參考 |
{projectName}.projectFileExtension.nuget.g.targets |
MSBuild套件中包含的目標參考 |
使用一個 MSBuild 命令還原和建置
NuGet由於可以還原關閉MSBuild目標和屬性的套件，還原和建置評估會使用不同的全域屬性執行。 這表示下列專案會有無法預測且通常不正確的行為。
msbuild -t:restore,build
相反地，建議的方法是：
msbuild -t:build -restore
相同的邏輯會套用至類似 build的其他目標。
使用 還原 PackageReference 和 packages.config 專案 MSBuild
使用 MSBuild 16.5+ 時，也支援 packages.config。msbuild -t:restore
msbuild -t:restore -p:RestorePackagesConfig=true
注意
packages.config 還原僅適用於 MSBuild 16.5+，而非使用 dotnet.exe
使用 MSBuild 靜態圖形評估還原
注意
使用 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" />