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不支援 來自 .nuspecMSBuild的和 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	目前使用者的使用者名稱	以分號分隔的套件作者清單，符合 nuget.org 上的配置檔名稱。這些會顯示在 NuGet 資源庫中 nuget.org，並用來由相同的作者交叉參考套件。
Owners	N/A	不存在於 nuspec
Title	Title	$(PackageId)	套件的易記標題，通常會用於 UI 顯示，以及 nuget.org 和 Visual 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有利於 。 不過，為了獲得最佳的下層體驗，除了 之外，您也應該指定 PackageIconUrlPackageIcon。
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	以分號分隔的套件作者清單，符合 nuget.org 上的配置檔名稱。這些會顯示在 NuGet 資源庫中 nuget.org，並用來由相同的作者交叉參考套件。
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用戶端最低版本，nuget.exe和 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屬性與使用 封裝有關：

1. NuspecFile：將用於封裝之 .nuspec 檔案的相對或絕對路徑。
2. NuspecProperties：以分號分隔的索引鍵=值組清單。 由於命令行剖析的運作方式 MSBuild ，必須指定多個屬性，如下所示： -p:NuspecProperties="key1=value1;key2=value2"。
3. 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> 

請注意， nuspec 使用 dotnet.exe 或 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 專案搭配使用) 會還原專案檔中所參考的套件，如下所示：

1. 讀取所有專案對專案參考
2. 讀取專案屬性來尋找中繼資料夾和目標架構
3. 將資料傳遞 MSBuild 至 NuGet。Build.Tasks.dll
4. 執行還原
5. 下載套件
6. 撰寫資產檔案、目標和屬性

目標 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 評估，而不是標準評估。 靜態圖表評估是大型存放庫和解決方案的實驗性功能。

屬性 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" />